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.13 or newer — the pinned pnpm requires it. The published package keeps a lower
engines.nodefloor of 22.12, which CI verifies separately on the installed tarball. - 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.
pnpm clean:daemon retains state when it cannot confirm the recorded daemon exited. Restore
process inspection or stop the verified owner before retrying. Its --prune-dev option considers
dev state directories whose newest observed modification is at least 14 days old. It retires
confirmed abandoned registrations and keeps session artifacts and state directories for inspection.
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.
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 (into a scratch directory under
.tmp/ that it removes afterwards, not into ~/.agent-device), 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.
That Android leg needs AGENT_DEVICE_ANDROID_BUILD_TOOLS naming the build-tools version to compile
with. An unpinned build takes the newest version installed on the machine, which CI refuses to do,
so name the version the CI lanes install and the published helper matches the CI-built one.
pnpm package:npm is a release guard, not a routine development command. Use the specific commands
above while iterating.
Every release publishes from .github/workflows/release.yml, through npm trusted publishing: no
npm token or one-time password is involved, and every release version carries provenance. The one
exception is the empty 0.0.0 placeholder a maintainer publishes by hand to onboard a new package,
described below. A local npm publish from the repository root refuses to run.
The core and every public workspace package release together at one version. Private packages stay unpublished. There are three channels:
- Nightly (
npm install -g agent-device@nightly): every few hours the workflow checksmain. It publishesX.Y.Z-nightly.<YYYYMMDD>.<run>under thenightlydist-tag whenmain's HEAD has changed since the last nightly, its CI passed, and no nightly shipped that UTC day. It then tags the commitnightly/v<nightly version>. To publish one now, run Release onmain. - Stable (
latest): a repository admin publishes a GitHub release with a newvX.Y.Ztag targetingmain. Use the versionmainbuilds towards (itsX.Y.Z-dev), or a later one, and write the notes or generate them in the release form. The tag starts a Release run. It waits up to 20 minutes for that commit's CI to pass, then waits for approval in thereleaseenvironment. Once approved, it publishes the packages, attaches the iOS runner and Android helper assets to the release, publishes the MCP Registry entry, and commitsmain's next-devversion. If you reject the run, delete the release and its tag. Pushing the tag instead (git push origin main:refs/tags/vX.Y.Z) starts the same run, which then drafts the release itself. - Dry run: a pull request that changes release tooling builds and verifies every package with a nightly version, and publishes nothing.
To retry a failed run, re-run its failed jobs, or run Release on the release tag. The
publisher skips package versions that are already on npm, so a partial publish completes on the
next attempt. To preview the packages locally, run
pnpm release:prepare. It builds, verifies, and packs every public package into .tmp/release.
A public package owns its files, published exports, license, repository metadata, README,
and prepack build (including any prerequisites). Use publishConfig.exports for source-only
workspace test exports; pnpm applies the overrides when packing. Keep plugin SDK imports and
bundled workspace helpers in devDependencies. Plugins must not depend on the core at runtime
or through a peer dependency. Their factories receive the host from agent-device.
When adding a public package, initialize its version from the root package.json; the release
workflow stamps the release version into every public package. An optional plugin must have no
production import from the core build or production dependency in the root manifest. Run its
packed-install smoke before releasing. npm can only trust a package that exists, so a maintainer
publishes an empty 0.0.0 placeholder once and grants the trust before the next nightly:
cd "$(mktemp -d)"
echo '{"name":"@agent-device/<name>","version":"0.0.0","license":"MIT"}' > package.json
npm publish --access public --tag reserved
npm trust github @agent-device/<name> --file release.yml --repository callstack/agent-device \
--environment npm-publish --allow-publish --yes
npm access set mfa=publish @agent-device/<name>npm trusts every run of release.yml that reaches the npm-publish environment, so GitHub
settings, not the workflow, decide who can publish. The plan job refuses to publish until the first
three are in place. Apply them before granting npm trust:
- Environment
npm-publish(Settings → Environments): deployment branches and tags limited to the branchmainand the tag patternv*. No reviewers and no secrets, so nightlies run unattended. - Environment
release: required reviewers. Turn on "Prevent self-review" only when another maintainer can approve, because the admin who creates the tag cannot approve their own run. - Tag ruleset (Settings → Rules → Rulesets → New tag ruleset): active, targeting
refs/tags/v*with no exclusions, restricting creations, updates, and deletions, with only the Repository admin role allowed to bypass. Nightly tags live undernightly/and stay outside it. - Actions (Settings → Actions → General): workflow permissions set to read repository contents, and "Allow GitHub Actions to create and approve pull requests" turned off.
- Releases (Settings → General): leave release immutability off, because the run attaches its assets after the release is published.
Confirm the result, then grant npm trust to each public package and, once a nightly has published, refuse token-based publishing:
gh api repos/callstack/agent-device/environments/npm-publish/deployment-branch-policies \
--jq '.branch_policies[] | "\(.type) \(.name)"' # branch main, tag v*
gh api repos/callstack/agent-device/environments/release \
--jq '.protection_rules[] | select(.type == "required_reviewers")'
gh api repos/callstack/agent-device/rulesets --jq '.[] | select(.target == "tag") | .name'
npm trust github <package> --file release.yml --repository callstack/agent-device \
--environment npm-publish --allow-publish --yes
npm access set mfa=publish <package>Anyone who can push to main can still change what the next nightly publishes; main does not
require pull requests.
main carries X.Y.Z-dev, naming the release it is building towards. Nightlies preview it as
X.Y.Z-nightly.*, and only a stable release publishes X.Y.Z. After a stable release, the workflow
moves main to the next patch's -dev version, unless main already builds towards a later
release. To plan a minor or major release, commit the new -dev version to main (for example
0.22.0-dev); nightlies then preview it. The invariant protects MCP Registry scanners, which diff
the repository's tool surface per version string: a released number left on main while main
keeps changing is indistinguishable from a republished ("rug-pull") version.
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 check:coverage-crap --base origin/main— CRAP from measured coverage for the functions a change touches; it fails when one scores 30 or more, so runpnpm test:coveragefirst.--allreports every function and never fails: that ismain's backlog. Both list the file-widefallow-crap.jsonexemptions they honoured.check:fallowleaves CRAP off without coverage.pnpm 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.
check:coverage-crap --base <ref> scores the functions whose lines your diff adds, so it also
fails when it cannot score them. It prints no trustworthy verdict and names the files when
coverage/coverage-istanbul.json is missing, malformed, or records fewer files than the same run's
coverage/lcov.info enumerated; when a file you touched was dropped as corrupt or never recorded;
or when a touched function postdates the map and would be scored from complexity alone. Every one of
those is a stale coverage run, not a debt you owe: re-run pnpm test:coverage on the commit and
re-check. What does count as debt is editing a function that already scores 30 or more — the score
does not have to be new. Only lines you add are charged, so removing them is not: deleting a whole
function takes its score with it, and deleting lines from one is not charged however it moves the
score — a deletion that drops lines which used to be covered can raise what the function scores, and
that debt reaches the --all backlog rather than your PR. Moving a file without editing its lines
touches none of its functions. Unlike the changed-line gate, this one has no coverage-waiver label:
the only way past a score is to test or simplify the function, or to exempt the file in
fallow-crap.json.
Two things are listed rather than blocked, so a green run does not mean they were checked. A touched
function in a file coverage never instrumented — one coverage.exclude drops, or one a stale local
coverage/ never enumerated — is reported as not measured and stays non-blocking: no re-run would
score it, and blocking on it would refuse every tooling PR. And an estimate is only ever compared
against 30: a touched function the map predates is named as no-verdict, or listed as unmeasured, only
when its estimated score reaches that bar, so a below-bar guess about new code is reported by neither.
A coverage run you re-ran is what turns either one into a measured score.
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.