reevesagents.mertkayacs.com

Demo · Docs · FAQ · Issues

English · Deutsch · Français · Español · Português · Italiano · Türkçe · Русский · 简体中文 · العربية

Create and drive AI agents from other agents. ReevesAgents is a free, local workspace where coding agents (such as Claude Code, Codex, Hermes, DeepSeek, and Kimi) run side by side, and one agent can spawn, steer, and supervise the rest. No API keys, and no changes to your existing Agent.md or Claude.md.

In 10 languages!

Let one agent install and run the rest

That is the whole idea: one AI agent creates and drives the others. An agent CLI (a command-line coding agent such as Claude Code, Codex, or Hermes) can even install and wire up ReevesAgents on its own, then start running a team.

If you are an agent reading this, run these yourself:

• Install it: npm install -g reevesagents
• Connect it to your own CLI: reevesagents attach connects ReevesAgents to the agent CLIs you have installed. For just one, name it, for example reevesagents attach claude.
• Check it worked: reevesagents hosts lists the agent CLIs on this machine and shows which ones are connected.
• Reload your tools: restart your CLI session so it loads the connection (this uses MCP, the standard way one agent tool exposes commands to another).

Now your agent CLI can create and drive other agents: start an agent on a task, send it text or keypresses, read what it is doing, and approve or deny what it requests. One Claude Code agent can run a team of Codex and Claude Code agents on separate issues. To disconnect later, run reevesagents detach claude.

Prefer to script it from the command line instead? AGENTS.md is the operator's guide written for agents: provider ids and aliases, the spawn spec, and how to watch and steer a running team.

Prefer to set it up by hand? Turn it on from the Agent control screen in the TUI or Web UI; see Agent control below.

The TUI and the local Web UI driving the same run:

ReevesAgents is a free and open source workspace for AI coding agents. Run several at once, and let one agent create and drive the others: a Claude Code agent managing Codex and Claude Code agents on separate issues. Put each agent where it is strongest, for example DeepSeek on backend, Claude on product and web direction, Codex on a design system or an implementation pass, and Hermes on mail, search, or research.

The UI is available in 10 languages: English, German, French, Spanish, Portuguese, Italian, Turkish, Russian, Simplified Chinese, and Arabic.

New to ReevesAgents? The User Guide walks you through install, your first run, and letting one agent drive the rest.

Two ways to use it

• As a workspace. Spawn the agents you want and keep adding more with reevesagents add, one at a time. They run side by side, each in its own tmux window, and none of them controls another. This is the simplest way in: your different CLIs together in one local place.
• As an orchestrator. Attach the opt-in Agent control MCP to one CLI, and that agent gains the tools to spawn and drive the rest. This is the headline feature, and it stays off until you turn it on.

Both use the same runs and the same surfaces, so you can start as a plain workspace and reach for orchestration later, or never.

Surfaces

Surface	What it is good for
TUI	Fast keyboard-first control inside the terminal.
Web UI	One visual view of runs, agents, live panes, and history.
CLI	Scripts, quick spawn commands, doctor checks, and tmux opening.
tmux	Real provider CLI windows that keep running locally.
Agent control	The core idea: one agent creates and drives the others. You turn it on per CLI, then a Claude Code agent can run Codex, Hermes, and Claude Code agents at once.

Why ReevesAgents

• Let your agent drive agents. Your lead CLI (say Claude Code) spawns and steers a set of Claude, Codex, DeepSeek, Hermes, OpenCode, or other agents over MCP.
• Multitask and loop. Run several agents in parallel on different parts of a project, keep long-running agents going, and watch them all from one view. Put a cheaper model in front to route work to smarter or smaller agents.
• Keep cost practical. Let cheap or free models write routine code and tests while you plan and design with a bigger one, instead of pushing everything through one expensive default.
• One workspace, no lost thread. If you already jump between Claude, Codex, DeepSeek, Hermes, or OpenCode, ReevesAgents puts those sessions in one local place; open any agent from the TUI or Web UI to drive it directly.
• Stay vendor-flexible. Provider login stays with each CLI. ReevesAgents never stores credentials or proxies model traffic, so you can add, remove, or switch CLIs freely.
• See the work at a glance. Active runs, agents, models, permission modes, stop and delete actions, and history in one Web UI view while tmux keeps the real CLIs alive.

