Review agent work and return feedback
Open the original simulator or emulator from a review link, test in the portal or iOS companion, and return feedback to Codex or Claude Code.
A test handoff connects a review to a registered developer computer, an exact simulator or emulator, an app, and the agent conversation that produced the work. The same HTTPS link opens the review in the web portal or the iOS companion app. Sign in with the Ansight account that owns the registered computer.
Publish work for review
Sign in to the CLI, enable companion access on your Mac, and keep the host running:
ansight auth login
ansight host run --companion-access session --machine-name "Development Mac"
The machine must be approved for companion access. Start the simulator or emulator and install the app before publishing. Remote video uses the host’s existing device preview requirements. These links do not add remote control support to physical devices that the companion cannot stream.
After building and testing, the agent can publish a handoff:
ansight companion handoff create \
--provider codex \
--thread-id "<original-thread-id>" \
--workspace "/absolute/path/to/project" \
--device-id "<simulator-or-emulator-id>" \
--app-id "com.example.app" \
--build-id "<commit-or-build-revision>" \
--title "Review checkout validation" \
--summary "Checkout now explains missing address fields." \
--checks "Submit an incomplete address, then complete it and retry."
The result includes a URL such as https://app.ansight.ai/handoffs/<handoff-id>.
Include that URL in the agent’s completion message. Publishing also queues a push
notification for the account’s enabled iOS installations.
--build-id is a label supplied by the agent; it is not an attestation of the
installed binary. Publish a new handoff after replacing the build. To require
the original live capture session, include --session-id <id>.
| Option | Purpose |
|---|---|
--provider codex or --provider claude | Select the return adapter. |
--thread-id <id> | Pin the original Codex thread or Claude Code session. |
--workspace <absolute-path> | Run the return adapter in the original workspace. |
--machine-id <uuid> | Select this computer’s approved registration when needed. |
--session-id <id> | Require the exact live app capture session during review. |
--agent-executable <path> | Select the installed Codex or Claude Code executable if it is unavailable on the host’s PATH. |
--codex-socket <absolute-path> | Connect to a specific existing Codex app-server control socket. |
--turn-id <id> | Retain the originating turn alongside the conversation. |
--notify false | Publish without queuing a push notification. |
--id <uuid> | Reuse the same request ID when retrying an identical publication. |
Test in the portal or companion
Open the link, sign in with an account that has companion access, and choose Test in browser or Open device to test. The review retains the requested computer and device. If the target or app is unavailable, restore it on the developer computer and reconnect. Ansight does not substitute another running target. Links expire after seven days.
Use the inbox icon in the iOS app’s header to find handoffs without a notification. In the portal, open a review link and use Companion reviews to see your other handoffs. An active iOS review adds a small indicator to the inbox icon. In the iOS app, choose Notify me when work is ready and allow notifications. You can turn off handoff notifications from the same inbox or manage system permission in Settings. Notification text contains no build details or feedback; opening it requires authenticated access to the handoff.
Write feedback and optionally mark the screen with a drawing. In the portal, choose Annotate, draw with a mouse, finger, or pen, and enter an Annotation note describing the marked area. Attach drawing adds it to your review. Drawing freezes the captured frame, so your marks do not control the remote app. Use Undo or Clear to revise the marks before attaching them.
In the iOS companion’s annotation mode, draw on the frozen image and choose Add note. Enter a note, then choose Add Another or Review Set. You can return to the drawing without losing your draft or edit a note from the set.
Annotations require a live Ansight capture session on the target and retain session, frame, and annotation references for the agent. In the review, choose Looks good or Request changes to queue feedback for the original conversation.
Return to Codex or Claude Code
Keep Ansight companion access enabled on the original computer. The host receives queued feedback and uses the local agent connection saved when the handoff was published. Agent executable paths and workspace paths stay on that computer.
For Codex, the installed CLI must support codex queue. Ansight queues the verdict,
feedback, build label, and evidence references to the registered thread, including
when that conversation is already working.
With --codex-socket, Ansight instead uses codex app-server proxy to connect to
that existing app-server, resume the registered thread, and start a turn. This
direct mode reports an active thread as needing attention. The socket must belong
to the server that owns the original conversation.
For Claude Code, Ansight invokes claude --resume <session-id> --print in the saved
workspace. Claude must already be signed in, and the session must be available
locally. Existing tool permissions still apply. Permission denials are reported
in the review’s delivery status.
| Status | Meaning |
|---|---|
| Queued | Stored durably; waiting for the registered host. |
| Dispatching | The host claimed the feedback and is contacting the provider. |
| Accepted | Codex confirmed the queued message or accepted the direct turn, or Claude Code completed processing the resumed request. This does not mean a requested fix has passed review. |
| Needs attention | Check the original conversation and host before submitting again. Delivery may already have reached the provider. |
If the host stops during delivery, Ansight does not automatically resend an ambiguous submission. After the claim times out, its status becomes Needs attention when the host next checks the queue.
Inspect or revoke a handoff
ansight companion handoff list
ansight companion handoff get <handoff-id>
ansight companion handoff revoke <handoff-id>
Revocation prevents new review submissions and queued deliveries. It cannot undo feedback already delivered to an agent. Revoking the machine or losing the organisation’s companion access also removes access to its handoffs.