Agents

What it is

An agent is a terminal that runs an AI CLI, which wdx calls an ACA (AI coding agent): Claude Code, Codex, Cursor or Antigravity. wdx starts it, reads its screen to say whether it is working, idle or waiting for you and with what question, and follows its session, so that an agent started again goes on in the same conversation. It keeps its own copy of that conversation too. See Concepts.

Try it

See which AI CLIs are installed, and the models of the default one:

$ wdx agent acas
AI coding agents
ID
claude_code (default)
antigravity
cursor
codex
$ wdx agent models
models of claude_code
ID      NAME
fable   Fable
opus    Opus
sonnet  Sonnet
haiku   Haiku
with no --model, your own setting for it

Create an agent in the project you are in. --prompt would start it on a task; --aca and --model choose what runs it:

$ cd ~/code/app
$ wdx agent create --name lead
created agent lead in app
  dir  /home/you/code/app
  aca  claude_code
  id   agent-c132a237

The list says what each is doing. This one waits on Claude Code’s question about trusting the folder, and agent get shows it:

$ wdx agent list
NAME  STATE    ACTIVITY  MODEL  CONTEXT  ACA          DIR                 ID
lead  running  yes/no                    claude_code  /home/you/code/app  agent-c132a237
$ wdx agent get --name lead
agent lead in app
  state       running
  activity    yes/no
  prompt      yes/no · Accessing workspace
  question    Accessing workspace:
  detail      /home/you/code/app
  options     ❯ No, exit
                Yes, I trust this folder
  worktree    main
  dir         /home/you/code/app
  aca         claude_code
  permissions full
  session     789aa95c-6e50-4680-9834-dacb71edc6b3
  pid         2753818
  id          agent-c132a237
  created     2026-11-08 01:48:13
  started     2026-11-08 01:48:13

Attach to answer it and talk to the agent. C-\ d detaches and leaves it running:

$ wdx agent attach --name lead

Once answered, the list shows it idle, with its model and how full its context is:

$ wdx agent list
NAME  STATE    ACTIVITY  MODEL      CONTEXT  ACA          DIR                 ID
lead  running  idle      Fable 5.1  0        claude_code  /home/you/code/app  agent-c132a237

Read back what an agent said and did, as Markdown, without attaching. Here the end of one that has been at work:

$ wdx agent transcript --name readme --tail 12
### Tool: Bash

```
{"command":"cd /home/you/code/app && git status --short --branch && git worktree list && git branch -a","description":"Show branch, worktrees and status of main clone"}
```

### Result (error)

```
Working directory "/home/you/code/app/.worktrees/fix-readme" was deleted; shell cwd recovered to "/home/you". Re-issue your command (it will run from the recovered directory).
```

How much of the AI CLI’s limits is used since 0.5.0, as its agents last told; the row is the account’s, so every agent of one AI CLI shows the same. The same in TIDE is the stats tab:

$ wdx usage
claude_code                 available
  WINDOW                    USED  RESETS         AS OF
  Session (5 h)             54%   in 2 h 10 min  16:11
  Week                      51%   Nov 12 10:00   16:11
antigravity Gemini models   available
  WINDOW                    USED  RESETS         AS OF
  Session (5 h)             12%   in 4 h 2 min   16:09
  Week                      30%   Nov 13 08:00   16:09

Answer the questions your Claude Code agents wait on unreleased, without attaching to each: wdx prompt lists them, asks which, then offers its options.

$ wdx prompt
2 prompts in app
  1  fix-readme  yes/no    Bash command · go test ./...
  2  planner     decision  Which store keeps the sessions?
