kmuxyourterminalsworldruntimeagents

The local runtime for AI coding agents.

Structured access to your projects, terminals, services, and environment.

$ brew install kmux

AI coding agents need a runtime.

Agents interact with your real dev environment but have no structured way to discover projects, access services, or isolate their work.

Without a runtime

✗Agents can’t see what services are running or on which ports
✗No isolation. Parallel agents step on each other’s code and env.
✗Terminal output is invisible to agents debugging issues
✗Every agent starts blind: no project discovery, no runtime state
✗Environment drift between sessions causes silent failures

With kmux

✓Agents query live project state, ports, and sessions via MCP
✓Each agent gets its own worktree with isolated ports and env
✓Terminal capture gives agents real debugging context
✓kmux status --json: full environment discovery in one call
✓Deterministic port ranges and env injection, every time

Works with Claude Code, Cursor, Copilot, Codex, and any MCP-compatible tool.

Three commands. Full control.

kmux — terminal

$ kmux init

✓ Project 'acme-api' registered

✓ Port range: 3100-3199

✓ Config: .kmux.yaml

$ kmux up

✓ tmux session 'acme-api' created

✓ Dev server on :3100

✓ Ready

$ kmux switch dashboard

✓ acme-api suspended (state saved)

✓ dashboard resumed

✓ Attached to dashboard

$ brew install kmux

macOS & Linux · View on GitHub

The runtime layer

🤖

MCP Server for AI Tools

Your AI tools see what’s running. Project state, live terminal output, port assignments, all queryable via Model Context Protocol.

kmux mcp serve

🌳

Worktree Isolation

Each agent gets its own git worktree with sub-allocated ports and injected env vars. Code isolation + environment isolation in one command.

kmux up my-app --worktree feature-branch

📊

Agent Observability

See every agent running across all projects. Live TUI dashboard, logs, inspect, kill. Agents are first-class runtime objects.

kmux agents watch

🔌

Port Isolation

Every project gets a 100-port range, auto-assigned. Named ports injected as env vars. .env.kmux generated on startup.

kmux port assign dev

📟

Multi-Session Workspaces

Run Claude Code, Codex, and your own dev work on the same project, each in its own session, sharing ports and env.

kmux up my-app --session claude

⚡

Instant Context Switching

One command suspends a project and resumes the target. Session, ports, env. Everything follows.

kmux switch, kmux last, kmux -

Your agents get structured access.

AI coding agents need a runtime just like apps do. kmux manages the environment underneath them, exposing project state, terminal output, and port assignments via MCP and --json. Any agent with shell access can use kmux status --json.

kmux // json

$ kmux status --json | head

{ "projects": [ { "name": "backend", "status": "running", "ports": {"dev": 3100, "api": 3101, "db": 3102}, "sessions": ["default", "claude-code"] } ] }

What’s next

v0.4

Fleet Spawning & Conflict Detection

Task queues, parallel agent coordination

v0.5

Supervision & Policy Engine

Approval gates, budgets, safety constraints

kmux is open source. Follow the roadmap on GitHub.

Built on trust

✓Open source (Apache 2.0). Inspect the code, contribute, fork.
✓Works fully offline. No network calls for core features.
✓Telemetry is opt-in and off by default. Disable via CLI, env var, or auto-detected CI.
✓kmux doctor shows exactly what’s configured.
✓All state stored in ~/.kmux/. Inspectable, deletable, yours.
✓Clean uninstall. No leftover daemons, no hidden processes.

The runtime your agents are missing.

Open source. One binary. Zero dependencies beyond tmux.

$ brew install kmuxView on GitHub

runtimeagentsservicesterminalsworldkmuxyourterminalsworldruntimeagentsterminals