wakterm agent#

The agent subcommand starts, observes, and interacts with AI coding agents and harness panes.

Supported harnesses include Agy, Claude, Codex, Gemini, OpenCode, and ZCode.

Overview of agent subcommands#

• wakterm agent start: start an agent harness in the current pane, a split, a new tab, or a new window
• wakterm agent launch codex: launch Codex through a mux-supervised app-server transport
• wakterm agent adopt: adopt an existing pane as an agent with explicit metadata
• wakterm agent adopt-detected: promote a detected harness pane into persistent agent metadata
• wakterm agent promote-codex: promote an adopted remote Codex TUI into managed app-server metadata
• wakterm agent list: list adopted and detected agent panes
• wakterm agent watch: stream latest observer-backed harness messages
• wakterm agent inspect: inspect a single adopted or detected agent
• wakterm agent output: read experimental normalized agent output for shadow comparison
• wakterm agent events: read durable normalized Agent API v1 events
• wakterm agent capabilities: print versioned Wakterm Agent API capabilities
• wakterm agent catalog: print the narrow Agent API catalog
• wakterm agent admit: atomically admit and submit an agent prompt
• wakterm agent send: send a prompt to an agent pane with optional return correlation
• wakterm agent request: inspect, stream, or cancel durable agent return requests
• wakterm agent remind: schedule messages that the mux sends to an agent later or on a repeat
• wakterm agent interrupt: interrupt a native harness turn
• wakterm agent set: attach agent metadata to a pane
• wakterm agent clear: remove agent metadata from a pane

See also:

• Agent Harness Lifecycle
• Agent Prompt Submission and Final Responses
• Agent API v1 Contract
• Experimental Agent Output Shadow Page

wakterm agent start#

Starts a supported harness in the current pane, a new split, a new tab, or a new window.

start an agent harness in the current pane, a split, a new tab, or a new window

Usage: wakterm agent start [OPTIONS] [HARNESS]

Arguments:
  [HARNESS]  Built-in harness to launch. Preferred for agy/claude/codex/gemini/opencode [possible values: agy, claude, codex, gemini, opencode, zcode]

Options:
      --here                   Start the harness in the current pane instead of creating a new pane/tab/window
      --replace                Replace the current shell process when used with --here
      --name <NAME>            Stable human-readable name for this agent. Defaults to codex/claude with a numeric suffix
      --split                  Spawn into a split instead of creating a new tab
      --pane-id <PANE_ID>      Specify the current pane or split target. Defaults to WAKTERM_PANE
      --new-window             When not splitting, create a new window instead of a new tab
      --workspace <WORKSPACE>  Workspace to use when creating a new window
      --horizontal             Equivalent to `--right`
      --left                   Split horizontally, with the new pane on the left
      --right                  Split horizontally, with the new pane on the right
      --top                    Split vertically, with the new pane on the top
      --bottom                 Split vertically, with the new pane on the bottom
      --cells <CELLS>          Number of cells for the new split
      --percent <PERCENT>      Percentage for the new split
      --repo <REPO>            Repository root or any path inside the target repository
      --worktree <WORKTREE>    Worktree mode: `none`, `auto`, or an explicit path [default: none]
      --branch <BRANCH>        Branch to create or checkout before launch
      --cwd <CWD>              Override the launch cwd directly
      --cmd <CMD>              Explicit command line to launch. Overrides the default command for the selected harness
  -h, --help                   Print help

Examples:

# Start Codex in a new tab
wakterm agent start codex --new-tab

# Start Claude in a split pane to the right
wakterm agent start claude --right --percent 50

# Start Gemini in a specific working directory
wakterm agent start gemini --cwd /code/project

wakterm agent launch codex#

Launches Codex as a mux-supervised app-server TUI. The mux manages the app-server connection over a private Unix socket while the pane runs the native Codex TUI.

launch Codex through the mux-owned app-server

Usage: wakterm agent launch codex [OPTIONS] [-- <CODEX_OPTIONS>...]

Arguments:
  [CODEX_OPTIONS]...  Options passed to the native Codex TUI after `--`

Options:
      --cwd <CWD>           Working directory for the Codex thread. Defaults to the current Wakterm pane cwd
      --resume <THREAD_ID>  Resume this exact Codex thread UUID. A failed resume never creates a replacement
      --new-tab             Launch in a new tab instead of using the current Wakterm pane
  -h, --help                Print help

When run inside a Wakterm pane, the command runs the native TUI in the current pane and returns to the shell when Codex exits. Use --new-tab when running outside Wakterm or when a separate tab is desired.

