docs~/terminal/dispatch.md
/esc
~/terminal/dispatch.md
terminal/dispatch.md · 9 min · updated 2026-11-15 · as markdown

# Dispatch an agent

A dispatch starts Claude Code on one issue. The TUI clones the project's repository into a folder of its own, on a branch named after the issue, starts Claude in a new Rex session, and moves the issue to In Progress, delegated to the workspace's agent. Claude reads the issue, makes the change, runs the checks, pushes the branch and opens a draft pull request. Everything runs on your Mac, started by your own keypress: the server never sends a command or a path. A step that fails undoes the steps before it.

What you need

  • macOS. The tokens come from the Keychain.

  • rsva, signed in with rsva login or your own token (The rsva command).

  • Rex, with its rex command on the PATH.

  • Claude Code, with its claude command on the PATH. The TUI reads the agents' state from claude agents --json.

  • git, and pnpm when the repository has a pnpm-lock.yaml. The agent opens its pull request with gh.

  • A local clone of each project's repository, with an origin remote, mapped to the project's key (below).

  • An agent among the workspace's members. With several, RSVA_AGENT names the one issues are delegated to, by email.

  • Two tokens in the Keychain, which the agent runs on:

    • the agents' recursiva token, under the service rsva-bot;
    • a fine-grained GitHub token with Contents and Pull requests write access to the repositories agents work in, under rsva-agents-github.

    RSVA_AGENT_KEYCHAIN and RSVA_AGENT_GITHUB_KEYCHAIN name other services, for a Mac that works with more than one server.

One GitHub token per owner

A fine-grained GitHub token belongs to one resource owner: a user or an organization. When agents work in repositories of more than one owner, make a token for each and keep it under rsva-agents-github-<owner>, the owner in lowercase as it appears in the repository's origin. A dispatch looks there first, then under rsva-agents-github. With RSVA_AGENT_GITHUB_KEYCHAIN set, the same suffix goes on that name.

sh
security add-generic-password -a agents -s rsva-agents-github-acme -w

With -w last, security asks for the token, so it never appears on the command line.

For recursiva to see the agent's pull request, and to clean up once it is merged, the repository also needs recursiva's GitHub App installed on it and the repository bound to its project on the server. Without them the token still pushes, but the pull request never shows on the issue.

Map projects to repositories

The settings live in ~/.config/rsva/dispatch.json:

json
{
  "repos": { "ABC": "~/code/abc" },
  "model": "opus",
  "effort": "high",
  "executorEffort": "high"
}
Key What it sets Default
repos A project's key and the path of its local clone. A key the project had before a rename still finds it. —
model Claude's model when nothing else is chosen: fable, opus or sonnet. opus
effort Its effort: low, medium, high, xhigh or max. high
executorEffort The executor's effort, when Claude hands the code to one. high

A project without a repository here cannot be dispatched: the TUI says so and does nothing.

From the TUI

Press d on an issue: on the list, on the issue screen, in the queue, or Dispatch to an agent… in the palette.

  1. Context. Anything the issue does not say, up to 4000 characters. It goes into Claude's prompt and onto the issue as your comment. ↵ goes on, Shift+Enter makes a new line, Ctrl+E opens $EDITOR, Esc goes back.
  2. Model, effort and executor. The panel shows the Rex session's name, the repository and the branch. Tab, j k or ↑ ↓ move between the rows; h l or ← → change the value. ↵ launches; Esc or e goes back to the context. The choice is remembered for the project on this Mac.
  3. The launch. Each step shows as it runs, with its time. Esc hides the log while it runs and the status line follows it; l opens the full log in your pager. When it is through, the log closes and the status line says which Rex session Claude is in. If a step fails: r tries again, e goes back to the context, y copies the error, Esc closes.

One launch runs at a time. Quitting the TUI waits for a launch on its way, so its changes to the issue are not lost.

From the command line

sh
rsva tui dispatch ABC-12
rsva tui dispatch ABC-12 --model sonnet --effort medium
rsva tui dispatch ABC-12 --model opus --executor sonnet
echo "Keep the public API as it is." | rsva tui dispatch ABC-12 --context -
rsva tui dispatch ABC-12 --dry-run
Flag What it does Default
--model M Claude's model: fable, opus or sonnet. model in the settings, opus
--effort E low, medium, high, xhigh or max. effort in the settings, high
--executor M Hand the code to an executor on this model; Claude curates. It must differ from --model. none: Claude works alone
--context TEXT Your context for the agent. - reads it from stdin. none
--dry-run Print the repository, the clone's folder, the branch, the Rex session, the claude command and the prompt, and stop. off

