wdx agent

Manage agents: AI coding agents that belong to a project and outlive the daemon.

An agent runs an AI coding agent, such as Claude Code, in its own process, so it keeps running when the daemon restarts or is upgraded. Attach to talk to it. Closing its project stops it, and opening the project again starts it in the same session. wdx agent acas lists the AI coding agents new agents can run.

Command	What it does
`wdx agent acas`	List the AI coding agents new agents can run
`wdx agent attach`	Show an agent full-window and talk to it, as tmux does
`wdx agent create`	Create an agent and start its AI coding agent
`wdx agent get`	Show an agent
`wdx agent list`	List agents
`wdx agent models`	List the models agent create `--model` takes
`wdx agent remove`	Delete an agent
`wdx agent rename`	Give an agent a new name
`wdx agent restart`	Start an agent again in a new session, which reads its history in brief
`wdx agent send`	Give a running agent a message, submitted once it can take it
`wdx agent start`	Start an agent that exited, failed or was lost, in the same session
`wdx agent transcript`	Print an agent’s conversation as text

wdx agent acas

List the AI coding agents new agents can run.

wdx agent acas [flags]

Those installed, as the login shell finds each one’s program, and enabled by its aca.<id>.enabled setting, in the order they are offered; the default is what agent create runs with no --aca. wdx deps list says which are installed, and wdx setting list which are enabled.

Flags

Flag	Default	Description
`--node <name>`		run the command on the node of this name, another of your account, through a session

Examples

# List them
wdx agent acas

# As JSON
wdx agent acas --json

Output