A new-tab launch returns only after the mux confirms that the native Codex frontend is attached. Wakterm preflights fresh-thread attachment before creating the pane, removes the pane if frontend startup does not complete, and reports the originating app-server or frontend error.

Examples:

# Launch in current pane
wakterm agent launch codex

# Launch in a new tab
wakterm agent launch codex --new-tab

# Resume an exact Codex thread UUID
wakterm agent launch codex --resume 12345678-1234-1234-1234-123456789abc

# Override the model and reasoning effort
wakterm agent launch codex -- --model gpt-6-astra -c 'model_reasoning_effort="high"'

Managed launches accept the model_reasoning_effort config key because Wakterm applies it to both the app-server thread and native TUI. Other -c or --config overrides remain rejected because process-wide and thread settings could otherwise disagree.

wakterm agent list#

Lists adopted and detected agent panes.

list managed, adopted, and detected agent panes

Usage: wakterm agent list [OPTIONS]

Options:
      --format <FORMAT>    Controls the output format. "table" and "json" are possible formats [default: table]
  -v, --verbose            Show pane ids, workspace, turn state, transport, progress, and command
  -f, --follow             Stream latest observer-backed harness message updates instead of printing a snapshot
      --poll-ms <POLL_MS>  Poll interval for follow/watch mode [default: 500]
      --status <STATUS>    List only agents with this status. Repeat or separate with commas to match any of several [possible values: starting, busy, idle, errored, exited]
  -h, --help               Print help

By default, agent list prints a compact table. Use -v for verbose details including turn state and launch command, -f to follow updates, or --format json for JSON output.

# Compact table
wakterm agent list

# Verbose table
wakterm agent list -v

# Stream live updates
wakterm agent list -f

# JSON output
wakterm agent list --format json

wakterm agent watch#

Streams latest observer-backed harness messages across adopted and detected panes.

stream latest observer-backed harness messages for registered and detected agent panes

Usage: wakterm agent watch [OPTIONS]

Options:
      --format <FORMAT>    Controls the output format. "table" streams tab-separated lines, while "json" streams JSON lines [default: table]
      --poll-ms <POLL_MS>  Poll interval while streaming updates [default: 500]
  -h, --help               Print help

Output formats:

# Tab-separated streaming output
wakterm agent watch

# JSON lines output
wakterm agent watch --format json

wakterm agent inspect#

Inspects detailed runtime and metadata state for a single agent.

inspect a single registered or detected agent by name or id

Usage: wakterm agent inspect <TARGET>

Arguments:
  <TARGET>  Agent name, stable id, or pane id

Options:
  -h, --help  Print help

wakterm agent inspect zola

wakterm agent adopt and adopt-detected#

Adopts an existing pane or promotes a detected harness pane into persistent agent metadata.

adopt an existing pane as an agent

Usage: wakterm agent adopt [OPTIONS] --name <NAME> --cmd <CMD>

Options:
      --pane-id <PANE_ID>      Specify the target pane. Defaults to WAKTERM_PANE
      --name <NAME>            Stable human-readable name for this agent
      --cmd <CMD>              Launch command to use for restart and restore
      --cwd <CWD>              Override the declared checkout/cwd for this agent
      --repo-root <REPO_ROOT>
      --worktree <WORKTREE>
      --branch <BRANCH>
  -h, --help                   Print help

promote a detected harness pane into persistent agent metadata

Usage: wakterm agent adopt-detected [OPTIONS] <TARGET>

Arguments:
  <TARGET>  Detected agent name, synthetic id, or pane id

Options:
      --name <NAME>  Override the detected stable name before adoption
  -h, --help         Print help

wakterm agent promote-codex#

Promotes an adopted Codex TUI that is already connected to the current mux-owned app-server. The command requires the exact live thread UUID and fails without changing metadata if the pane process, thread, or socket does not match.

promote an adopted remote Codex TUI into managed app-server metadata

Usage: wakterm agent promote-codex --thread <THREAD_ID> <TARGET>

Arguments:
  <TARGET>  Adopted agent name, stable id, or pane id

Options:
      --thread <THREAD_ID>  Exact Codex thread UUID shown in the live remote TUI command
  -h, --help                Print help

wakterm agent promote-codex wakterm_codex --thread 01a02767-c120-77b2-88a1-4e17c93a7549

wakterm agent send#

Sends a message to an agent pane.

send a message to an agent pane

Usage: wakterm agent send [OPTIONS] <TARGET> [TEXT]

Arguments:
  <TARGET>  Agent name, stable id, or pane id
  [TEXT]    The text to send. If omitted, reads from stdin

