dex

A CLI multi-agent coding orchestrator

Plan with one model, code with another, review with a third — no more single model doing everything. dex doesn't replace Claude Code, Codex, or your local Ollama model — it wraps them in a pipeline where each role runs on whichever model actually fits it.

Why Dex · Features · Quick Start · Commands · Architecture · Config

dex decomposes a task with an orchestrator model, hands execution to a configurable executor (Claude Code, Codex, or a direct LLM backend), then runs a reviewer pass before surfacing the result — with checkpointing and session history so a bad run is never a lost run.

[!WARNING] Under active development. Expect rough edges and bugs. Found one? Open an issue — reports are welcome.

Why Dex?

Claude Code, Codex, and every other coding agent right now lock you into one model for everything — that same model plans, writes the code, and reviews its own work. With open models catching up fast, that's leaving capability and money on the table.

dex splits the job into three roles, each with its own {backend, model}:

• an orchestrator breaks the task into a concrete plan (and can explore the repo with read-only tools first)
• an executor does the actual work — writes code, edits files, runs commands
• a reviewer checks the diff against the task before calling it done, and can send it back for another pass

That means you can plan with a frontier model, execute on something fast and cheap (or fully local), and review with a different frontier model — one that owes nothing to the code it's checking, so it isn't just rubber-stamping its own output. Mix and match however your budget and trust level call for. Every run is checkpointed so /rewind can restore both history and files to any prior point.

Features

• Multiple backends — Anthropic, Groq, Llama.cpp, Ollama (local + cloud), OpenRouter, Ramp Router, or shell out to Claude Code/Codex CLIs — mix and match per role
• Three independent roles — orchestrator, executor, reviewer each get their own {backend, model}, switchable mid-session via /model
• Tool-using planner — the orchestrator can explore your repo (read-only list_files/read_file, MCP tools, skills) before committing to a plan, not just guess from a file tree
• Council mode — fan a plan out across multiple models in parallel, then have the orchestrator judge and merge the best candidate
• Smart routing — send trivial tasks to a cheaper/local model automatically, escalate back to the main executor on review failure
• MCP support — Model Context Protocol client & manager built in, shared across every agent (claude-code, codex, and the direct-LLM executor alike)
• Checkpointing — content-addressed (sha1) snapshots per task; /rewind restores both files and history together, distinct from git
• Session history — resume, rename, delete, or replay past sessions; /compact folds old history into a durable MEMORY.md
• Cloud supervision — have a cloud model supervise a local LLM writer step-by-step (/supervisor, /continue)
• Effort controls — tune how much planning detail (/orc-effort) and review scrutiny (/rev-effort) you pay for, per task
• Search primitives — grep and glob in both the planner and executor tool sets, plus paged, line-numbered read_file, so the model finds code instead of dumping the repo into its context
• .gitignore-aware project context — the file tree handed to the model honors .gitignore and an optional .dexignore (which can also re-include something .gitignore excluded), instead of a hardcoded ignore list
• @file mentions — type @ in the REPL to pull a file's content into the task, with a live autocomplete dropdown as you type
• Loop guard everywhere, not just the executor — the read-only planner/ask loops now detect a model stuck repeating the same tool call (e.g. the same grep fifteen times) instead of burning turns until they hit the cap
• Per-model tuning — context window, output cap, turn ceiling and tool-set size resolve from a model-id registry (config → registry → live probe → default), not from which backend the model happens to arrive over
• Permission modes — plan / default / acceptEdits / yolo, deny-first rule matching, and "always allow this pattern" learned per project into .dex/permissions.json
• Live streaming — watch the model generate, with a plan tree that shows turns, tokens and time per step, and a /timeline of every tool call
• Sub-agents — the executor can delegate a self-contained piece of work to a fresh agent with its own context and get back only the summary
• Scriptable — --output-format json|stream-json and -p/--print for CI and editor integrations

Quick Start

npm install -g run-dex

Or build from source:

git clone https://github.com/s-nish/dexcli.git
cd dex
npm install
npm run build
npm link          # makes the `dex` binary available globally