Which one? (1-2, q to quit): 2
planner · decision · Store
Which store keeps the sessions?
  1  SQLite
  2  Files
  3  Type something.  (type your own)
  4  Chat about this  (declines; go on in the agent's tab)
Which option? (1-4, q to quit): 1
answered agent planner in app

In TIDE

The Agents section of the left pane lists the project’s agents, children under their parents, each with its activity, model and context size; Enter opens one in the right pane to talk to it. C-q a creates one in a form (name, ACA, model, worktree, permissions and a prompt), and i opens its info tab, with what agent get shows. On an agent, r renames it, g starts it again once it has ended, R starts a new session after a confirmation, and x removes it. TIDE has no transcript screen: that is for reading and grepping with the CLI. More in Agents in TIDE.

How it behaves

Where it starts. In the working directory if that is in the project, else in the project’s clone; --worktree starts it in a worktree of its own (Worktrees and landing). It runs through your login shell, which finds the AI CLI’s program.
What runs it. --aca picks the AI CLI (the AI CLIs compares them), which must be installed and enabled (aca.<id>.enabled); by default the first that is, as agent acas lists them. --model takes a model as that CLI’s own model flag does; without it, your own settings for that CLI decide. --permissions full, the default, lets it do anything without asking, with network access and no sandbox; ask leaves that to your settings. Both are kept for every later start.
Activity is read from its screen: working, idle, waiting, or yes/no and decision when wdx can read the question (Claude Code for now), with the question and its options in agent get. unknown means the screen cannot be read yet. Context is how much of its context window the conversation fills, colored by context.threshold.warning and context.threshold.critical.
States are a terminal’s: running, exited, stopped by closing the project, failed, lost, and removed for a parent kept for its children (Child agents).
Starting again. agent start brings back an agent that ended in the same session, so its conversation is there, in the directory it last worked in. Opening a project starts the agents closing it stopped, the same way.
A new session. agent restart stops the ACA and starts a new session under the same id, whose first message tells it to read agent transcript --brief, its history in brief. An agent that is busy, or has text in its input box, needs --force, which can leave work half done.
The transcript is wdx’s own copy of the conversation. It only grows, across compactions and clears, and stays after the ACA deletes its own, until the agent is removed and for 7 days after. It is what was said and done, not what the screen showed. --path prints its file, for grep.
Names are generated unless --name gives one, unique in a project among agents and terminals; agent rename changes one while it runs.
Removing a running agent asks first, as it interrupts what it does; --stop-running or --cancel answers in advance. What the ACA keeps of its session stays on disk.
Giving it a task later is wdx agent send, in Messages and sending.
Answering its prompts unreleased. wdx prompt lists the project’s Claude Code agents with a question open, in the agents’ order, and answers the one you pick: a number chooses an option; in a checkbox list you give the numbers to tick, and it asks before sending; a Type something option asks for your text; Chat about this declines and says to go on in the agent’s tab. A decision of several questions is asked one by one, each sent as you answer it, as Claude Code shows only the current one and submits nothing before its review; then the answers are shown and sent only on y. wdx presses the keys through the agent’s terminal, one at a time, and only while its screen still shows the question you saw: if it changed, nothing more is pressed, wdx prompt says so and lists them again. With --json it lists the agents and their prompts and asks nothing; scripts answer through the API’s POST /v1/agents/{agent}/prompt/answer. Nothing it logs holds a question, an option or what you typed. The same in TIDE is the prompts tab.
Usage since 0.5.0 is read from what the AI CLI tells its agents, with nothing typed into them: the windows of its limits with the percentage used and when each resets, as of the latest answer of any of its agents. A window used 100% or more is limited, and the AI CLI can be used while none is; the line says limited, resets in 2 h otherwise. Nothing is shown until an agent has answered, and an account without limits never shows anything. wdx only shows it: nothing pauses or resumes on its own. wdx usage --node desk shows another node’s (Hub).
Where each AI CLI tells it since 0.5.0. Claude Code and Antigravity in the status line wdx gives every agent, the file it already reads for the context size; Codex in its session file, beside each answer’s token count; Cursor nowhere on disk, so the daemon asks Cursor’s API what its own /usage screen asks, while a Cursor agent works and at most every 5 minutes, with the login Cursor’s CLI keeps, which wdx reads at each call and never stores (on Linux; on macOS that login is in the keychain, which wdx does not read). Cursor is the one place wdx goes on the network for an AI CLI.
Buckets since 0.5.0. Some limits apply to a group of models only, shown as a block of their own under its name: Antigravity’s Gemini models, Claude and GPT models and Gemini 4 Argon, each with a session and a week; Cursor’s Auto and API beside its included allowance, by the billing month, in whole percents, without on-demand spend; Codex’s other buckets by the names it gives. A window or bucket wdx does not know yet shows its key as the AI CLI gives it. Codex may stop at 99% and refuse every prompt: wdx shows that window limited too.
Limited agents since 0.5.0. An agent reads limited in agent list’s ACTIVITY, in red, while a bucket its model draws on is limited, and agent get names it and when it resets: limited Claude and GPT models, resets in 2 h, or only when for the limit every model of its AI CLI shares. An agent on Gemini is not limited while Antigravity’s Claude and GPT models is. wdx tells the model’s bucket from its --model or from the name the AI CLI shows; a model it cannot place is marked only once every bucket of its AI CLI is limited, so it never shows a limit that is not its own. A working agent keeps reading working, as its turn goes on. The mark ends by itself at the reset, and wdx acts on nothing: it neither waits, resumes nor switches. With --json, limited is {"bucket": "3p", "resets_at": "…"} or null.

Commands

Command	What it does
`wdx agent create`	Create an agent and start its AI coding agent
`wdx agent attach`	Show an agent full-window and talk to it, as tmux does
`wdx agent list`	List agents
`wdx agent get`	Show an agent
`wdx agent acas`	List the AI coding agents new agents can run
`wdx agent models`	List the models agent create --model takes
`wdx agent rename`	Give an agent a new name
`wdx agent start`	Start an agent that exited, failed or was lost, in the same session
`wdx agent restart`	Start an agent again in a new session, which reads its history in brief
`wdx agent transcript`	Print an agent's conversation as text
`wdx agent remove`	Delete an agent
`wdx usage`	Show how much of each AI coding agent's account's limits is used
`wdx prompt`	Answer the prompts the project's Claude Code agents wait on