Wakterm docs

wakterm agent

On this page
  1. wakterm agent
    1. Overview of agent subcommands
    2. wakterm agent start
    3. wakterm agent launch codex
    4. wakterm agent list
    5. wakterm agent watch
    6. wakterm agent inspect
    7. wakterm agent adopt and adopt-detected
    8. wakterm agent send
    9. wakterm agent admit
    10. wakterm agent request
    11. wakterm agent events
    12. wakterm agent capabilities and catalog
    13. wakterm agent interrupt
    14. wakterm agent set and clear

wakterm agent#

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

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

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 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 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:

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]

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.

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

wakterm agent list#

Lists adopted and detected agent panes.

list 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]
  -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 adopted 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 adopted 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 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 observer-backed acknowledgement [default: 2000]
      --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 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 interrupt#

Interrupts a native harness turn.

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
Edit this page