# Interactive setup — pick backends/models for each role
dex init

# One-shot task
dex run "fix the memory leak in the worker"

# Read-only: investigate and describe the change without touching anything
dex run "why is the worker leaking?" --permission-mode plan

# Machine-readable, for CI or another tool
dex run "fix the flaky test" --output-format json --yolo
dex run "fix the flaky test" --output-format stream-json   # one JSON object per line, live

# Just the answer, nothing else
dex run "summarise what changed in src/worker.ts" -p

# Interactive session
dex repl
# ...or just `dex` with no subcommand — same thing

Inside the REPL, type @ and start typing a path to pull a file's content into your task (autocompletes as you go), or / for the command palette below.

dex run exits 0 on a passing review, 1 on failure, and 2 on a malformed invocation.

Slash Commands

Available inside dex repl

Session & History

| Command | Description | |---------|-------------| | /resume | List past sessions for this dir + subdirs, pick one to continue | | /clear | Save the current session and start a fresh one | | /delete | List past sessions and delete by number (multiple allowed, e.g. 1 3 4) | | /session-name <name> | Rename current session (auto-named by LLM after first task) | | /rewind | Rewind history AND restore files to that point | | /compact | Fold old raw task history into MEMORY.md (executor model), then drop it from the log |

The Vibe Rail

| Command | Description | |---------|-------------| | /vibes on | Turn on the rotating feed line while the agent works | | /spotify play <name> | Play a track (macOS + Chrome) | | /spotify play album <name> | Play an album | | /spotify pause | Pause playback | | /spotify next | Skip to next track | | /spotify status | Check Spotify bridge status |

Smart Routing

| Command | Description | |---------|-------------| | /routing on | Route trivial tasks to a cheaper agent | | /shell on | Allow the llm agent to run shell commands (npm run build, grep, etc.) — read-only commands (cat, grep, ls, git status) are always auto-approved |

Permissions & Visibility

