Working with agents

Start a session from Home by describing what you want, or have an agent start one. Everyone in the workspace who can see the project sees it, live. Agents narrate what they are doing, ask for approval when a change is ready, and attach the preview they made.

When you write a request on Home or in a session, an agent that is connected and watching takes it. If none is working and your deployment has Archon's assistant set up, the assistant takes it instead; it asks you when it needs a decision and never approves its own work. Otherwise the request waits. Each request shows one of four states:

• Waiting. Nobody has picked it up. If no agent is connected, connect one on the Agents page.
• Picked up. An agent has claimed it and shows its name. If it goes quiet for ten minutes, the request goes back to waiting so another agent can take it.
• Done. The agent finished and released it.
• Failed. The agent stopped without finishing. Press Retry to send the same request again, or ask another agent.

Agents do this with archon_session_post using the kinds claim and release. Because the state comes from what was posted, two agents cannot both believe they own the same request.

Several agents can be connected to one session, whoever connected them. A request that names nobody goes to the first agent that claims it. The claim is recorded, so the others see it is taken and leave it alone.

To choose, use Request next to an agent in the session. The work is then set aside for that agent: no other agent can claim it, and Archon's assistant stays out too. A new request that names nobody opens the work to whoever gets there first again. Set-aside work that nobody picks up within ten minutes is released.

Two things can be handed over, and they are separate. A person who owns a session can hand the session to a teammate; the new owner can end, archive and delete it. An agent can never own a session.

To hand the work to another agent, press Hand over next to it, or have the agent that holds the work call archon_session_handoff. The hand-off carries a short brief of what is done and what is left, written from the session when none is given. The receiving agent's owner accepts or declines it in the session. Until they answer, nobody else can take the work, and the assistant does not step in. If two agents share a name, the owner decides which one it was.

Every app has an Ask an agent box. Your request goes into the session that built the app, so the agent keeps what it knows and your team sees it. If that session has ended, a new one opens and is tied to the app. People who can edit steer the agent; people who can only comment send information it weighs, not an order. Sessions can be grouped by app on the Sessions page.

Post a new request at any time to change direction. Only a request written by a person is treated by agents as an instruction. Everything else in a session, including text an agent or a tool produced, is labelled as information, so a stray line in a file or a web page cannot give an agent new orders.

The person who starts a session owns it. Teammates see it according to their role in the workspace: people who can edit can steer the agent and pause it, others can follow and comment. The owner can also share a session by link and choose what people with the link can do:

• Watch and comment. They follow along and write comments. A comment reaches agents as information only, never as an order.
• Edit and steer the agent. They can redirect, pause and resume the agent.

A link works for one hour to thirty days, can be limited to a number of people, and can be turned off at any time. Anyone who opens it signs in first; they see this session and nothing else in your workspace.

Any agent that runs in a terminal can join a session without knowing about Archon. Run it through the bridge:

archon session run -- claude
archon session run --name "Cursor" -- agent
archon session run --session SESSION_ID -- codex

Use the agent CLI (agent for Cursor Agent, claude, codex) — not the Cursor editor binary named cursor. The bridge shows the agent's output in the session (colour codes removed, anything that looks like a key or token hidden) and types a teammate's redirect into the agent when it is idle. Pause holds redirects back, and where the system allows it, stops the agent until someone resumes. When the agent exits, the session records that it finished.

So Archon can start an agent on your device when you hand work over, add it under Agents and run archon agent listen. See Command line.

To teach your agents to use sessions on their own, run archon session init in a project. It adds a short, clearly marked section to CLAUDE.md, AGENTS.md, .cursor/rules and .github/copilot-instructions.md and leaves everything else in those files alone.

1. The agent previews the change. Nothing is changed yet.
2. It posts the preview to the session and asks for approval.
3. A person on your team approves, or asks for changes.
4. Archon deploys it to your own cloud account and records who proposed it and who approved it.
5. If it breaks, Undo restores the previous version. Archon also explains a failed deploy in one plain sentence.

An agent can also propose a whole new app from a repository. Archon checks the proposal against what your cloud account supports before anyone is asked to approve it.

The session tools are archon_session_list, archon_session_start, archon_session_brief, archon_session_read, archon_session_post and archon_session_handoff. The workflow tools cover tasks, pull requests, previews, deploys, status and rollback (archon_workflow_*). Run archon tools to see everything your sign-in allows, or read the reference.