The AI coding agents, the default first. With --json: {“acas”: [{“id”: “claude_code”, “default”: true}, …]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

With --node, also: code_not_set_up, code_wrong, connection_lost, daemon_unavailable, hub_unreachable, hub_version_unsupported, node_key_mismatch, node_not_found, node_offline, node_version_unsupported, not_logged_in, remote_access_off, remote_not_for_agents, route_not_allowed, session_closed, session_required, too_many_streams.

wdx agent attach

Show an agent full-window and talk to it, as tmux does.

wdx agent attach (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--prefix-key <key>] [flags]

The agent takes the whole window, above a status line, and what you type goes to it. C-\ is the prefix for attach’s own keys: C-\ d detaches, leaving the agent running, and gives the window back as it was; C-\ ? lists them all. It runs in the terminal it was started from, not on stdin and stdout, which print the result when it ends.

Flags

Flag	Default	Description
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--prefix-key <key>`	`ctrl-\`	key before attach’s own keys: ctrl-<letter> but i and m, ctrl-\ or ctrl-]
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Attach to an agent of the project you are in
wdx agent attach --name reviewer

# With ctrl-] as the prefix
wdx agent attach --id agent-1a2b3c4d --prefix-key ctrl-]

# As JSON once it ends
wdx agent attach --name reviewer --json

Output

The agent, once you detach or it exits. With --json: {“result”: “detached” or “exited”, “agent”: {…}}

With --json, result is one of: detached or exited.

Errors

Code	Exit	When
`agent_not_running`	1	the agent’s AI coding agent is not running
`attach_unsupported`	1	the terminal was started by a wdx too old to attach to
`connection_lost`	3	the connection to the terminal or node ended before it answered
`daemon_unavailable`	3	the daemon is not running or not answering
`holder_version_unsupported`	1	the terminal’s holder and a client on another node speak no version in common: the terminal was started by a wdx too old for relayed clients, or the client’s is too old for the holder
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent create

Create an agent and start its AI coding agent.

wdx agent create [--prompt <text>] [--project-id <id> | --project-name <name>] [--name <name>] [--parent-id <id> | --parent-name <name>] [--worktree <name>] [--aca <id>] [--model <model>] [--permissions <mode>] [flags]

Without a project flag, the agent belongs to the project the working directory is in, and starts there. With one, it starts in the working directory when that is in the project, else in the project’s clone path. It runs through your login shell, which finds the program.

Agents get a generated name such as swift-falcon unless --name is given; names have letters, numbers and - only, and are unique within a project, among agents and terminals.

With a parent flag it is a child of that agent: it belongs to the parent’s project and starts in the parent’s dir. Without one it is at the top level, even when an agent creates it: an agent finds its own id in WDX_AGENT_ID. With --node, --parent-id needs no project flag; --parent-name does, as a name is unique only within its project.

With --worktree it starts in that worktree of the project instead: main is the clone, and any other name matches the last part of a worktree’s path. A name that matches none creates the worktree in <project root>/.worktrees/<name>, on a new branch of that name from the HEAD of where it would otherwise start. Removing the agent leaves the worktree.

With --prompt it starts on that task: the first message in its inbox, as wdx agent send gives it, typed in once it is ready for it. A prompt that cannot be sent leaves the agent running, and the result says why.

With --aca it runs that AI coding agent, which must be installed and enabled; by default the first that is, as wdx agent acas lists them.

With --model its AI coding agent uses that model, named as its own model flag takes it: wdx agent models lists them, and any other is passed as given. --permissions full, the default, lets it do anything without asking, with network access and no sandbox; ask leaves that to your settings for it. Both are kept for every later start: restart and resume use them too.

Flags

Flag	Default	Description
`--aca <id>`		id of the AI coding agent it runs (default: the first installed and enabled)
`--model <model>`		model its AI coding agent uses, on every start (default: its own default)
`--name <name>`		name of the agent (default: a generated one)
`--parent-id <id>`		id of the agent to create it under
`--parent-name <name>`		name of the agent to create it under (case-insensitive)
`--permissions <mode>`		mode: full lets it do anything without asking, ask leaves that to your settings for it (default: full)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--prompt <text>`		text of its first task; it is submitted once it is ready
`--worktree <name>`		name of the worktree to start in, created when there is none (default: the parent’s, else the one you are in, else main)
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --parent-id or --parent-name
at most one of --project-id or --project-name

Examples

# Create an agent in the project you are in
wdx agent create

# Start one on a task
wdx agent create --name reviewer --prompt summarize

# Start a child on a task, in a worktree of its own
wdx agent create --parent-name reviewer --worktree fix-login --prompt fix

# Name it and pick the project
wdx agent create --project-name app --name reviewer

# Create a child of an agent
wdx agent create --parent-name reviewer

# Create a child by the parent's id, as JSON
wdx agent create --parent-id agent-1a2b3c4d --json

# Create a child in a worktree of its own
wdx agent create --parent-name reviewer --worktree fix-login

# Pick its AI coding agent
wdx agent create --aca claude_code

# Pick its model
wdx agent create --model sonnet

# Have it ask before acting, as your settings say
wdx agent create --permissions ask

# As JSON
wdx agent create --json

Output

The agent, running. With --json: {“result”: “created”, “agent”: {…}}, and “worktree_created”: true when its worktree is new

With --json, result is one of: created.

Errors

Code	Exit	When
`aca_unavailable`	1	the AI coding agent is not installed or is disabled, or none is installed and enabled
`agent_removed`	1	the agent was removed and stays only for its children
`branch_exists`	1	a new worktree’s branch already exists
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_argument`	1	an argument is empty or malformed
`invalid_name`	1	the name is not allowed
`name_taken`	1	something else has this name
`not_found`	1	nothing has this name or id
`path_exists`	1	something is already at the path, as the directory to clone into
`project_closed`	1	the project is closed
`start_failed`	3	the holder, the shell or the AI coding agent did not start
`worktree_failed`	1	git could not add the worktree
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent get

Show an agent.

wdx agent get (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [flags]

In any state, with why it failed when it did. Without a project flag, --name is looked up in the project the working directory is in. Nothing is changed.

Flags

Flag	Default	Description
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Show an agent of the project you are in
wdx agent get --name reviewer

# By id, as JSON
wdx agent get --id agent-1a2b3c4d --json

Output

The agent. With --json: {“agent”: {…}}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent list

List agents.

wdx agent list [--project-id <id> | --project-name <name> | --all] [flags]

Without a flag, the agents of the project the working directory is in. Every state is listed: an agent stays until it is removed. Children are indented under their parents, and a removed agent stays as long as it has children.

Flags

Flag	Default	Description
`--all`		list the agents of every project
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --all or --project-id
at most one of --all or --project-name
at most one of --project-id or --project-name

Examples

# The agents of the project you are in
wdx agent list

# Every project's, as JSON
wdx agent list --all --json

Output

The agents by project, then name, each with its children; an empty list when there are none. With --json: {“agents”: […]}, the children of each under “children”

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent models

List the models agent create --model takes.

wdx agent models [--aca <id>] [flags]

The models of an AI coding agent new agents can run, as it says: --aca’s, or by default the first installed and enabled. One marked default is what it runs with no --model; with none marked, it runs what your own settings for it say.

Flags

Flag	Default	Description
`--aca <id>`		id of the AI coding agent (default: the first installed and enabled)
`--node <name>`		run the command on the node of this name, another of your account, through a session

Examples

# List them
wdx agent models

# List another AI coding agent's
wdx agent models --aca claude_code

# As JSON
wdx agent models --json

Output

The AI coding agent’s models, in its order. With --json: {“aca”: “claude_code”, “models”: [{“id”: …, “name”: …, “default”: …}, …]}

Errors

Code	Exit	When
`aca_unavailable`	1	the AI coding agent is not installed or is disabled, or none is installed and enabled
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent remove

Delete an agent.

wdx agent remove (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--stop-running | --cancel] [flags]

If it is running, you are asked whether to stop it, which interrupts what it is doing; --stop-running and --cancel answer in advance, and with --json one of them is required. What the AI coding agent keeps of its session stays on disk.

An agent with children stays in the list as removed, its children untouched, until the last of them is removed.

Flags

Flag	Default	Description
`--cancel`		if it is running, change nothing without asking
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--stop-running`		if it is running, stop it without asking
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --stop-running or --cancel
at most one of --project-id or --project-name
with --json: one of --stop-running or --cancel

Examples

# Remove an agent of the project you are in
wdx agent remove --name reviewer

# From a script: stop it if it is running
wdx agent remove --id agent-1a2b3c4d --stop-running --json

Output

The removed agent, as it was before. With --json: {“result”: “removed”, “agent”: {…}}

With --json, result is one of: removed.

Errors

Code	Exit	When
`agent_removed`	1	the agent was removed and stays only for its children
`agent_running`	1	the agent is already starting or running
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent rename

Give an agent a new name.

wdx agent rename (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] --new-name <name> [flags]

It goes on running, in the same session. Names have letters, numbers and - only, and are unique within a project, among agents and terminals. What used the old name no longer finds it. A removed agent cannot be renamed.

Flags

Flag	Default	Description
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--new-name <name>`		name to give the agent
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--new-name is required
exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Rename an agent of the project you are in
wdx agent rename --name reviewer --new-name auth-review

# By id, as JSON
wdx agent rename --id agent-1a2b3c4d --new-name auth-review --json

Output

The agent, under its new name. With --json: {“result”: “renamed”, “agent”: {…}}

With --json, result is one of: renamed.

Errors

Code	Exit	When
`agent_removed`	1	the agent was removed and stays only for its children
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_name`	1	the name is not allowed
`name_taken`	1	something else has this name
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent restart

Start an agent again in a new session, which reads its history in brief.

wdx agent restart (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--force] [flags]

agent start goes on with the same conversation, whatever its size. This stops the AI coding agent if it runs and starts a new session under the same id, in the directory it last worked in if that is still there, else its own. Its first message tells it to read agent transcript --brief. Messages not yet delivered reach it after that one, general even if they were instant; one delivered just before may come again. What the old session held only in memory goes with it. A background session its AI coding agent moved it to is stopped too, and named, as agent start and agent remove do. Unless it is idle with an empty input box, and no such session is at work, it takes --force, which can leave work half done.

Flags

Flag	Default	Description
`--force`		restart it even in the middle of its work
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Restart an idle agent of the project you are in
wdx agent restart --name reviewer

# In the middle of its work, as JSON
wdx agent restart --id agent-1a2b3c4d --force --json

Output

The agent, running in its new session. With --json: {“result”: “restarted”, “agent”: {…}}, with stopped_sessions when it stopped any

With --json, result is one of: restarted.

Errors

Code	Exit	When
`aca_unavailable`	1	the AI coding agent is not installed or is disabled, or none is installed and enabled
`aca_unsupported`	1	the agent’s AI coding agent cannot do this yet
`agent_busy`	1	the agent is in the middle of something, which this would lose
`agent_removed`	1	the agent was removed and stays only for its children
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`project_closed`	1	the project is closed
`start_failed`	3	the holder, the shell or the AI coding agent did not start
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent send

Give a running agent a message, submitted once it can take it.

wdx agent send (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] --prompt <text> [--instant] [flags]

The message is queued for the agent, in the order sent. It waits while text is in the agent’s input box, a prompt is open or its screen cannot be read, for as long as that lasts. During a turn it goes in, for the agent to take up at its next step (Claude Code, Codex), or after the turn (Cursor, Antigravity). This does not wait for it to go in or for a reply. A message still queued when the agent ends is kept: it goes on when the agent is started again in the same session or restarted, or else waits in wdx message list.

--instant goes before the other messages, and waits as they do. Claude Code takes it at once, Codex at its next step. An AI coding agent that cannot take a message into its running turn has the turn interrupted first, but not in a pane too narrow to show that a turn is running.

A message whose first non-blank character is ! is given to the model as !, never run as a shell command.

Flags

Flag	Default	Description
`--id <id>`		id of the agent
`--instant`		go before other messages; Claude Code takes it at once, and an AI coding agent that cannot take it into its turn is interrupted
`--name <name>`		name of the agent (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--prompt <text>`		text to give it; it is submitted
`--node <name>`		run the command on the node of this name, another of your account, through a session

--prompt is required
exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Give an agent of the project you are in a task
wdx agent send --name reviewer --prompt summarize

# Give it this first: Claude Code takes it at once
wdx agent send --name reviewer --prompt stop --instant

# By id, as JSON
wdx agent send --id agent-1a2b3c4d --prompt summarize --json

Output

The agent the message is queued for. With --json: {“result”: “queued”, “agent”: {…}}

With --json, result is one of: queued.

Errors

Code	Exit	When
`agent_not_running`	1	the agent’s AI coding agent is not running
`agent_removed`	1	the agent was removed and stays only for its children
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`send_failed`	3	the message did not reach the terminal’s holder
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent start

Start an agent that exited, failed or was lost, in the same session.

wdx agent start (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [flags]

The agent keeps its id, name, dir and session, so its conversation comes back, in the directory it last worked in if that is still there, else its own. Agents stopped by closing their project start again when it is opened.

Flags

Flag	Default	Description
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Start an agent of the project you are in
wdx agent start --name reviewer

# By id, as JSON
wdx agent start --id agent-1a2b3c4d --json

Output

The agent, running. With --json: {“result”: “started”, “agent”: {…}}

With --json, result is one of: started.

Errors

Code	Exit	When
`aca_unavailable`	1	the AI coding agent is not installed or is disabled, or none is installed and enabled
`agent_busy`	1	the agent is in the middle of something, which this would lose
`agent_removed`	1	the agent was removed and stays only for its children
`agent_running`	1	the agent is already starting or running
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`project_closed`	1	the project is closed
`start_failed`	3	the holder, the shell or the AI coding agent did not start
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx agent transcript

Print an agent’s conversation as text.

wdx agent transcript (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--tail <lines> | [--from <line>] [--count <lines>] | --path | --brief] [flags]

wdx keeps its own copy of the conversation, which only grows: it goes on across compactions and clears, and stays after the AI coding agent deletes its own, until the agent is removed and for 7 days after that. Unlike the terminal’s history, it is what was said and done, not what the screen showed. It can hold whatever the agent’s tools read. --path prints the file’s path, for grep. Lines are numbered from 0, which --from counts in; --count alone starts at the first.

--brief is for an agent in a new session: from the latest summary, or the first request, it prints the messages since, and each tool call as one line, with the line of the file that --from reads it at. It goes no further back than a /clear.

Flags

Flag	Default	Description
`--brief`		print the conversation in brief, for an agent to read
`--count <lines>`	`1000`	lines from `--from` on, or from the first
`--from <line>`	`0`	number of the first line
`--id <id>`		id of the agent
`--name <name>`		name of the agent (case-insensitive)
`--path`		print the file’s path, not its lines
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--tail <lines>`	`1000`	the last lines
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --brief or --tail
at most one of --brief or --from
at most one of --brief or --count
at most one of --brief or --path
at most one of --tail or --count
at most one of --path or --count
at most one of --tail or --from
at most one of --path or --from
at most one of --path or --tail
at most one of --project-id or --project-name

Examples

# The last lines of an agent of the project you are in
wdx agent transcript --name reviewer

# The last 50
wdx agent transcript --name reviewer --tail 50

# The file, to grep it
wdx agent transcript --name reviewer --path

# The conversation in brief
wdx agent transcript --id agent-1a2b3c4d --brief

# From line 1200 on, as JSON
wdx agent transcript --id agent-1a2b3c4d --from 1200 --count 100 --json

Output

The lines, oldest first, as Markdown, or the file’s path with --path, or the brief. With --json: {“transcript”: {“path”: …, “from”: …, “next”: …, “lines”: […]}}

Errors

Code	Exit	When
`aca_unsupported`	1	the agent’s AI coding agent cannot do this yet
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git