Options:
      --no-paste
          Send the text directly, rather than as a bracketed paste
      --no-submit
          Do not press Enter after sending the text
      --return-final
          Durably return this prompt's final response through the request event stream
      --request-id <REQUEST_ID>
          Stable idempotency and correlation id. Generated when omitted
      --ack-timeout-ms <ACK_TIMEOUT_MS>
          Maximum time to wait for the agent to record the input. The command returns as soon as it does [default: 10000]
      --ack-poll-ms <ACK_POLL_MS>
          Poll interval while waiting for acknowledgement [default: 50]
      --final-timeout-ms <FINAL_TIMEOUT_MS>
          Asynchronous final-response deadline. Zero disables the deadline [default: 0]
  -h, --help
          Print help

For idle Codex agents, --return-final enables durable asynchronous return correlation.

# Send prompt to an agent pane
wakterm agent send zola "Run test suite"

# Asynchronous prompt with durable return correlation
wakterm agent send zola --return-final "Refactor module"

wakterm agent admit#

Atomically admits and submits an agent prompt with process incarnation validation and idempotency keys. This is the primary submission interface for external orchestrators.

atomically admit and submit an agent prompt

Usage: wakterm agent admit [OPTIONS] --incarnation <INCARNATION> --request-id <REQUEST_ID> <TARGET> [TEXT]

Arguments:
  <TARGET>  Current agent id or unique display name from `agent catalog`
  [TEXT]    Prompt text; reads stdin when omitted

Options:
      --exact-agent-id
          Treat TARGET as an opaque agent id and bypass current catalog lookup
      --incarnation <INCARNATION>
          Opaque process incarnation from `agent catalog`
      --request-id <REQUEST_ID>
          Durable idempotency key
      --no-paste
          Send the text directly rather than as a bracketed paste
      --return-final
          Preserve the existing return-final terminal request stream
      --final-timeout-ms <FINAL_TIMEOUT_MS>
          Asynchronous return-final deadline; zero disables the deadline [default: 0]
  -h, --help
          Print help

wakterm agent admit zola \
  --incarnation INCARNATION_ID \
  --request-id REQUEST_UUID \
  --return-final \
  "Complete task"

wakterm agent request#

Manages durable agent return requests created with --return-final.

inspect and stream durable agent return requests

Usage: wakterm agent request <COMMAND>

Commands:
  get     get one durable return request
  watch   stream terminal return-request events
  cancel  cancel a pending return request
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

wakterm agent request get#

Views details for a specific return request by ID.

get one durable return request

Usage: wakterm agent request get <REQUEST_ID>

Arguments:
  <REQUEST_ID>

Options:
  -h, --help  Print help

wakterm agent request watch#

Streams terminal return request events.

stream terminal return-request events

Usage: wakterm agent request watch [OPTIONS]

Options:
      --after <AFTER>      Resume after this durable terminal event sequence [default: 0]
      --once               Return after draining currently available events
      --poll-ms <POLL_MS>  Internal observer poll interval for the persistent stream [default: 250]
  -h, --help               Print help

wakterm agent request cancel#

Cancels an in-flight return request.

cancel a pending return request

Usage: wakterm agent request cancel <REQUEST_ID>

Arguments:
  <REQUEST_ID>

Options:
  -h, --help  Print help

wakterm agent remind#

Schedules messages that the mux sends to an agent at a time, after a delay, or on a repeat. Agents use reminders for their timed wakeups instead of timers inside the harness, such as Claude's /loop or ScheduleWakeup. A reminder arrives as input through Wakterm, like wakterm agent send, so it reaches an agent even while the agent is idle and frozen.

Reminders are stored by the mux and survive mux restarts. A reminder that came due while the mux was not running is sent once when it starts, and a repeating reminder then continues one interval later instead of sending every missed repeat. A reminder waits while its agent is not running or has a dialog open, and its last_error says why.

schedule messages that the mux sends to an agent later or on a repeat

Usage: wakterm agent remind <COMMAND>

Commands:
  add     schedule a message to an agent at a time, after a delay, or on a repeat
  list    list scheduled reminders, soonest first
  cancel  cancel a scheduled reminder
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

wakterm agent remind add#

Schedules a message. Give the first time with --at, as an RFC 3339 time, or with --in, as a delay such as 10m. --every repeats the message at that interval until it is cancelled, and alone it starts one interval from now.

schedule a message to an agent at a time, after a delay, or on a repeat

Usage: wakterm agent remind add [OPTIONS] <TARGET> <MESSAGE>

Arguments:
  <TARGET>   Agent name, stable id, or pane id
  <MESSAGE>  The message to send, as `wakterm agent send` would

