agent

agent is a built-in extension (no install required) that orchestrates background coding-agent processes — Claude Code, Codex, Gemini CLI, and similar harnesses. One grammar, one set of lifecycle verbs, no harness-specific shell wrapping.

Quick start

godmode agent "summarize this directory"     # shorthand: spawn + send + tail output

That single command picks an installed harness, spawns it in a managed session, sends the prompt, and streams the output until the agent exits. Equivalent to:

ID=$(godmode agent start)
godmode agent send "$ID" "summarize this directory"
godmode agent output "$ID" --follow

Lifecycle verbs

godmode agent start [--harness=<name>]    # start a session, print its id
godmode agent send <id> <prompt>          # send a turn
godmode agent attach <id>                 # interactive REPL on an existing session
godmode agent output <id> [--follow]      # dump (or tail) recent output
godmode agent status <id>                 # running | idle | exited
godmode agent list                        # all sessions, with ages
godmode agent stop <id>                   # terminate a session

The session id is a short random slug (a4-fox, b7-sage). Tab-completion enumerates running sessions.

Harness selection

Set GODMODE_AGENT_HARNESS to change the default for the shell session.

Why this exists

Most coding agents have their own start/attach/log conventions. Wrapping them under godmode agent <verb> means:

1. One Bash permission. A sandboxed agent with Bash(godmode:*) can spawn and orchestrate its own sub-agents without you adding a per-harness permission for each.
2. Session ids are stable. A session keeps its id across attach/detach cycles; output --follow resumes correctly.
3. No harness lock-in. Switching from Claude to Codex is a flag, not a script rewrite.

See also

• godmode agent --help — exact flag/verb listing for the version you have installed.
• Claude Code integration — wire godmode extensions into a Claude Code session.
• Other MCP clients — for non-coding-agent MCP integrations.