reevesagents

io.github.mertkayacsPublished by GitHub account mertkayacsv2.1.0Updated Nov 2, 2026

Spawn, read and steer AI coding CLIs (Claude Code, Codex, Kimi and more) in local tmux windows.

VerifiedSTDIODesktop onlyDeveloper ToolsAI & ML

Overview

AI-generated overview

Runs and steers other AI coding CLIs (Claude Code, Codex, Kimi and more) in local tmux windows, letting one assistant spawn, read, redirect and stop them.

What you can do
  • Spawn, list and stop agents and whole runs, with saved presets for reusable agent teams
  • Read recent terminal output, paste text, press keys and interrupt a running agent
  • Request, resolve and track human approvals for risky actions
  • Inspect providers, helper tool CLIs, hosts and machine health, and attach or detach the MCP from host CLIs
  • Manage configuration, run history and cleanup of zombie agents and orphan sessions
When to use it
Use it when you want one assistant session to delegate slices of work to several coding CLIs in parallel and then poll or redirect them, or to keep long-running CLI agents alive in tmux after the UI closes.
Requirements
Local process installed from npm (Node.js 22.12+), tmux 3.0+ (or the built-in winmux on Windows), and at least one supported provider CLI installed and authenticated on PATH. macOS, Linux and WSL are supported; state lives under ~/.reeves.
Before you install
Attach only to a CLI you trust to drive local tools: it can spawn, type into, interrupt and kill other agents. Setting permissions to skip turns off worker approval prompts, and Codex hosts need a full-access sandbox to launch tmux. Stop, kill and delete commands end agents and remove records; state files are written locally with token patterns redacted.

Installation

In SourceWeft

  1. Open reevesagents in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[ReevesAgents is free and open source under the Apache-2.0 license]

[GitHub stars] [npm version] [monthly npm downloads] [total npm downloads] [node] [license] [free and open source] [CI]

ReevesAgents is free and open source under the Apache-2.0 license.

Demo · Docs · FAQ · Issues

[Claude Code] [Codex CLI] [Gemini CLI] [GitHub Copilot CLI] [Cursor CLI] [OpenCode] [Kimi Code] [Aider]

25+ coding CLIs, one workspace.

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

ReevesAgents is a local workspace for AI coding CLIs. It runs Claude Code, Codex, OpenCode, Hermes, Kimi, DeepSeek, Qwen, Pi, Aider, Gemini CLI, Cline CLI, Crush, Goose, Kilo Code, Letta Code, Mistral Vibe, Grok Build, Kiro CLI, Factory Droid, Qoder CLI, Warp, Junie CLI, GitHub Copilot CLI, Cursor CLI, Rovo Dev CLI, and other provider CLIs side by side in tmux. You can use it as a normal CLI/TUI/Web UI, or attach its opt-in MCP so one agent can spawn, read, steer, and stop the rest.

Provider logins stay inside each provider CLI. ReevesAgents keeps its own state as a few plain JSON files under ~/.reeves, and it runs only while you or an attached CLI are using it.

[A gold-framed lead pane joined by fine gold threads to eight glowing glass panes, one for each tool in a run]

Quick Start

sh
pnpm add -g reevesagentsreevesagents doctorreevesagents

Start a run from the CLI:

sh
reevesagents spawn claude-code:lead codex:tests hermes:research \  --name "release check" \  --prompt "Review the release path, test coverage, and docs."

Open the Web UI:

sh
reevesagents web

Let one attached agent drive the others:

sh
reevesagents attach codexreevesagents hosts

Restart that CLI after attach so it loads the MCP tools.

Windows

Native Windows 10 1809+ needs no WSL: reevesagents ships a built-in, tmux-compatible multiplexer (winmux) that runs panes over ConPTY. Agents keep running after you close the UI because winmux runs as a background server, just like tmux. When you attach in the TUI or CLI, the usual prefix keys work: Ctrl-b d to detach, Ctrl-b n / p to move between agent windows, Ctrl-b 0-9 to jump to a window.

What It Gives You

SurfaceUse it for
TUIKeyboard-first run control inside the terminal.
Web UILocal visual view of runs, panes, agents, approvals, and history.
CLIScripts, smoke checks, spawning, state cleanup, and tmux jumps.
Agent Control MCPOne trusted CLI can spawn and drive other CLIs through local tools.
tmuxReal provider CLI windows that keep running after the UI closes.

ReevesAgents is local by design. State is plain JSON under ~/.reeves, and the CLIs it starts are the same CLIs you already use by hand.

Tools

Four tools sit next to the coding CLIs. Perplexity CLI searches the web, Google Colab CLI runs scripts and notebooks on CPU, GPU and TPU runtimes, Hugging Face CLI downloads and uploads models and datasets and runs jobs on the Hub, and Ollama runs local or cloud models from the terminal. Agents call them from their own shell.

reevesagents tools lists the four with a purpose, an example command, and whether each is installed and signed in (for Ollama: reachable). Add --json for scripts. An agent with the MCP attached gets the same list from list_tools.

Install

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.