Options:
      --at <AT>        When to send it, as an RFC 3339 time such as 2026-10-09T1400
      --in <AFTER>     How long from now to send it, such as 10m or 2h
      --every <EVERY>  Send it again at this interval, such as 30m, until cancelled
  -h, --help           Print help

# Check the build in 20 minutes
wakterm agent remind add reviewer "Check whether the CI run finished." --in 20m

# Every hour, starting now plus one hour
wakterm agent remind add monitor "Check the queue and report anything stuck." --every 1h

wakterm agent remind list#

Prints the scheduled reminders as JSON, soonest first.

list scheduled reminders, soonest first

Usage: wakterm agent remind list

Options:
  -h, --help  Print help

wakterm agent remind cancel#

Cancels a reminder by the id that add and list print.

cancel a scheduled reminder

Usage: wakterm agent remind cancel <ID>

Arguments:
  <ID>

Options:
  -h, --help  Print help

wakterm agent events#

Reads durable normalized Agent API v1 events.

read durable normalized Agent API events

Usage: wakterm agent events [OPTIONS]

Options:
      --after <AFTER_SEQUENCE>  Return events strictly after this durable global sequence [default: 0]
      --limit <LIMIT>           Maximum events to return [default: 100]
      --follow                  Keep the connection open and stream event pages as JSON lines
      --wait-ms <WAIT_MS>       Maximum server wait at the stream head [default: 30000]
  -h, --help                    Print help

wakterm agent events --after 0 --limit 100
wakterm agent events --after 0 --limit 100 --follow

--follow keeps one mux connection open and writes each page as one JSON line. It drains retained pages without delay and holds one bounded request at the stream head until a durable commit or --wait-ms timeout. It exits after a cursor_too_old page so the consumer can take a fresh catalog snapshot.

wakterm agent capabilities and catalog#

Prints Agent API capabilities and the current narrow agent catalog.

print the versioned Wakterm Agent API capabilities

Usage: wakterm agent capabilities

Options:
  -h, --help  Print help

print the narrow Wakterm Agent API catalog

Usage: wakterm agent catalog

Options:
  -h, --help  Print help


## `wakterm agent approval`

Resolves one advertised choice for an exact pending approval: a managed Codex command approval or question, or a Claude question with a single choice (`user_question`). The request ID, agent ID, incarnation, and choice come from the corresponding `approval_requested` Agent API event. Replayed or replaced requests fail instead of sending terminal input.

A Claude question form with several questions or multi-select answers is reported as a `user_question_form` event, which advertises no choices. Every Claude question event carries its `questions`, and any Claude question can be resolved with `--choice submit` and `--answers`, or with `--choice chat` or `--choice cancel`; the [Agent API](@/agent-api/v1/_index.md) describes the answer format and the checks Wakterm makes while entering it.

```sh
wakterm agent approval --request-id REQUEST_ID --agent-id AGENT_ID --incarnation INCARNATION_ID --choice CHOICE_ID
wakterm agent approval --request-id REQUEST_ID --agent-id AGENT_ID --incarnation INCARNATION_ID \
  --choice submit --answers '[{"question":0,"choices":["option_2"]}]'

## `wakterm agent interrupt`

Interrupts a native harness turn.

```console
interrupt a native harness turn

Usage: wakterm agent interrupt [OPTIONS] <TARGET>

Arguments:
  <TARGET>  Agent name, stable id, or pane id

Options:
      --ack-timeout-ms <ACK_TIMEOUT_MS>
          Maximum time to wait for observer-backed acknowledgement [default: 2000]
      --ack-poll-ms <ACK_POLL_MS>
          Poll interval while waiting for acknowledgement [default: 50]
  -h, --help
          Print help

wakterm agent interrupt zola

wakterm agent set and clear#

Attaches or removes agent metadata for a pane.

attach agent metadata to a pane

Usage: wakterm agent set [OPTIONS] --name <NAME>

Options:
      --pane-id <PANE_ID>        Specify the target pane. Defaults to WAKTERM_PANE
      --name <NAME>              Stable human-readable name for this agent
      --launch-cmd <LAUNCH_CMD>  Launch command used to recreate this agent on restore
      --cwd <CWD>                Override the declared launch cwd
      --repo-root <REPO_ROOT>
      --worktree <WORKTREE>
      --branch <BRANCH>
      --managed-checkout         Mark the checkout as being provisioned by wakterm
      --unmanaged-checkout       Mark the checkout as not being provisioned by wakterm
  -h, --help                     Print help

remove agent metadata from a pane

Usage: wakterm agent clear [OPTIONS]

Options:
      --pane-id <PANE_ID>  Specify the target pane. Defaults to WAKTERM_PANE
  -h, --help               Print help