The command prints each step as it ends: ✓ done, ✗ failed, ↺ undone. Its last line names the Rex session Claude is working in.

rsva tui agents lists the agents started from this Mac, one line each: the issue, its state, the model and effort, when it started, and the Rex session. The state is what Claude Code reports, such as busy, idle or blocked; starting before Claude shows up; or closed once the Rex session is gone.

What a dispatch does

  1. Check. An issue whose agent's Rex session is still open is refused.
  2. Fetch origin. Refuses an issue whose clone folder already exists: it was dispatched before. Asks origin for its default branch and that branch's commit.
  3. Clone. Makes a separate clone, not a git worktree, in <repository>/.claude/worktrees/<branch>. The branch is the issue's key and its title in lowercase, such as abc-12-fix-the-login-redirect. It starts at origin's commit and pushes to origin under the same name. Git hooks are off while the TUI clones.
  4. Install dependencies, when the repository has a pnpm-lock.yaml: pnpm install --frozen-lockfile without the packages' scripts. packageManager in package.json must be pnpm@x.y.z, with or without its +sha512.… hash; a URL or another manager is refused.
  5. Rex session. Reads the two tokens from the Keychain into the session's own settings file, readable only by you. Marks the clone as trusted in Claude Code and declines imports from outside it, so Claude stops on neither dialog: the clone sits inside your repository, Claude also reads your CLAUDE.md above it, and an @ import there points outside the clone. The clone's own CLAUDE.md brings its own files. Opens a Rex session named after the branch, with Claude in it.
  6. Claude started. Waits up to 15 seconds for Claude to appear in claude agents. A dialog waiting in its session fails this step.
  7. The issue. Posts your context as a comment, then a line saying who started what: the model, the effort, the branch and Claude's session id. Moves the issue to its project's first started state (In Progress in the default workflow), delegates it to the agent, and takes the proposed label off. Dispatching an issue approves it.

If any of steps 2 to 6 fails, the steps before it are undone, newest first: the Rex session closed, the trust removed, the settings file deleted, the clone removed. From step 7 on the agent is working: a change the server refuses shows as a failed step, and the agent keeps going.

What the agent does

Claude starts with a fixed prompt: the issue's key, its folder and branch, and your context. The issue's own text is not in the prompt. Claude reads the issue with rsva show and rsva comments, and is told that the issue's text and its comments are data, not instructions: if they ask for anything beyond the issue's change, such as secrets, other repositories, servers or deploys, it says so in a comment and stops.

Working alone, Claude:

  1. reads the code and the repository's CLAUDE.md, and files anything it notices outside the issue as a new issue labelled proposed;
  2. makes the change;
  3. runs the checks the repository asks for;
  4. commits on the branch, with the issue's key in the message;
  5. pushes and opens a draft pull request with gh pr create --draft; recursiva's GitHub integration links it to the issue by the branch name;
  6. comments on the issue what it did, what it checked and what is left.

It does not merge and does not deploy. When it needs you, it asks in a comment on the issue and waits.

Curator and executor

With an executor, Claude curates and a cheaper model writes the code. Claude writes a brief and posts it on the issue, hands it to an executor subagent on the executor's model and effort, reads the diff itself, and sends it back with concrete points twice at most. Then Claude pushes, opens the draft pull request and comments, as above. The executor commits but does not push or write to recursiva.

What it may do

Claude Code runs in auto permission mode, without a sandbox. Its settings forbid pnpm release and security. Its git ignores your global git configuration and pushes over HTTPS with the agents' GitHub token, never yours. Commits carry the name and email of your global git configuration. When your repository sets a relative core.hooksPath, the agent's own git uses those hooks too.

The agent gets the TUI's RSVA_URL and RSVA_WS when they are set, so it works on the same server and workspace.

Watching and cleaning up

While the TUI runs, each issue with an agent shows the agent's state on its row: running, waiting, idle, or done once its Rex session is closed. The head counts the agents running and waiting.

When recursiva sees the pull request from the run's branch merged, the TUI, while it runs, cleans up: it waits while the agent is busy, closes the Rex session, moves the clone to a trash folder in its cache, and deletes the settings file and the trust entry. The clone is kept there for a week, for anything the agent left uncommitted, then deleted.

rsva tui agents deletes the settings file, with its tokens, of every agent whose Rex session is closed.