cliclaw

Run your CLI coding agent unattended, in parallel, at scale.

cliclaw is a meta-agent that orchestrates the CLI coding agent of your choice — Claude Code, Codex, or anything else — through tmux. It spawns multiple instances, handles state and confirmations, remembers across sessions, and lets you walk away.

Demo video · How it works · Install · FAQ

The problem

Claude Code and Codex are great at writing code. They are less great at the parts around writing code:

• You can't walk away. They pause on every destructive action, ask you to confirm, ask you to pick between two approaches.
• You can run one at a time per task. Want one agent on the backend, another on the frontend? You open two terminals and babysit both.
• They don't coordinate. Finishing a task, running tests, filing a PR, posting in Slack — that's your job, again, by hand.
• They don't learn across sessions. Every run starts fresh.
• Every agent sees every tool. Once you've installed 6 MCPs, every agent — even one writing docs — pays for the system-prompt bloat and risks tripping over tool name collisions.

I tried solving this with the Anthropic SDK and a bash script. It didn't work. The CLI agents have rich TUIs — step-by-step reasoning, interactive confirmations, live progress — and wrapping the API throws all of that away.

So I built cliclaw instead.

What cliclaw is

cliclaw is a chat-driven meta-agent that runs your CLI coding agent for you — whichever one you've chosen.

You configure your tools of choice once via cliclaw config: Claude Code, Codex, etc. — anything with a tmux-friendly CLI. The orchestration mechanics don't care which tool sits behind them: the MainAgent operates against a generic agent contract — spawn, send, confirm, await — implemented per tool as a thin adapter (a couple hundred lines).

When you assign work, cliclaw spawns one or more instances of your configured tools in tmux panes. It reads those panes like a human reads a terminal — recognizing spinners, confirmation prompts, error messages, completion markers. It sends keystrokes back. When a pane goes idle, it evaluates the result and decides what to do next.

