axiopera: run other coding agents (claude, codex, grok, agy) as your sub-agents.
Use axiopera for a different agent or model, or for work that must continue after your
session ends.
@user
@user axiopera takes you for `user`, the person at a terminal. An agent must not act as `user`:
@user when your session variable does not reach axiopera (over ssh, in a container) or axiopera
@user does not recognize your agent, add `--caller <agent>:<session ID>` to every command, e.g.
@user `ssh host axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" inbox`. Claude Code, Codex and
@user Grok keep the ID in CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID and GROK_SESSION_ID. AGY uses ANTIGRAVITY_CONVERSATION_ID. An agent
@user without one generates a random ID once and keeps using it.
Dispatch
axiopera spawn codex "Fix the failing test in tests/parser.rs."
axiopera spawn claude --tier read --name review -f task.md
Tiers: read (read-only; requests needing approval are refused;
MCP: read-only tools only, none on Grok, Axiopera directory listing and communication tools on AGY; Grok shell: plain axiopera commands only),
work (default: the agent's own auto mode), full (the agent's full-access mode).
Options: --model, --effort, --name (use it instead of the ID), --cwd, --timeout 30m.
Tasks share your working directory unless --cwd selects another; axiopera creates no copy.
Give parallel writers separate git worktrees via --cwd.
A timeout interrupts the task; send resumes its session with a fresh time limit.
axiopera models <agent> lists --model IDs and --effort values and names what spawns use
without --model; --json includes descriptions.
Get results
axiopera inbox collects results, questions, approval requests and problems from
your sub-tasks. Each is handed over once. Never blocks.
axiopera wait blocks until there is something new, lists it, and takes nothing.
@claude Run `axiopera wait` as a background command (teammates of team-lead: foreground). When it
@claude exits, run `axiopera inbox`, and start `axiopera wait` again while sub-tasks still run.
@claude Native subagents and teammates share their parent's inbox,
@claude so all pass task IDs to wait and inbox.
@codex After spawning or resuming tasks, run `axiopera watch --status` unless it is already running.
@codex Let your shell tool yield a background session so the user can see progress; the command
@codex exits when no tasks run. Receive results as directed by spawn.
@grok Before you spawn, start `axiopera watch --caller grok:<session>` with your monitor tool,
@grok persistent, unless it is running; start it again if told it ended while sub-tasks run.
@grok For each line it prints, run `axiopera inbox`.
@agy Run `axiopera wait` as a background command. When it finishes, run `axiopera inbox`.
@agy Start another wait while sub-tasks are running. Shell access to the daemon may need approval.
Exit codes: 0 success, 1 command error, 3 nothing new yet (or wait timed out),
4 nothing new and nothing running.
Continue a task
axiopera send <task> "Also update the docs." steers the running turn, or starts a new turn
in the same session if it already finished.
Messages confirmed as queued are handled in a following turn.
Cancelled tasks can also resume with send or reply; their cancelled children stay stopped
until continued separately.
Answer questions
Sub-agents can keep working on independent work until you answer.
axiopera reply <question> "Use port 8080." reaches it mid-turn, or resumes it.
Approval requests pause the sub-agent until you decide; unanswered requests are denied
after the approval timeout (2 minutes by default), ending the wait for approval.
axiopera approve <request> axiopera deny <request> --reason "Use a dry run instead."
Use `send <task> -f msg.md` or `reply <question> -f answer.md`; use `-` to read stdin.
Sub-agents can talk to each other: give them each other's task IDs and tell them to run
`axiopera tell <task> "..."` (Codex and AGY sub-agents have it as the `tell` tool). You get a copy of
every note.
Inspect and stop
axiopera status your sub-tasks axiopera log <task> recent events
axiopera result <task> latest turn result; --force to read it again
axiopera cancel <task> stop it and its children
axiopera detach <task> stop driving it and print the native command for the user