camacho-mcp

camacho-mcp

Persistent tmux terminal for AI agents — zero dependencies, real-time spectating, SSH host-group dispatch.

Named after President Dwayne Elizondo Mountain Dew Camacho — humble enough to recruit intelligence, brave enough to act on it.

Note: DO NOT USE IN PRODUCTION. This is a proof of concept. Please report any glitches.

See it in action

You just talk to Copilot in plain English. It figures out which tools to call.

You: "SSH to all the webservers and compare disk usage"

Copilot calls president_camacho_execute with { command: "df -h /", hosts: ["webserver*"] } — it resolves webserver* against your ~/.ssh/config, SSHes into each matching host simultaneously, runs the command, and returns the results side-by-side. You watch it happen live in the tmux spectator window.

You: "Which servers have packages waiting to be upgraded?"

Copilot runs apt list --upgradable across all hosts and summarizes the differences.

You: "Compare the apache config on the two web hosts"

Copilot SSHes in, finds the config files, cats them from both servers, and diffs the output — calling out exactly what's different.

You: "Run a build in the background and let me know when it's done"

Copilot uses execute_async to fire the build, then polls with pane_status and get_pane_output until it completes.

More examples

"Run uname -a"                              → single command, default pane
"Check memory on all webservers"            → SSH host-group dispatch
"Compare /etc/fstab across prod servers"    → multi-host diff
"Start the dev server in pane 0.1"          → target a specific pane
"Send Ctrl+C to pane 0.0"                   → interrupt a running command
"What's running in each pane?"              → list_panes

Hosts are resolved from your ~/.ssh/config — wildcards like webserver*, prod*, staging* just work. SSH failures are detected automatically and reported with the error instead of running commands locally.

Install

npx -y camacho-mcp

VS Code / GitHub Copilot

Add to settings.json or .vscode/mcp.json:

{
  "servers": {
    "camacho-mcp": {
      "command": "npx",
      "args": ["-y", "camacho-mcp"]
    }
  }
}

Claude Desktop, Cursor, JetBrains, etc.

{
  "mcpServers": {
    "camacho-mcp": {
      "command": "npx",
      "args": ["-y", "camacho-mcp"]
    }
  }
}

Requirements

• Node.js >= 22 — nodejs.org
• tmux — Linux/macOS native, or WSL on Windows

Watch it live

tmux attach -t camacho-mcp

The session starts with two side-by-side panes. Additional panes auto-tile into a grid — up to 12 per window, then a new window is created. Use Ctrl+b n/p to switch windows.

Tools

Tool	What it does
president_camacho_execute	Run a shell command (multi-pane parallel, SSH host-groups, optional quiescence wait)
execute_async	Fire a command and return immediately — poll with get_pane_output
get_pane_output	Read current output from any pane without running a command
send_keys	Send raw keys to a pane — Ctrl+C, Ctrl+D, Enter, Escape, arrow keys
pane_status	Check if a pane is running a command or idle at a prompt
screen_snapshot	Rendered terminal view with ANSI colors — what a human sees (for TUIs)
list_panes	List all active panes with current command and size
spawn_pane	Add a new pane (overflows to new windows)
reset_panes	Reset to default 2-pane layout
open_spectator	Open a spectator terminal to watch the AI work in real-time

Environment variables

Variable	Default	Description
CAMACHO_MCP_CLEANUP_DELAY	2000	Milliseconds before stale panes are auto-cleaned (0 = disabled)
CAMACHO_MCP_MAX_PANES	12	Max panes per window before overflow
CAMACHO_MCP_SPECTATOR	true	Auto-open spectator terminal on first command (false = disabled)
CAMACHO_MCP_LOG	false	Enable daily log files
CAMACHO_MCP_LOG_DIR	~/.camacho-mcp/logs	Log directory

Optional: tmux config

git clone https://github.com/sanchirico/camacho-mcp.git
cd camacho-mcp
./setup.sh

Installs mouse support, scroll mode, and keybindings:

Key	Action
Ctrl+b R	Reset panes to default layout
Ctrl+b =	Even-vertical layout
Ctrl+b [	Scroll mode (vi keys, q to exit)

Planned improvements

• Secure password input — send_password that suppresses echo and log output for sudo, SSH passwords, key passphrases
• Session transcripts — per-pane transcript and command logs with metadata, not just daily log files
• Database queries — run SQL against Postgres/MySQL/SQLite from the tmux session and return structured results
• File transfer — scp/rsync commands across SSH host-groups with progress tracking

Publish

npm publish

Register on the MCP registry:

mcp-publisher login github
mcp-publisher publish

Similar projects

This project will probably be obsolete in a week. The MCP ecosystem moves fast. Here's what else is out there doing similar things — terminal access for AI agents:

Project	Stars	What it does
DesktopCommanderMCP	5.5k	All-in-one: terminal + filesystem search + diff editing + Docker isolation
ssh-mcp	9	Pure SSH fleet management — group hosts, run commands across machines simultaneously
ssh-mcp	301	MCP server exposing SSH control for Linux servers via Model Context Protocol.
mcp-console-automation	21	40 tools, 50 concurrent sessions, background jobs with priority queue — Playwright for terminals
PiloTY	27	True PTY-backed persistent sessions — handles password prompts, REPLs, TUI screen snapshots

Advanced orchestration

And then there's a whole other level — multi-agent swarm orchestration, container isolation per agent, shared task lists with inter-agent messaging. These projects coordinate entire teams of AI agents working in parallel. Different league.

Project	Stars	What it does
Claude Code Agent Teams	—	Anthropic's own multi-agent coordination — each teammate gets a split pane in tmux or iTerm2, shared task list, direct inter-agent messaging. Experimental, requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. tmux has known limitations on certain OSes and traditionally works best on macOS.
cli-agent-orchestrator	256	AWS-backed supervisor/worker system — orchestrates Claude Code, Kiro, Codex, Q CLI agents in tmux with cron-scheduled flows
container-use	3.6k	Each agent gets its own container + git branch — full isolation, real-time visibility, standard git merge workflow
Agent-MCP	1.2k	Ephemeral agents with a shared knowledge graph, file-level locking, and a real-time network visualization dashboard
claude-flow	14.4k	60+ specialized agents, 175+ MCP tools, swarm topologies with Raft consensus, HNSW vector memory, plugin marketplace
tmux-beads-loops	1	Git-backed dependency-aware issue graph — agents claim tasks and report back to a manager pane via hooks

License

MIT — see LICENSE