Enable more than one agent and the MainAgent routes by fit. It sees every adapter you've turned on and its strengths, then assigns each task to the agent best suited to it — Codex for gnarly single-point reasoning and deep debugging, Claude Code for broad multi-file edit→test→rerun loops — and hands the diff to the other one for an independent review pass. You don't pick the agent per task; you describe the work and let the loop choose, always within the toolset you turned on (it never reaches for one you didn't enable). Roles aren't hard-wired — either can implement, either can review.

That's the entire idea. Switching tools is a config change. Adding support for a new tool is one adapter file. The orchestration layer never changes.

A side benefit of this layered design: you and the MainAgent can talk in one language while the MainAgent talks to the coding agents in another. Chat with the MainAgent in Chinese; have it brief Claude Code or Codex in English (or vice versa). cliclaw injects per-locale instructions into the prompts crossing each boundary, so the language you read is independent of the language the agents reason in.

cliclaw is a loop, not a prompt box

There's a name for the shift happening to coding agents this year — loop engineering, structured by Google's Addy Osmani after Boris Cherny (who built Claude Code) and Peter Steinberger (OpenClaw) kept saying the same thing out loud:

"I don't prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops." — Boris Cherny, Acquired Unplugged, June 2026

"You shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents." — Peter Steinberger

The idea: stop hand-prompting the agent turn by turn. Stand up a system that prompts it for you, iterates until the goal is verifiably met, and only comes back when it genuinely needs you. The human moves from prompter to loop designer.

cliclaw's MainAgent is that general loop, pre-built. You talk to it in plain language; it writes the prompts to Claude Code / Codex, reads their panes, decides the next move, and keeps going until the success criteria are met. You don't write the loop in bash — cliclaw is the loop.

Osmani names six primitives a loop-engineering setup needs. cliclaw ships four of them outright and approximates the other two:

Two v3.0.0 pieces make the loop real:

• Auto-continue gate (/autocontinue). At every natural stopping point a gate model asks is the goal actually met, or is there a next round? — and either keeps the loop running or hands back to you, capped so it can't run away.
• A loop-shaped system prompt. The MainAgent prompt is written around a TDD loop where a failing test is a continue signal, not a stop, and independent work fans out to parallel sub-agents instead of blocking on one.

Honest about the edges: cliclaw gives you one general loop (the MainAgent) rather than asking you to script task-specific ones, and its parallel isolation is panes-and-working-dirs, not git worktrees. But the core bet — you converse with a loop that prompts the coding agents, instead of prompting them yourself — is exactly the transition Cherny is describing.

Demo

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

A real example

To be added.

How cliclaw fits in

This is the honest landscape. cliclaw is not the only thing in this space.

cliclaw is for you if: you already live inside a CLI coding agent, you want to run more than one instance at once, and you don't want to give up the rich TUI output by wrapping the agent in an API.

How it works

  ┌───────────────────────────────────────────────────────┐
  │  Web chat UI  ⇄  WebSocket  ⇄  MainAgent  ⇄  LLM      │
  └───────────────────────────────────────────────────────┘
                              │
                              ▼
                        tmux session
                     ┌────────┬────────┐
                     │ pane A │ pane B │   ← coding agents live here
                     │ Claude │ Codex  │     (Claude Code, Codex, …)
                     │ Code   │        │
                     └────────┴────────┘
                              │
                              ▼
                   ┌─────────────────────┐
                   │ State detector      │   ← reads pane output, classifies
                   │ idle / working /    │     as idle / working / waiting
                   │ waiting / error     │     using per-agent regex patterns
                   └─────────────────────┘

The four pieces worth talking about:

State detection via pane scraping. Each agent adapter declares four regex patterns — waiting-for-input, active-work, completion, error. The state detector polls the tmux pane at a modest rate, classifies what it sees, and emits events the MainAgent subscribes to. No API hooks. No SDK. The agent doesn't know cliclaw exists.

Adapter abstraction. Adding support for a new CLI agent is a thin adapter (a couple hundred lines): the four regex patterns, the launch command, the confirm/abort keystrokes. src/agents/adapter.ts is the contract.

Hybrid memory, two-tier. SQLite-backed store with two indexes — sqlite-vec for dense retrieval, FTS5 for BM25, configurable weighted combination. Five embedding providers including a local node-llama-cpp path (Qwen3-Embedding) for fully-offline operation. Memory lives in two layers that are indexed and searched together: a global store (your coding style, your tone, your team's people, things that don't change when you switch repos) and a per-project store (this codebase's conventions, its architecture decisions, its open todos). The same editing, search, and /tidy machinery applies to both. Markdown files are the source of truth; the DB is the index.

Skill system. Markdown files with frontmatter under skills/. A skill is loaded on demand via conditional activation — the MainAgent decides when a skill is relevant from its description, then reads the full instructions. Modeled after Claude's skills.

Per-agent capability scoping. Every sub-agent has its own MCP roster (per-agent skill scoping is on the way). Don't load every tool you've ever installed into every agent — give each one only what it needs. A backend agent gets the database MCP; a docs agent doesn't. The result: smaller system prompts, no tool-name collisions, and an LLM that isn't distracted by tools it'll never call. This is one of the harder problems to retrofit onto an existing agent stack — cliclaw's adapter abstraction made it cheap.

Code layout:

src/
├── core/          MainAgent, signal router, work queue, context manager,
│                  learning pipeline (prompt tracker + change tracker + summarizer)
├── agents/        Adapter interface + Claude Code / Codex implementations
├── tmux/          Bridge (shells out to tmux CLI), state detector
├── llm/           Provider-agnostic client (12 providers)
├── memory/        sqlite-vec + FTS5 hybrid search, embedder, chunker
├── skills/        Parser, registry, injector, filter
├── tui/           Dashboard + agent preview (custom diff renderer)
├── server/        Express + WebSocket + auth
└── persistence/   Agent & conversation stores (SQLite)

Install

Requires Node 20+ and tmux.

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

Install cliclaw:

npm install -g @happenmass/cliclaw

cliclaw          # run in foreground, prints URL
# → open http://localhost:3120

Or run as a daemon:

cliclaw start    # background
cliclaw stop
cliclaw restart

Logs: ~/.cliclaw/logs/server.log · Config: ~/.cliclaw/config.json · State: ~/.cliclaw/server-state.json.

Configure

Minimum config:

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

Or run cliclaw config for an interactive TUI. Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) are read as fallbacks.

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

Chat commands

Status & roadmap

Today (v3.0.0): works for me, daily, against Claude Code and Codex — now with cross-vendor execute-then-review (Claude implements, Codex reviews), an auto-continue loop, and a loop-shaped MainAgent prompt. Memory + skills + hybrid search shipped. TUI dashboard works. Not battle-tested against production team workflows yet.

Next: - [ ] Per-agent skill scoping (MCP scoping already shipped) - [ ] More agent adapters (aider, gemini-cli, open-interpreter) - [ ] Slack / Discord bridge (drive cliclaw from chat on your phone) - [ ] Multi-user mode (teams sharing a single cliclaw server) - [ ] Richer execution evidence (surface test results, diffs, PR links in chat) - [ ] Budget / rate-limit enforcement across agents

If you want something specific, open an issue — this is still a solo project and priorities are flexible.

FAQ

Does cliclaw 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