Skill

---
name: wts
description: wts runs parallel Claude Code agents on this machine, one per git worktree and tmux session, and shares their state in a database. Use it when the user asks what the other sessions or agents are doing, wants a piece of work started in a new isolated session (from a sentence, a task or a document), wants to delegate to another agent and get its result back, or asks about tasks, worktrees to clean up or the work journal — and inside a wts session (your context then starts with "# wts: you are in session"), whenever your change may affect another session.
---
<!-- generated by `wts setup claude --install` (wts {{VERSION}}); rerun it to update, edits are overwritten -->

# wts, for an agent

`wts` is on PATH in a wts pane; if your shell does not find it: `{{WTS}}`.
Every command below works without a terminal: none asks a question or opens a
picker without one (they exit 2 and say what to pass instead). Exit codes: 0
done, 1 failed, 2 usage. JSON outputs are objects with `"version": 1`, except
`wts status --json`, an array of sessions, and `wts db sql|tables|row --json`,
sqlite3's own array of rows; keys are added, never renamed.

## What is going on

| Command | What it answers |
|---|---|
| `wts status --json` | every session: `name`, `branch`, `worktree`, `agent_state` (blocked working idle done failed stopped, or null: no agent known), `stale` (true: it says working and its pane no longer moves), `agent_since`, `agent_waiting_for`, `task`, git delta, `merged` (squash included), `pr` (number, state, checks, review, as `wts pr --refresh` last cached them), `usage` (tokens and cost) |
| `wts brief --cached --json` | each session's last "done / next" summary and its age — no model call |
| `wts task ls --all --json`, `wts task show <id> --json` | tasks, their notes, documents, live sessions and previous attempts |
| `wts doc ls --json`, `wts doc show <slug> --json` | the context documents and which sessions they are attached to |
| `wts db notes --all` | the notes the agents left each other; `wts db row <table> <rowid>` prints one record of any table |
| `wts db sql "<SELECT …>" --json` | anything else (read-only); find the table with `wts db tables` (row and column counts) and its columns with `wts db schema <table>`, rather than reading the whole `wts db schema` |
| `wts log --since '-30 days'` | finished sessions, outcomes, retrospectives, tokens and cost per session and per task |
| `wts doctor --json` | whether wts can work on this machine |

## Working next to other agents (inside a session)

- When you edit a file another session of this repository has edited too, wts
  tells you in the tool result; when a session edits one you edited first, you
  hear of it at your next prompt or edit. Read their notes before going further.
- When your change affects another session (a migration, a shared model, an API
  contract), leave one line: `wts db set <key> "<one line>"` (also `get`, `del`).
  Your own notes only: `--session <other>` reads, it does not write. New notes
  from the others, and the sessions that finished with the notes they left,
  reach you once each, at your next turn or your next edit, whichever comes first.
- What you learn about the task outlives the session: `wts task note "<text>"`.

## Delegating to another agent

```sh
wts "<the task in one sentence>" --json        # new session, named for you; prints {name, branch, worktree, …}
wts <name> "<the task>" --task <id> --doc <slug> --json   # with a name, a task, a document
wts wait <name> --timeout 90                   # 0 once it is no longer working, 1 on timeout: call again
wts status --json                              # blocked? .agent_waiting_for says on what
wts send <name> --answer <choice>              # answer the question it is blocked on
wts send <name> "<a new prompt>"               # to a working or idle agent only
wts tail <name> -n 3 --json                    # its last messages, from its transcript
```

`wts wait` also returns on an agent that quit (`stopped`) or that is stuck
(`"stale": true`). When it says no agent is known in a session (`unknown`),
calling it again will not help: read `wts status --json`. `wts send` refuses a
prompt to a blocked agent (it would be typed into the question) and anything to
an agent that quit (its pane is a shell): it says which, and what to pass.

A creation without a terminal (or with `--json`, or `--detach`) never attaches:
the user's terminal stays where it is. `wts new --json a b c` creates several.

## Ask the user first

- `wts rm`, `wts stop`, `wts gc --apply`, `wts task done`: they tear down
  someone's work. `wts gc --json` shows the plan without doing anything.
- `wts brief` (without `--cached`), `wts doc add`, `wts doc sync`,
  `wts retro` and `gc --apply` call the model and cost turns on the user's account.
- Things (the task app) is read from a terminal only: pass task ids
  (`wts task ls --json`), never rely on a picker.