sh
# 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>:

sh
pnpm add -g reevesagents@<version>

Source install:

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

Screenshots

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]

Commands

No arguments launches the TUI.

CommandPurpose
reevesagentsLaunch the TUI.
spawn [spec...]Start a run. Each spec is provider[:nickname[:model]].
add [spec...]Add agents to the most recent active run.
runsList active runs.
agents [run-id]List agents across runs or inside one run.
open <id>Jump to a run or agent tmux window.
peek <agent-id>Print recent output from one agent.
send <agent-id> <text...>Paste text into an agent without submitting.
key <agent-id> <key>Send enter, escape, arrows, tab, space, backspace, or ctrl-c.
interrupt <agent-id>Send Ctrl-C to one agent.
stop <run-id>Stop a run. Requires --yes or ALLOW_DESTRUCTIVE=1.
kill <agent-id>Stop one agent. Requires --yes or ALLOW_DESTRUCTIVE=1.
setupFirst-run check. --attach connects every installed host CLI.
doctorCheck Node, tmux, state, and provider CLIs.
webStart the loopback-only Web UI.
providersList provider ids, aliases, models, and availability.
toolsList Perplexity, Google Colab, Hugging Face and Ollama with purpose, example, and install and sign-in state.
approvalsList pending approval requests.
approve / denyResolve one approval request.
hostsShow which host CLIs have ReevesAgents attached.
attach [cli]Connect the Agent Control MCP to one host CLI, or all installed hosts.
detach <cli>Remove that MCP connection from one host CLI.
skills [action]Install, remove, or inspect the ReevesAgents skill.
mcpStart the MCP server over stdio. Host CLIs run this.
config [key] [value]Show or update editable settings.
presetsList saved run presets.
save-presetSave a live run as a preset.
start-presetStart a run from a preset.
delete-presetDelete a preset.
deleteDelete one ended agent record. Requires confirmation.
delete-runDelete one ended run and archive it. Requires confirmation.
historyList archived runs.
delete-historyDelete one archived history record. Requires confirmation.
reapEnd zombie agents and agents past max_lifetime_ms, and kill orphan tmux sessions no run record owns.

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

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

sh
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:

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

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

[A gold-framed lead pane sending messages along gold threads to three other panes]

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.

Configuration

State lives under ~/.reeves:

text
~/.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.

Examples

Spread one project across multiple CLIs:

sh
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:

sh
reevesagents peek backend -n 40reevesagents open backend

Stop the run when the work is done:

sh
reevesagents stop "feature x" --yes

Web UI
sh
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:

sh
ssh -L 8080:127.0.0.1:8080 user@host

Troubleshooting

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.

Contributing

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.

Cite this

