Agents

An agent is the coding tool a session actually runs. actor.sh drives any agent through a small contract — start a process, deliver a prompt, report turn boundaries via hooks, resume across turns, and pick up the right credentials — so support is a matter of teaching it that agent's specifics. Two are supported today, Claude and Codex, and the list is meant to grow.

You interact with actor.sh through Claude — the main session is itself a Claude conversation — but the sessions it spawns can run any supported agent, chosen per session.

Supported agents

Claude

The default. Each Claude session is a real claude process, launched with actor.sh's MCP server and coordination prompt wired in.

• System prompt is delivered via --append-system-prompt, so a role's identity rides alongside Claude's own behaviour.
• Resuming: persistent sessions are pinned to a stable Claude session id up front and re-attached with --resume on each run, so they keep their full history across turns.
• Hooks: Claude reports lifecycle moments through its UserPromptSubmit, Stop, and SessionEnd hooks, which actor.sh maps to turn-start, turn-end, and session-end. That's how completions reach main.
• Auth: by default Claude uses whatever credentials its CLI has. Set use-subscription to run on a subscription instead of an API key — actor.sh drops ANTHROPIC_API_KEY from the agent's environment so the subscription is used. See Configuring Claude.

Codex

OpenAI's codex. The interactive entry point is always actor claude — there is no Codex main session — but main (or you, via the CLI) can spawn worker sessions that run Codex:

actor new migrate --agent codex --prompt "Port the config loader to the new schema."

Codex meets the same contract through different mechanics, which actor.sh handles for you:

• Developer instructions stand in for a system-prompt flag: a role's prompt is delivered as a Codex -c config override on the collaboration mode.
• Hooks: Codex reports turn-start and turn-end (it has no session-end hook), injected as Codex config overrides.
• Resuming uses Codex's own session/thread identity.
• Auth: like Claude, use-subscription drops OPENAI_API_KEY so a subscription login is used. See Configuring Codex.

Choosing per session

The agent is chosen per session — by --agent on actor new, by agent: in the new_session tool, or by a role that pins one. A single main session can coordinate a mix of agents in the same project.