Thanks for helping improve agent-device. This guide is the shortest path from a fresh checkout to a reviewable change. Detailed testing and device procedures live in the linked focused guides.
Requirements:
- Node.js 22 or newer
- pnpm at the version pinned in
package.json - Android SDK tools (
adb) for Android work - Xcode (
simctl/devicectl) for Apple-platform work
pnpm install
pnpm buildpackage.json's packageManager field is the source of truth for pnpm, and CI rejects a different
version. Node distributions that include Corepack can activate it with corepack enable pnpm.
Newer Node distributions may not bundle Corepack; in that case, install the pinned pnpm version
using your Node version manager or the pnpm installation guide, then
confirm it with pnpm --version before installing dependencies.
The root install does not install the much larger Expo test-app dependency graph. If your change
touches examples/test-app, install it separately:
pnpm test-app:install
pnpm test-app:typecheckpnpm build compiles the TypeScript CLI and library. If a running development daemon must pick up
that build, use pnpm rebuild:cli; it builds and then stops the worktree-scoped daemon.
Build only the Apple runner target you changed:
pnpm build:xcuitest:ios
pnpm build:xcuitest:macos
pnpm build:xcuitest:tvos
pnpm build:xcuitest:visionosAppend :clean to any platform build when DerivedData may be stale, for example
pnpm build:xcuitest:macos:clean. pnpm build:xcuitest remains the shared iOS-and-macOS gate for
changes that affect both runners; it is not an all-platform build.
Android and macOS helper builds remain separate because they require their native toolchains:
pnpm build:android
pnpm build:macos-helperThere is intentionally no catch-all development build. Native toolchains are expensive and
independent, so agents and contributors should run the command for the surface they changed.
Use pnpm build:macos-helper:clean if a Swift cache was created in another worktree.
pnpm publish and package-manager pack commands run prepack, which first checks synchronized MCP
metadata and then runs pnpm package:npm. This is the one completeness-oriented aggregate: it
builds the TypeScript distribution and all four Apple runner targets, clean-builds the macOS helper,
packages the Apple runner source, and rebuilds both Android helper APKs. Any failed build stops
packaging. It deliberately does not stop the worktree's development daemon; use pnpm rebuild:cli
when a running daemon needs to pick up a new TypeScript build.
pnpm package:npm is a release guard, not a routine development command. Use the specific commands
above while iterating.
release:publish runs release:mark-dev right after npm publish, moving package.json (and the
synchronized server.json) to the next patch with a -dev prerelease marker (for example
0.20.11-dev). Commit that bump as part of the release. The invariant it protects: MCP registry
scanners diff the repository's tool surface per version string, so a released number left on main
while main keeps changing is indistinguishable from a republished ("rug-pull") version.
release:prepare enforces the inverse direction and refuses to publish while the -dev marker is
still in place — set the real release version first (for example npm version patch, which strips
the prerelease marker), commit, then publish.
Compatibility gates baseline against the last released tag, not against main, so publishing is
what advances them — there is no separate baseline-refresh step and no regenerate command. Tagging a
release makes that commit's test/wire-compat/ledger.json the new baseline for
pnpm check:daemon-wire-compat, and its .ad corpus tags the new ceiling for
pnpm check:replay-compat. The practical consequence for a normal PR: wire churn within an
unreleased branch is free, and only the net change since the last publish has to carry a
DAEMON_RPC_PROTOCOL_VERSION bump or a compatibleChanges acknowledgment. After a release that
bumped the protocol version, the acknowledgments accumulated against the previous one no longer
match any current digest and are dropped — git history keeps the audit trail.
Use the smallest trustworthy loop while editing:
pnpm check:quick # lint + TypeScript
pnpm test:maestro-compat # example of a focused family suite
pnpm exec vitest run path/to/file.test.tsBefore pushing a normal code change, let the repository derive the required gates:
pnpm check:affected --runThe selector combines the committed diff with staged, unstaged, and untracked files. Unknown, workflow, lockfile, and selector-owning changes fail open to the full local set. It reports device/toolchain checks that remain GitHub-authoritative instead of trying to run them implicitly.
For broad refactors or when explicitly requested, run the deterministic core aggregate:
pnpm checkpnpm check covers formatting, lint, typechecking, layering, dependency-graph parity, production
exports, MCP metadata, the distributable build, bundle ownership, Fallow, unit tests, and local smoke
tests. It is intentionally not a simulation of every CI job: coverage, provider integration,
history-backed compatibility, specialized toolchains, and live device/browser lanes remain separate.
GitHub CI is authoritative.
Useful direct entry points:
pnpm testorpnpm test:unit— root unit projectspnpm test:coverage— coverage plus coverage-only projectspnpm test:integration— Node and provider-backed integration suitespnpm perf --platform iosorpnpm perf --platform android— device performance harnesspnpm check:fallow --base origin/main— changed-code quality gatepnpm fallow:all— full-tree audit, including grandfathered baseline findingspnpm fallow:baseline— intentionally regenerate both reviewed Fallow baselines
See docs/agents/testing.md for gate ownership, shared test utilities,
mutation/fuzz lanes, contention policy, and test-speed rules. For real devices, follow
docs/agents/device-verification.md; a fixture-backed test does
not prove that a native path was active.
The Expo fixture app owns its setup, simulator/device, Metro, replay, and Maestro instructions in
examples/test-app/README.md.
The stable compatibility entry points are:
pnpm test:maestro-compat
pnpm maestro:conformance
pnpm test-app:maestro:ios
pnpm test-app:maestro:androidThe first two are deterministic and device-free. The test-app suites need the app, Metro when applicable, and a real simulator or emulator.
- Keep dependencies minimal and prefer built-in Node APIs.
- Preserve the CLI's compact, agent-friendly JSON output.
- Open and close sessions explicitly in tests and manual verification.
- Add or adjust integration coverage when introducing a command or changing a wire response.
- Run the focused gate that owns the behavior; do not replace missing coverage with a broad, assertion-free test.
When code deliberately chooses a slower or more conservative path, leave a short comment at the
decision site naming the prevented failure and the condition for revisiting the choice. Use the
grep-able CONSERVATIVE: prefix when the decision is expected to outlive the current change.
// CONSERVATIVE: Preserve external runner artifacts because the checkout does not own their cache
// root. Revisit only if external artifacts get an ownership marker that makes cleanup safe.Renovate proposes weekly lockfile maintenance, grouped development-dependency updates, individual runtime-dependency updates, and GitHub Action digest bumps. Automerge is disabled: dependency PRs need green CI and human review.
Read the release notes, inspect the affected-check plan, and treat a green update as a merge candidate rather than an automatic merge:
pnpm check:affected --runIssue labels describe workflow state, not ownership. See
docs/agents/triage-labels.md.
When reporting a problem, include the OS and Node version, relevant Xcode or Android SDK versions, and the exact command and output.