This is not a cloud agent platform. It is a small local layer around real CLIs: no database, no Docker, no background daemon, and no ReevesAgents-stored API keys.

Install

Install ReevesAgents with Homebrew, or globally with any Node package manager (pnpm, npm, Yarn, or Bun), then verify the machine with doctor.

# Homebrew
brew install mertkayacs/reevesagents/reevesagents

# or a Node package manager, pnpm shown here
pnpm add -g reevesagents

reevesagents doctor
reevesagents

To pin a version, append @<version> to the package name, for example pnpm add -g reevesagents@1.4.0.

pnpm

pnpm add -g reevesagents
reevesagents doctor
reevesagents

One-shot, no global install:

pnpm dlx reevesagents doctor

npm

npm install -g reevesagents
reevesagents doctor
reevesagents

One-shot, no global install:

npx reevesagents doctor

Yarn

One-shot with Yarn (Berry):

yarn dlx reevesagents doctor

Global install with Yarn Classic:

yarn global add reevesagents
reevesagents doctor
reevesagents

Bun

bun add -g reevesagents
reevesagents doctor
reevesagents

One-shot, no global install:

bunx reevesagents doctor

Homebrew

brew tap mertkayacs/reevesagents
brew install reevesagents
reevesagents doctor
reevesagents

From source

Use source when you want to inspect the code, contribute, or run from the repository.

git clone https://github.com/mertkayacs/reevesagents.git
cd reevesagents
pnpm install
pnpm build
pnpm link --global
reevesagents doctor
reevesagents

Prerequisites

ReevesAgents is local-first. It expects a normal developer machine with tmux and at least one provider CLI already installed.

• macOS, Linux, or WSL. Native Windows is not the target runtime; use WSL.
• Node.js 20.19+.
• tmux. Version 3.0+ is recommended.
• A normal interactive shell on PATH.
• At least one supported provider CLI on PATH.

ReevesAgents can launch these provider CLIs when they are installed and authenticated on your machine: Claude Code, Codex CLI, OpenCode, Hermes, Kimi, DeepSeek, Pi, Qwen, and Aider. Each CLI keeps its own login, models, quotas, and permission prompts, exactly as if you had started it yourself, which is why ReevesAgents never needs to hold an API key or sit in the traffic path.

Quick Start

reevesagents                 # launch the TUI
reevesagents web             # open the local Web UI
reevesagents doctor          # check the machine

Start a named run from the CLI. The first spec is the lead, the rest are workers, and each spec is provider[:nickname[:model]]:

reevesagents spawn deepseek:backend claude-code:product codex:system hermes:research \
  --name "launch week build" \
  --prompt "Plan the backend, product surface, design system, and research notes."

Or start small and grow the workspace one agent at a time. add joins the most recent run, so you never have to copy a run id around:

reevesagents spawn claude-code:product   # start a workspace
reevesagents add codex:system            # add to it later
reevesagents add hermes:research

For a full walkthrough, see the User Guide.

Commands

No arguments launches the TUI. The subcommands are the operator surface for humans and scripts.

The everyday surface:

