reevesagents

ReevesAgents needs Node.js 22.12+, tmux 3.0+, and at least one supported provider CLI installed and authenticated. It supports macOS, Linux, and WSL.

# Homebrewbrew tap mertkayacs/reevesagentsbrew install reevesagents
# pnpmpnpm add -g reevesagents
# npmnpm install -g reevesagents
# one-shot checkspnpm dlx reevesagents doctornpx reevesagents doctor

Pin a version by replacing <version>:

pnpm add -g reevesagents@<version>

Source install:

git clone https://github.com/mertkayacs/reevesagents.gitcd reevesagentspnpm installpnpm buildpnpm link --globalreevesagents doctor

The TUI and Web UI drive the same local runs:

[ReevesAgents Web UI: runs and live agent panes]

[ReevesAgents Web UI: starting a new run]

No arguments launches the TUI.

Common flags:

• --json: available on script-facing list and action commands.
• --name <name>: name a run.
• --cwd <dir>: run agents from a directory.
• --prompt <text>: paste startup text into each spawned agent.
• --skip: skip provider permission prompts for unattended workers.
• --run <run-id>: add agents to a specific run.
• --port <n> and --no-open: Web UI startup options.

Agent Control is an optional MCP server. Attach it only to a CLI you trust to drive local tools:

reevesagents attach claudereevesagents hosts

After restart, that CLI receives tools to spawn, read, send_text, send_key, interrupt, kill, stop, manage approvals, manage presets, and inspect hosts. The provider catalog is also exposed as reevesagents://providers.

In Claude Code you can install the connection and its operating instructions together as a plugin:

claude plugin marketplace add mertkayacs/reevesagentsclaude plugin install reevesagents@reevesagents

The server is listed in the official MCP Registry as io.github.mertkayacs/reevesagents.

Workers do not receive the MCP by default. If a worker should create its own workers, attach ReevesAgents to that worker's CLI explicitly.

Codex sandboxes MCP calls by default, which blocks tmux launches. When using Codex as the host that drives agents, run it with full access, for example codex --sandbox danger-full-access, or use a Codex profile that sets sandbox_mode = "danger-full-access".

Full tool reference: docs/mcp.md. Agent-facing operator guide: AGENTS.md.

State lives under ~/.reeves:

~/.reeves/  config.json  presets/  runs/  history/

Two environment variables override the default paths:

• REEVES_REGISTRY: state root override for runs/, history/, and presets/.
• REEVES_CONFIG: config file path override.

In the Web UI, open Config and choose Web theme → Light or Dark, then save. The choice is stored in config.json and also applies to the embedded terminal. The default is Dark. From the CLI, use reevesagents config web_theme light.

One registry per tmux server: the background orphan sweep judges session ownership against the current registry, so two registries must not share one tmux server.

Agent tasks, task notes, inbox messages and approval text are redacted for known token patterns before their state files are written.

Spread one project across multiple CLIs:

reevesagents spawn deepseek:backend claude-code:product codex:review \  --name "feature x" \  --prompt "Backend, product copy, and a review pass."

Watch one agent and then open its window:

reevesagents peek backend -n 40reevesagents open backend

Stop the run when the work is done:

reevesagents stop "feature x" --yes

reevesagents web

The Web UI binds to 127.0.0.1 only and runs in the foreground. Agents keep running after the page closes because they live in tmux.

The Web UI uses optional runtime modules, ws and @lydell/node-pty. npm installs them by default. CLI and TUI commands keep working without them, and reevesagents web explains what is missing.

To reach it from another machine, forward the loopback port over SSH:

ssh -L 8080:127.0.0.1:8080 user@host

tmux is not installed. Install tmux and run reevesagents doctor. The TUI auto-wraps itself in a tmux session named reeves; set REEVES_NO_TMUX_WRAPPER=1 to skip that behavior.

A provider CLI is missing or signed out. ReevesAgents launches provider CLIs that are already on PATH and authenticated. reevesagents doctor shows what is detected. If a launched window is waiting at login, peek shows it.

The Web UI reports missing packages. Reinstall with optional dependencies enabled, then run reevesagents doctor.

Port already in use. reevesagents web starts at 8080 by default. If it is taken, the server binds the next free port in a small range and prints the URL.

Contributor docs live under docs/. Start with CONTRIBUTING.md, testing, and releasing.

End users do not need the development toolchain. Contributors use pnpm, TypeScript, tsup, Vitest, and ESLint from the repository.