Project BareMetal-Tmux

A decoupled, stateful, interactive MCP (Model Context Protocol) Tmux tool. It exposes a persistent host tmux session to MCP clients — GitHub Copilot CLI, ForgeCode, VS Code — over the stdio transport. No containers, no network: raw JSON-RPC text streams straight into bare-metal shell execution.

Interactive terminal state survives agent crashes, context compaction reloads, and framework restarts, because the shell lives in a detached tmux session (local_agent_workspace) owned by the host — not by the agent process.

Architecture

Upstream Client (Copilot CLI / ForgeCode / VS Code)
  │  spawns subprocess, speaks JSON-RPC over stdio
  ▼
Local MCP Server  (server.py — Python 3.11+, fastmcp)
  │  validates schemas, applies SR-01 safety checks, strips ANSI
  ▼
Host OS Shell  (persistent detached tmux session, 20k-line scrollback)

Related MCP server: codex-mcp-server

MCP Tools

The session is created lazily on first tool invocation (FR-01) with a 20,000-line history limit.

Safety Guardrails (SR-01)

Execution is un-sandboxed on the host, so the server refuses destructive commands before they reach the tmux buffer:

• Recursive rm aimed at / or top-level system roots (/usr, /etc, …), including sudo-wrapped and &&/;-chained variants

• --no-preserve-root, mkfs.*, dd of=/dev/..., redirects onto block devices, fork-bomb signatures

Workspace-scoped destruction (e.g. rm -rf ./build, /tmp/...) passes through.

Requirements

• Windows host: WSL distro Ubuntu-24.04 with tmux installed (the server runs inside WSL; clients launch it via wsl.exe)

• Linux/macOS host: just tmux on PATH — drop the wsl.exe wrapper and run uv run python server.py directly

• uv (installed user-locally, e.g. curl -LsSf https://astral.sh/uv/install.sh | sh)

• Python ≥ 3.11 (resolved by uv)

Setup

Dependencies are isolated in a uv-managed venv. On WSL, keep the venv on ext4 (not /mnt/c) for speed:

cd /mnt/c/Users/troll/Python/tmux-harness
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/tmux-harness"
uv sync

Run the smoke test (28 checks: ANSI stripping, SR-01 guardrails, live tmux round-trips against a throwaway session):

TMUX=harness_smoke_test uv run python tests/smoke_test.py

Client Integration

GitHub Copilot CLI

Two options:

1. Custom agent (recommended) — .github/agents/tmux.agent.md is a self-contained agent profile: it defines the MCP server in its frontmatter and allowlists only the three harness tools (no shell, no file edits, no web). Use it with:

   /agent                          # pick "tmux" interactively
   copilot --agent=tmux -p "run the test suite and watch for failures"

2. Global MCP server — merge mcp-config.copilot.json into ~/.copilot/mcp-config.json to expose the harness tools in every session (all built-in tools remain available).

ForgeCode

.mcp.json sits at the project root and is picked up automatically when ForgeCode runs from this directory.

VS Code

Add the same server block from .mcp.json to .vscode/mcp.json.

Configuration

Project Layout

server.py                     MCP server (tools, SR-01 checks, ANSI stripping)
pyproject.toml                uv project: mcp[cli] + fastmcp
tests/smoke_test.py           28-check verification suite
.github/agents/tmux.agent.md  Copilot CLI custom agent (harness tools only)
mcp-config.copilot.json       Copilot CLI global MCP config
.mcp.json                     ForgeCode project-root MCP config