bibtex
@software{kaya2026reevesagents,  author = {Mert Kaya},  title = {ReevesAgents: Local tmux workspace for AI coding CLIs},  year = {2026},  license = {Apache-2.0},  url = {https://github.com/mertkayacs/reevesagents},  version = {1.8.2}}

Links

[Eschatia Labs]
An Eschatia Labs project by Mert Kaya.

Source: README.md at commit 5ac9b27

Tools

31

spawn

Start a CLI agent in its own tmux window and return its agent_id (use it with send_text, send_key, read, kill) and run_id. Omit run_id to add the agent to this MCP session run, created on the first spawn so a chain of spawns stays in one run; pass run_id to add it to an existing run. Call list_providers for valid provider keys.

Parametersnametaskmodeleffortrun_idnicknameproviderrequiredauth_modeextra_argspermissionsworking_dir

kill

Stop one agent and close its tmux window. Pass an agent_id from spawn or list. Once it is ended you can remove its record with delete.

Parametersagent_idrequired

stop

Stop a whole run: end every agent in it and tear down its tmux session. Pass a run_id from spawn or list. Once ended, remove it with delete_run.

Parametersrun_idrequired

send_text

Paste text into one agent at its prompt. This does NOT submit it: follow with send_key enter to send. Use it to give a running agent a new instruction.

Parameterstextrequiredagent_idrequired

send_key

Press one key in an agent: enter, escape, tab, space, up, down, left, right, backspace, or ctrl-c. Send enter after send_text to submit the pasted text.

Parameterskeyrequiredagent_idrequired

interrupt

Press ctrl-c in one agent to interrupt whatever it is doing.

Parametersagent_idrequired

read

Read one agent's recent terminal output, ANSI-stripped and secret-redacted. Use it to see what the agent printed or is waiting on. Defaults to the last 20 lines.

Parameterslinesagent_idrequired

list

List every live run and the agents in each, with their ids, status, provider, and tmux info. Start here to find a run_id or agent_id for the other tools. Ended runs are in list_history.

Takes no parameters.

list_providers

List the CLI providers this machine can launch: id, display name, whether it is installed, aliases, and known models. Pass an id as the provider for spawn.

Takes no parameters.

list_tools

List the helper tool CLIs on this machine (Perplexity, Google Colab, Hugging Face, Ollama): what each is for, whether it is installed, and its state (signed in, or reachable for Ollama), plus an example command and a docs link. They are not spawn providers; run them from your own shell.

Takes no parameters.

request_approval

Ask for approval before a risky action. Creates a pending approval that a human or another agent clears with resolve_approval, and returns it with its approval_id.

Parametersriskactionrequireddetailssummaryrequiredagent_idrequired

resolve_approval

Approve or deny one pending approval by its approval_id (from list_approvals). An optional note records why.

Parametersnotedecisionrequiredapproval_idrequired

check_approval

Read one approval's current status (pending, approved, denied, or expired) by its approval_id.

Parametersapproval_idrequired

list_approvals

List approval requests, optionally filtered by run_id or status (pending, approved, denied, expired). Use it to find an approval_id to resolve.

Parametersrun_idstatus

list_history

List archived run history: runs that have ended or gone stale. Live runs are in list, not here.

Takes no parameters.

delete

Permanently remove one ended agent's record. Kill the agent first; a still-running agent is rejected.

Parametersagent_idrequired

delete_run

Permanently remove one ended run, archiving it to history. Stop the run first; a still-running run is rejected.

Parametersrun_idrequired

delete_history

Permanently remove one archived run history record by its id (from list_history).

Parametersidrequired

open

Open a run or agent in tmux for the user: switch the attached tmux client to a run (its reeves tab) or to a specific agent window. Works for any run, whether this agent started it or not, so you can surface any run for the user on request. No effect when nobody is attached.

Parametersidrequired

doctor

Check this machine for running agents: tmux availability, which provider CLIs are installed, and the state directories. Returns each check with an ok/warn/fail status and a detail string. Run it when a spawn fails to see what is missing.

Takes no parameters.

reap

Sweep for zombie agents and orphan tmux sessions: ends any agent whose tmux window has died or that is older than max_lifetime_ms when that is set above 0 (see get_config), and kills reeves-*/reevesweb_* sessions no live record owns. Returns each reaped agent with the reason (window-gone or lifetime-exceeded) and its age, plus the killed orphan session names. This runs on its own in the background; call it to force an immediate sweep, e.g. after a crash or before relying on list.

Takes no parameters.

get_config

Read the global reevesagents settings: peek_interval_ms, peek_lines, max_depth, max_agents (the per-run agent cap), ready_delay_ms, max_lifetime_ms (auto-reap agents older than this; 0 disables), default_permissions, and language. Check max_agents here when a spawn is rejected for hitting the cap.

Takes no parameters.

set_config

Change one or more global settings and save them. Pass only the fields to change. Counts must be positive integers (ready_delay_ms and max_lifetime_ms may be 0); default_permissions is ask or skip; language is a supported code such as en or tr. Example: raise the per-run agent cap with { "max_agents": 20 }, or auto-kill agents running longer than an hour with { "max_lifetime_ms": 3600000 }. Returns the saved settings.

Parameterslanguagemax_depthweb_thememax_agentspeek_linesready_delay_msmax_lifetime_mspeek_interval_msdefault_permissions

list_presets

List saved run presets: reusable agent-team templates, each with a root agent and workers. Launch a whole team at once by passing a preset name to start_preset.

Takes no parameters.

save_preset

Save a live run's agent line-up as a reusable preset under a name, so the same team can be relaunched later with start_preset. Pass a run_id from list. Re-saving the same name updates it. Note: a captured agent's auth_mode and effort are not stored (they default).

Parametersnamerequiredrun_idrequireddescription

start_preset

Launch a new run from a saved preset (see list_presets), starting its root agent and every worker at once. Optionally override the run name and working_dir. Returns the new run and its agents.

Parametersnamerequiredrun_nameworking_dir

delete_preset

Permanently delete a saved preset by its name (from list_presets). Does not affect any running run.

Parametersnamerequired

list_hosts

List the AI CLIs on this machine that can host the reevesagents MCP and whether reevesagents is attached to each. Use it to see where this control surface is wired before attach_host or detach_host.

Takes no parameters.

attach_host

Attach the reevesagents MCP to one host CLI by its key (from list_hosts), or to every installed host when key is omitted. After attaching, that CLI can drive agents through these same tools.

Parameterskey

detach_host

Detach the reevesagents MCP from one host CLI by its key (from list_hosts). The CLI keeps running but can no longer drive agents through reevesagents.

Parameterskeyrequired

install_skills

Install the reevesagents Agent Skill so skill-aware CLIs (Claude Code, Codex, Kimi, OpenCode) learn to drive reevesagents on their own. Writes one SKILL.md to the two shared skill directories under the home dir. Pass no arguments; call with status omitted to install, or read the returned rows to see where it landed. The user must restart their CLIs to pick it up.

Parametersstatus

Version history

7
  1. v2.1.0LatestOct 26, 2026
  2. v2.0.0Oct 18, 2026
  3. v1.9.1Oct 17, 2026
  4. v1.9.0Oct 16, 2026
  5. v1.8.2Oct 10, 2026
  6. v1.8.1Oct 9, 2026
  7. v1.8.0Oct 9, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts