omux

Install

Requires Node 20+ and tmux.

```bash

Demo

Click the thumbnail to play the demo (~70 MB MP4).

Configure

Minimum config:

{
  "defaultAgent": "claude-code",
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-..."
  }
}

Or run omux config for an interactive TUI. Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) are read as fallbacks. To run Claude Code and Codex side by side, add "enabledAgents": ["claude-code", "codex"] — the MainAgent only ever launches adapters in that list.

Supported LLM providers: OpenAI, Anthropic, OpenRouter, DeepSeek, Gemini, Groq, Mistral, xAI (Grok), Together, Moonshot (Kimi), MiniMax, Ollama.

FAQ

Does omux decide which CLI agent to use for a task? Within the adapters you've enabled, yes. The MainAgent sees every active adapter and its characteristics (listed under "Agent Capabilities" in its prompt) and picks per task by fit — lead with Codex for gnarly single-point reasoning and deep debugging, lean Claude Code for broad multi-file work and tight edit→test→rerun loops, then have the other one review (see the execute-then-review FAQ below). If you've enabled only one adapter there's nothing to choose — it just runs that. The menu is always exactly the adapters you turned on: it never silently pulls in a tool you didn't enable. Roles aren't hard-wired — either can implement, either can review; the implement/review split is a heuristic, not a fixed division of labor.

Can I run Claude Code and Codex together? Yes — as of v3.0.0 it's a headline feature. Enable both adapters and omux runs an execute-then-review loop in a single session: Claude Code implements, then a separate Codex agent independently reviews the diff — correctness, edge cases, regressions — and routes fixes back. They stay distinct agents you address individually, and the roles are interchangeable: either can implement, either can review. The default heuristic is Claude-implements / Codex-reviews; you override per task. (Want two fully independent sessions instead? Run two omux instances on different ports.)

Why scope MCPs per-agent instead of globally? Because tool-soup hurts. Every MCP you load injects its tool descriptions into the system prompt of every agent that has it enabled. A docs agent doesn't need your Postgres MCP, and the LLM gets distracted by tools it'll never call. omux lets you give each agent a focused toolset — smaller prompts, faster decisions, no name collisions. Per-agent skill scoping is on the way next.

Why two-tier memory (global + project)? Some things you teach an agent are about you — your coding style, your tone, your colleagues' names. Re-teaching that every time you cd into a new repo is wasteful. Other things are about this codebase — its conventions, its open todos, its architectural quirks — and shouldn't bleed into unrelated projects. omux splits memory into both layers and searches them together. Both run on the same hybrid-search index and the same editing tools, so the experience is identical at either level.

Can I change the context window size? You usually don't have to — omux derives the window from the model id (claude → 200k, gemini / gpt-4.1 → 1M, 500k fallback for unrecognized models). To override: --context-window at launch, or context.contextWindowLimit in ~/.omux/config.json. omux watches usage and auto-compresses (or flushes to memory) when you cross the threshold, so you can match the window to your model and budget without babysitting it.

Why tmux and not the Anthropic SDK / OpenAI Assistants API? Because the experience of Claude Code or Codex is not in their API — it's in their TUI. The interactive confirmations, the step-by-step reasoning, the "here's what I'm about to do" preview — all of that is TUI output. Wrapping the API strips it. Driving the TUI keeps it, and as a bonus you get compatibility with any CLI agent that ever ships.

How does state detection work across agents that update their UI differently? Each adapter declares its own regex patterns. When Claude Code 2026.04 changes its prompt format, you edit one file. The core orchestrator doesn't know or care.

Does omux need its own API key? Yes — one, for the MainAgent's reasoning. The coding agents use whatever keys they already use. You pay twice in tokens but the MainAgent's traffic is much smaller than the coding agents'.

Can I chat in one language while the agents work in another? Yes. omux auto-detects your locale (or you can set locale in ~/.omux/config.json — zh-CN and en-US are supported today) and uses it for the chat UI and the MainAgent's replies to you. The briefs the MainAgent writes into the coding agents are a separate, steerable channel: tell it once to brief sub-agents in English and it will — so you can read and write in Chinese while Claude Code or Codex gets briefed in English (or any combination). Useful if you think faster in your native language but want the coding agent's reasoning trace to stay in the language its training data is densest in.

Can I run this on a remote server? Yes. tmux is designed for detached sessions. SSH in, start omux, detach, come back hours later, pick up where you left off. This is actually the main mode I use it in.

Can I grab the wheel while an agent is mid-run? Yes. Any agent pane can be taken over from the web UI: you get the live terminal, your keystrokes go straight in, and the MainAgent keeps its hands off that agent until you release it back. For lighter touches, /stop halts the MainAgent between rounds — and it can itself interrupt a sub-agent it catches going off-track.

What happens if the omux server dies mid-task? Less than you'd fear. Sub-agents live in tmux, not in the server process — they keep working right through a server crash or restart. On startup omux re-adopts running omux-* (and legacy cliclaw-*) sessions, restores the conversation from SQLite, and repairs any tool call that was interrupted mid-flight.

Why "omux"? orchestrate × tmux — the orchestrator that lives where your agents live. (omux is the new name of cliclaw.)