| Command | Description | |---------|-------------| | /permissions | Show the current mode and every allow/deny rule in force | | /permissions plan\|default\|acceptEdits\|yolo | Change what runs without asking. plan withholds the write tools entirely; deny rules beat every mode, yolo included | | /permissions allow <rule> | e.g. /permissions allow run_command(npm test:*) — saved to .dex/permissions.json, project-local | | /permissions deny <rule> | e.g. /permissions deny edit_file(migrations/**) | | /permissions reset | Drop every learned rule, keep the shipped defaults | | /timeline | The last run's tool calls: timings, result sizes, and which ones the harness had to salvage | | /verbose on | Stream the model's thinking tokens inline (the count is always reported either way) |

Agent & Orchestrator Control

| Command | Description | |---------|-------------| | /model agent claude-code\|codex\|llm | Switch executor agent mid-session | | /model orchestrator <backend> <model> | Change orchestrator model | | /model executor <backend> <model> | Change executor model | | /model reviewer <backend> <model> | Change reviewer model | | /agents on | Enable parallel worker agents | | /agents off | Disable — tasks run through one executor |

Effort & Thoroughness

| Command | Description | |---------|-------------| | /orc-effort normal\|high\|xhigh | How detailed the orchestrator's plan/executor brief is | | /rev-effort normal\|high\|xhigh | How thorough the reviewer is (full-file context at high, adversarial pass at xhigh) | | /effort none\|low\|medium\|high\|max\|default | Ollama agent thinking effort |

The Reviewer

| Command | Description | |---------|-------------| | /reviewer on | Enable the reviewer pass (default) | | /reviewer off | Skip reviewer — accept executor output as final |

Cloud Supervision

| Command | Description | |---------|-------------| | /supervisor on | Cloud-supervise the local llm writer | | /supervisor off | Disable cloud supervision | | /continue | Resume the saved cloud-supervised task |

Memory & Context

| Command | Description | |---------|-------------| | /memory on | Enable durable project facts in MEMORY.md (default) | | /memory off | Disable MEMORY.md reading/auto-update | | /memory show | Display current MEMORY.md | | /memory edit | Edit MEMORY.md directly |

The Council (Multi-Model Planning)

| Command | Description | |---------|-------------| | /council add <backend> <model> | Add a council member, e.g. /council add anthropic claude-opus-5 | | /council remove <n> | Remove member by number | | /council list | Show configured members | | /council on | Turn council mode on (needs 2+ members) | | /council off | Turn council mode off | | /council help | Full council documentation |

MCP & Skills

| Command | Description | |---------|-------------| | /mcp list | List configured MCP servers | | /mcp add <name> -- <command> | Add stdio MCP server | | /mcp add <name> --url <url> | Add HTTP MCP server | | /mcp remove <name> | Remove MCP server | | /skills on | Enable project skills for codex/llm | | /skills off | Disable skills injection |

Recipes (Reusable Task Templates)

| Command | Description | |---------|-------------| | /recipe save <name> | Save last completed task as a recipe | | /recipe apply <name> [extra] | Apply a recipe with optional extra instructions | | /recipe list | List all recipes | | /recipe show <name> | Show recipe details |

Meta

| Command | Description | |---------|-------------| | /help | This message | | /exit or /quit | Close dex |

Mode Cycling

Press Shift+Tab to cycle between modes: ask → plan → agent → snap

• snap = no orchestrator plan, no reviewer — raw prompt straight to the executor for small one-off fixes

Architecture

The Agent Pipeline

dex runs a multi-agent pipeline:

User Input → Orchestrator → Plan → Executor → Reviewer → ✓ Done
                   │
                   ▼
           (optional) Council Mode
      Multiple models decompose & merge plans

• Orchestrator — breaks down your task into steps, decides approach
• Executor — the worker; writes code, runs commands
• Reviewer — second set of eyes; validates output before acceptance
• Council — fans planning out to multiple models, then merges results (requires 2+ members)

Executor Agents

| Agent | Backend | Description | |-------|---------|-------------| | claude-code | CLI | Native Claude Code with full tool access | | codex | CLI | OpenAI Codex CLI | | llm | API/Local | Direct to Anthropic/Groq/Ollama/etc. |

The llm agent is the flexible one — it can use any backend. claude-code and codex bring their own native capabilities.

Extras

• Chrome Bridge — terminal-to-browser bridge used by the Spotify integration
• Spotify Integration — control playback from the CLI (macOS + Chrome)
• Vibes Rail — rotating HackerNews/RSS feed line while the agent works, purely cosmetic

Backend Options

| Backend | Type | Notes | |---------|------|-------| | anthropic | Cloud | Claude models, native tool-calling | | groq | Cloud | Fast inference, OpenAI-compatible API | | ollama | Local | localhost:11434, auto-tiers turn/stall caps by model param size | | ollama-cloud | Cloud | Ollama's hosted API | | llama-cpp | Local | GGUF models via a local /v1-compatible server | | openrouter | Gateway | Access multiple providers through one API | | ramp-router | Gateway | Ramp Router — one key routed across providers, spoken via the OpenAI Responses API | | claude-code / codex | CLI | Shell out to your own CLI subscription; usable as orchestrator/reviewer too, not just executor |

Config

dex stores config at ~/.dex/config.json (mode 0600), managed via dex init or dex config .... Each role (orchestrator, executor, reviewer) gets its own {backend, model} pair, and a top-level agent picks the executor implementation (claude-code, codex, or llm):

{
  "agent": "claude-code",
  "orchestrator": { "backend": "anthropic", "model": "claude-sonnet-5" },
  "executor": { "backend": "claude-code", "model": "default" },
  "reviewer": { "backend": "anthropic", "model": "claude-sonnet-5" },
  "vibes": {
    "enabled": true,
    "sources": [
      { "type": "hn" },
      { "type": "rss", "name": "DevOps", "url": "https://devops.com/feed" }
    ]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

Contributing

Contributions welcome:

• Bug reports and fixes
• New backend support
• Documentation improvements

License

MIT — see LICENSE.

⬆ Back to top