Autohand Code CLI
Continue Autohand Code from your iPhone
Run /go to pair the active CLI session with the Autohand Code iOS app. Scan the terminal QR code to submit prompts, answer approvals, use supported composer commands, inspect delivery status, and receive the final result from your phone.
Canonical command: Use /go for mobile pairing. /handoff session remains as a compatibility command behind the experimental_handoff feature flag.
Before you pair
- Sign in to Autohand Code with
/login. - Start a conversation so the current workspace has an active session.
- Install and sign in to the Autohand Code iOS app.
- Keep the CLI running while you want live mobile control.
Pair the current session
/goThe CLI registers this computer, creates an expiring pairing, and prints:
- a high-contrast QR code for reliable camera scanning;
- a pairing URL and native-app simulator fallback;
- the current project and session identifiers;
- the selected relay mode and expiry time.
In an interactive CLI session, /go defaults to live steering. In a non-interactive surface without an instruction queue, it defaults to queue mode.
Choose live steering or durable queue mode
| Command | Behavior | Use it when |
|---|---|---|
/go --steer |
Keeps a relay attached to the live interactive session and runs phone prompts through that CLI. | You are leaving the terminal open and want real-time control. |
/go --queue |
Creates a durable queue-only handoff. Phone prompts wait for a compatible CLI worker. | The current surface cannot steer interactively or you want work to remain queued. |
--steer requires an interactive CLI session. If the current mode cannot accept instructions, use /go --queue.
Phone and terminal work stay ordered
Prompts and mobile composer commands share the same serialized work stream as text submitted in the terminal composer. Autohand processes them one at a time in submission order, including when the phone and terminal submit while another turn is active.
Each claimed mobile turn reports running, completed, failed, or cancelled state. Final results are correlated to the originating mobile work item and retried through the relay-safe delivery path when a transient publish attempt fails.
Use supported composer commands
The iOS app receives a versioned command catalog from the live CLI. Suggestions use current command names, descriptions, subcommands, and availability instead of a hard-coded phone list.
| Command | Mobile forms | Boundary |
|---|---|---|
/plan |
on, off, status |
Requires one explicit allowed subcommand. |
/goal |
A plain objective, writer, or templates |
Goal controls, flags, and local template execution are rejected. |
/deep-research |
A topic or status |
Command flags are not accepted from mobile. |
/autoresearch |
An objective, status, history, pareto, or off |
Destructive ledger controls, evaluator commands, and flags remain terminal-only. |
/automode |
on, off, status, pause, resume, cancel |
Requires one explicit allowed subcommand. |
A command is executable only when it is both mobile-permitted and enabled in the current CLI session. For example, /goal becomes available only when goals are enabled.
Handle approvals and permission modes
The paired app can answer permission, directory-access, change-review, and follow-up requests. Permission choices remain correlated to the pending CLI request and support one-time or session decisions plus a suggested alternative.
After the pairing has been claimed, the phone can request the CLI's canonical interactive, restricted, or unrestricted permission mode. Failed changes are reported back and rolled back when necessary.
Find files and send images
The iOS app can query file names inside the active workspace. Queries are bounded, time-limited, and return relative paths only. Real-path containment prevents symlinks from exposing files outside the workspace.
Mobile prompts may include PNG, JPEG, GIF, or WebP images. The CLI validates the MIME type and encoded payload before adding the image to the active instruction.
Resume an exact historical session
A mobile task may explicitly request a fresh session, continue the active session, or resume history. Resume requires an exact locally stored session ID for the current workspace.
If the session does not exist or belongs to another workspace, the task fails. Autohand does not silently start a fresh conversation or continue a different session. The phone stays paired to the existing CLI connection while progress and results identify the resumed agent session.
Review delivery status
When GitHub CLI data is available, live steering can publish read-only pull-request, check, and deployment status. Missing gh authentication does not stop the coding session.
A ready pull request can be squash-merged from the phone only after explicit confirmation. The CLI re-fetches the current pull request and rejects the merge unless the reviewed number and head branch still match, the pull request remains open and mergeable, and every reported check passes.
When the agent explicitly references generated PNG/JPEG, MP4, text, or JSON artifacts inside the workspace, the relay can upload up to 12 files with a 15 MB limit per file.
Keep the Mac available
On macOS, live steering starts with a CLI-owned keep-awake assertion so the computer does not sleep during a mobile run. The phone can turn this behavior on or off. Autohand always releases the assertion when the relay stops or the CLI exits.
Troubleshooting
| Message | What to do |
|---|---|
Sign in first with /login |
Complete authentication, then run /go again. |
| No active session to pair | Send a prompt in the current project before pairing. |
| Steer mode requires an interactive CLI session | Start the interactive CLI or use /go --queue. |
| Could not create mobile handoff | Check network access, authentication, and the configured api.baseUrl or AUTOHAND_API_URL. |