Driving an app with agent-bridge

The app mounts useAgentBridge({ tools }) in a dev build. You call those tools by name. Nothing is tapped, so there is no setup to click through.

Pair it with agent-device

agent-bridge works inside the app's JavaScript; agent-device works the device. Use both, each for what it's good at:

A typical run: agent-device open the app, set up and check the screen with agent-bridge, then finish with one real tap or a screenshot from agent-device. Don't tap through setup screens or edit backend data to reach a state that one bridge call can set.

Run the CLI directly

The examples say npx @avasapp/agent-bridge; never drop the scope, because agent-bridge on npm is an unrelated package. Prefer the installed bin, ./node_modules/.bin/agent-bridge (with bun too): npx loads npm's config on every call, so a project .npmrc with keys npm doesn't know prints npm warn Unknown project config into your output each time, and it adds roughly 200 ms more startup per call (machine-dependent).

Start a session

npx @avasapp/agent-bridge session start            # add --metro host:port if Metro isn't on localhost:8081
npx @avasapp/agent-bridge tools                    # what this app exposes

If Metro runs on another port, pass the same --metro (or set AGENT_BRIDGE_METRO) on every command that doesn't go through the session. A Nothing is listening on … error names the Metro it found instead and its apps; check it's yours before switching to it.

A session holds one connection for all your calls. It stops itself after 15 minutes without calls and runs bridge.restore when it does.

A JS reload (an error screen's Retry, or app.reload) throws away every pending restore. The session notices the app is a new runtime and reports app reloaded; N pending restores lost: store, query (the areas that had something to undo) as a warning on the next call (also on a failed one) and again in session stop. When you see it, redo your setup: nothing you changed before the reload will be undone.

If a call fails with app not connected; reconnecting or The app is gone, the session lost the app (Metro or the app is down, or mid-reload). It retries on its 5 s health check and on your next call: wait a few seconds and call again. session stop still works. A session never moves to another app: <app> is not connected; connected: … means its app is gone and something else is there.

If tools fails with "agent-bridge isn't running", the hook isn't mounted in this build. Say so; don't fall back to tapping silently.

If the app doesn't have the package or a bridge file yet, run npx @avasapp/agent-bridge init --json in the app (--dir apps/x from a monorepo root). It writes src/dev/agent-bridge.tsx but never edits the root layout: paste mount.snippet into mount.file as mount.note says. Ask the user about each entry in choices it reports as open (such as network tools), then rerun with the flag it names, or add its lines by hand when there's no flag. Then follow next, from runFrom.

Start from a scenario

Apps can define named setups, such as a locally signed-in user. Use one instead of signing in by hand or seeding auth state yourself:

npx @avasapp/agent-bridge scenarios                                        # what this app defines
npx @avasapp/agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'

scenarios shows each one's options as a JSON Schema. Bad options fail before anything changes, and the error lists every problem (options: unknown option "usr". Known: user): fix them and apply again. bridge.restore (and session stop) undoes it after everything else.

A local scenario usually turns on strict network mode: any request no mock answers fails with a 501, and the reply carries an error that names it (! error during …: agent-bridge strict network: no mock for GET https://…). Add a mock for it (net.mock), don't turn strict mode off.

If the app has no scenario for the state you need, say so. Don't sign in to a real account instead. If you're asked to add one, read references/writing-scenarios.md.

See and use the screen

npx @avasapp/agent-bridge call screen.snapshot                       # buttons, inputs, text on the focused screen
npx @avasapp/agent-bridge call screen.press '"add-plant"'            # by testID, label or text
npx @avasapp/agent-bridge call screen.fill '["plant-name", "Fern"]'  # runs the input's handlers
npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'   # {"gone": true} waits for it to go
npx @avasapp/agent-bridge call router.navigate /inbox

press and fill return once the app has rendered the result, so the next check sees it. Arguments are a JSON array (or a single JSON value): the array is spread into the tool's arguments.

Watch for errors

Every reply carries errors the app logged or threw since the previous reply, printed as ! error during <tool> or ! error after <tool>. Treat them as failures of the step they name. npx @avasapp/agent-bridge call bridge.logs shows the last 200 errors and warnings.

Clean up

npx @avasapp/agent-bridge call bridge.pending      # what restore will put back, per area
npx @avasapp/agent-bridge session stop             # runs bridge.restore; --keep leaves the app as is

bridge.restore unpins queries, puts back store values, removes network mocks, unmutes realtime channels, then undoes active scenarios, so the next run starts from the real state.

Read more when you need it

The app may expose its own tools for hooks the bridge has no tool for (queue.flush, realtime.reconnect); tools lists them. There is no app.eval: if the app has no tool for it, say so.

Caveats

• It can't see native UI (system alerts, permission prompts, native sheets) or overlap. Finish a flow with one real UI check or screenshot from agent-device.
• fill skips the keyboard: autocorrect and native-only input behaviour need one real typing step from agent-device.
• Swipe and drag gestures need agent-device, unless the control is screen-reader operable: press sends its activate accessibility action (see references/screen.md).
• With several apps on one Metro, pass --device.