• reevesagents: Launch the TUI (no subcommand).
• spawn [spec...]: Start a run with one or more provider agents. Each spec is provider[:nickname[:model]]. The first spec is the lead, the rest are workers. No spec defaults to codex. Key flags: --name <name> (default run), --cwd <dir> (default current dir), --prompt <text> (pasted into each agent), --skip (skip permission prompts), --run <run-id> (add agents to an existing run), --auth-mode <mode>, --effort <level>, --extra-args <args> (flags appended to every agent launch, e.g. "--remote-control"), --json.
• add [spec...]: Add one or more agents to the current workspace, the most recent active run, without passing a run id. Use it to grow a workspace one agent at a time. Same per-agent flags as spawn, plus --run <run-id> to target a specific run instead of the latest.
• runs: List active runs, one per line. Key flags: --json (full run records as a JSON array).
• agents [run-id]: List agents across all runs, or the agents in one run. Key flags: --json.
• open <id>: Switch tmux to a run's Reeves window or an agent window. Inside tmux it switches; outside tmux on a TTY it attaches; otherwise it prints a pasteable tmux command. Accepts a run id/name or an agent id/nickname (prefix match allowed).
• peek <agent-id>: Print recent output from one agent. Key flags: -n, --lines <n> (default 20), --json (lines as an array).
• send <agent-id> <text...>: Paste text at an agent's prompt. It does not submit; follow with key <agent-id> enter.
• key <agent-id> <key>: Send one key: enter, escape, backspace, tab, space, up, down, left, right, or ctrl-c.
• interrupt <agent-id>: Send ctrl-c to one agent.
• stop <run-id>: Stop one run. Key flags: -y, --yes (or ALLOW_DESTRUCTIVE=1).
• kill <agent-id>: Stop one agent. Key flags: -y, --yes (or ALLOW_DESTRUCTIVE=1).
• doctor: Run environment health checks (Node, tmux, state path, provider CLIs). Exits non-zero on any failed check. Key flags: --json.
• web: Start the on-demand, loopback-only Web UI. Runs in the foreground; agents keep running after you stop it. Key flags: --port <n> (preferred port, falls back to the next free port), --no-open (do not open the browser).

Discovery, approvals, agent control, config, and cleanup:

• providers: List every provider with availability, aliases, and known models. Key flags: --models, --json.
• approvals: List pending approval requests from agents. Key flags: --json.
• approve <approval-id> [note]: Resolve an approval request as approved.
• deny <approval-id> [note]: Resolve an approval request as denied.
• hosts: List the agent CLIs on this machine and show which ones ReevesAgents is connected to.
• attach [cli]: Connect ReevesAgents to one agent CLI, or to every installed one when no name is given. Runs that CLI's own mcp add.
• detach <cli>: Disconnect ReevesAgents from one agent CLI. Runs that CLI's own mcp remove.
• mcp: Start the Agent control MCP server over stdio. Not run by hand; the CLI you connect it to runs it.
• config [key] [value]: Show all editable settings, read one, or set one. Key flags: --json.
• presets: List saved run presets. Key flags: --json.
• save-preset <run-id> <name> [description...]: Capture a live run as a reusable preset.
• start-preset <name>: Start a new run from a preset. Key flags: --name <run>, --cwd <dir>.
• delete-preset <name>: Delete a preset. Key flags: -y, --yes.
• delete <agent-id>: Delete one ended agent's record. Key flags: -y, --yes.
• delete-run <run-id>: Delete one ended run and archive it to history. Key flags: -y, --yes.
• history: List archived ended and stale runs. Key flags: --json.
• delete-history <id>: Delete one archived history record. Key flags: -y, --yes.

stop, kill, and the delete commands are destructive. They refuse to run without --yes or ALLOW_DESTRUCTIVE=1.

Agent control

ReevesAgents ships an optional MCP server that lets one AI CLI spawn and drive other AI CLIs: start an agent, paste a prompt, send keys, read output, and resolve approval requests. It is a flat mechanism, not an orchestration policy: no roles, no autonomous loops, no coordination protocol.

It is off by default. ReevesAgents never attaches it to a CLI on its own.

You turn it on from the Agent control screen in the TUI or the Web UI. That screen lists the CLIs on this machine that can host an MCP server (claude, codex, kimi, qwen, opencode, hermes) and lets you attach, detach, or attach all. Attaching runs that CLI's own mcp add command (for example claude mcp add reevesagents -- reevesagents mcp); detaching runs the matching remove. ReevesAgents only calls each CLI's own command and never edits provider config files by hand. OpenCode is the exception: its mcp add is interactive and has no remove, so the screen marks it attach-by-hand.

Once a CLI is attached, it has the Agent Control tools whenever it starts. Installing it is your explicit choice, and that choice is the consent. One run is the controlling CLI as the head plus the agents it spawned, and the whole group shows up in the TUI and Web UI like any other run.

