Skip to content

Contributing

AutoMobile welcomes contributions!

If you have a question file an issue or discussion, but small contributions like documentation improvements, small obvious fixes, etc don’t need prior discussion. If you see a TODO go for it. For larger functionality changes or features, please raise a discussion or issue first before starting work. Read the system design overview to see how the pieces fit together. Almost everything in CI can be run locally, check out the scripts/ directory. After you’ve forked and cloned the project, set up your local development environment. We expect contributors to be active users of Claude Code or some other AI tool.

Ways to Contribute

Type Description
Bug reports File issues with reproduction steps
Feature requests Propose new capabilities via issues
Documentation Improve guides, fix typos, add examples
Code Bug fixes, new features, performance improvements

Code Guidelines

  • TypeScript only - Never write JavaScript
  • Run validation - bun run lint and bun test before submitting. If modifying Android or iOS code check for appropriate validation scripts in the scripts/ directory
  • Keep PRs focused - One feature or fix per PR
  • Add tests - Cover new functionality with tests
  • Prefer standard and existing code - Before adding a dependency or a generic utility, check the JavaScript/Node standard library and src/utils/. Keep time, randomness, I/O, concurrency, and process access behind an interface with a fake when tests need control. Every new dependency needs a short decision record under docs/decisions/ that bun run check:stdlib-first verifies.

Pull Request Process

  1. Create a branch from main
  2. Make your changes with tests
  3. At a minimum run scripts/all_fast_validate_checks.sh. If modifying Android or iOS code check for appropriate validation scripts in the scripts/ directory
  4. Submit PR with clear description
  5. Address review feedback

Local Development

Components Script
Desktop, Android, iOS, MCP daemon bash scripts/local-dev/hot-reload.sh

The four package scripts (dev:android, dev:android:hot-reload, dev:ios, and dev:ios:hot-reload) are aliases for this unified watcher; none limits the run to one platform.

Options:

  • --device <id> - Target a specific ADB device
  • --simulator <udid> - Target a specific iOS simulator
  • --once - Build all components once and exit
  • --poll-interval <s> - File watch interval in seconds (default: 2)
  • --timeout <m> - Background watcher timeout in minutes (default: 60)
  • --manage-ios-runner - Let the watcher own the CtrlProxy iOS runner lifecycle (default: the MCP daemon owns it)
  • --help - Show help

The script writes logs to scratch/, auto-detects ports based on your git branch, and automatically enables debug flags (AUTOMOBILE_DEBUG, AUTOMOBILE_DEBUG_PERF).

Verifying Setup

In Claude Code, run /mcp to check the connection status. A successful setup looks like:

╭─────────────────────────────────────────────────────────────────────╮
│ Auto-mobile MCP Server                                              │
│                                                                     │
│ Status: ✔ connected                                                 │
│ Auth: ✔ authenticated                                               │
│ URL: http://localhost:9000/auto-mobile/streamable                   │
│ Config location: /path/to/your/worktree/.mcp.json                   │
│ Capabilities: tools · resources                                     │
│ Tools: 44 tools                                                     │
╰─────────────────────────────────────────────────────────────────────╯