---
title: Dispatch an agent
summary: How rsva tui starts Claude Code on an issue in its own clone and Rex session, what each step does, and what it needs on your Mac.
---

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](/docs/terminal/cli)).
- [Rex](/docs/terminal/tui), 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.