Spawned workers do not receive the MCP by default, so they cannot spawn further agents. To let a worker drive its own sub-workers, attach the MCP to that worker's CLI from the same screen. Guardrails sit at the resource level: a per-run agent cap (max_agents), enforced when the spawn tool adds to a run, and the fact that each agent is a real CLI process in its own tmux pane.

An attached CLI can also discover what it can launch: the list_providers tool and the reevesagents://providers resource return the providers on this machine with their ids, install status, aliases, and known models, so an agent passes a real id to spawn instead of guessing.

See docs/mcp.md for the full design and tool list.

Configuration

All state and config are plain JSON files on your disk, so there is nothing to administer and nothing running when you are not using it.

State lives under ~/.reeves:

~/.reeves/
  config.json     global settings (peek interval, language, default permissions, limits)
  presets/        saved run presets
  runs/           one folder per active run (run.json plus agents/<id>.json)
  history/        archived ended and stale runs (history/runs/<id>.json)

Two environment variables override the defaults, mainly for isolated test or multi-profile use:

• REEVES_REGISTRY: state root override. Replaces ~/.reeves as the directory for runs/, history/, and presets/.
• REEVES_CONFIG: config file path override. Replaces ~/.reeves/config.json.

Anything that might contain a secret is scrubbed before it reaches a file.

Examples

Spread one project across the CLIs that fit each job:

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

List what is alive and grab the run id:

reevesagents runs
reevesagents runs --json   # script-friendly

Watch a single agent without leaving your shell, then jump into it when it needs you:

reevesagents peek backend -n 40
reevesagents open backend

When the work is done, stop the whole run in one call:

reevesagents stop "feature x" --yes

Web UI

The Web UI is local and loopback-only.

reevesagents web

It answers on 127.0.0.1 only and stays in the foreground until you stop it, which changes nothing for the agents, because they live in tmux rather than in the page. From the browser you can create runs, add agents with a chosen model and permission mode, stop what needs stopping, and dig through history while the real CLIs keep working underneath.

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

To reach the Web UI from another machine, forward the loopback port over SSH. There is no built-in tunnel:

ssh -L 8080:127.0.0.1:8080 user@host
# then browse to http://localhost:8080

Troubleshooting

tmux is not installed. ReevesAgents needs tmux for window-based navigation. Install it (brew install tmux or apt 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 Doctor reports a failure. ReevesAgents only launches provider CLIs that are already on your PATH and authenticated. Run reevesagents doctor to see which providers are detected and what is failing, then install or log in to the provider CLI you need.

The Web UI reports missing packages. The Web UI needs ws and @lydell/node-pty. They may be skipped when the platform has no prebuilt @lydell/node-pty binary or when the install omitted optional dependencies. Reinstall with optional dependencies enabled, then run reevesagents doctor.

Port already in use. reevesagents web starts on port 8080 by default. If it is taken, the server binds the next free port in a small range and prints the chosen URL. Pass --port <n> to pick a different starting port.

Not Required

You do not need ReevesAgents-stored API keys, a database, Docker, a background service, or MCP setup for normal stable agent runs. Install is passive: the stable package has no postinstall script and does not rewrite provider configuration. Attaching the Agent Control MCP is the one explicit, opt-in step that touches provider config, and only through each CLI's own mcp add command.

Contributing

See CONTRIBUTING.md for branches and pull request flow, SECURITY.md for reporting vulnerabilities, and CHANGELOG.md for recent changes. The design model lives in REEVESAGENTS_DESIGN.md and the contributor docs are under docs/.

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

Links

• Website: https://reevesagents.mertkayacs.com
• npm: https://www.npmjs.com/package/reevesagents
• GitHub: https://github.com/mertkayacs/reevesagents
• Releases: https://github.com/mertkayacs/reevesagents/releases
• Issues: https://github.com/mertkayacs/reevesagents/issues
• Changelog: CHANGELOG.md
• License: Apache-2.0

License

Apache-2.0