Duo-Coding: Mentor + Primary Pairing
Pair two coding agents on one task — a Primary that writes and a read-only Mentor that reviews every turn, runs the build and tests, and directs repairs — with a cheap analyst driving a live dashboard.
Overview
Duo-Coding pairs two coding agents on a single task. A Primary agent does the writing while a read-only Mentor ("Duo") reviews every turn, independently runs the build and tests, and — when it disagrees — directs a repair into the Primary's chat instead of editing files itself. A separate Analyst (a cheap API LLM, not a coding agent) turns the run's event log into a live dashboard. The aim: get more done, with fewer errors, faster.
| Role | Type | What it does |
|---|---|---|
| Primary | Coding agent | The sole writer — does the actual work. |
| Mentor ("Duo") | Coding agent (read-only) | Reviews every turn, independently runs the build and tests, and directs repairs into the Primary's chat rather than editing files itself. |
| Analyst | Cheap API LLM (not a coding agent) | Turns the run's event log into a live dashboard. |
How to Open Duo-Coding
Duo-Coding is on by default. You can turn it off in Settings → Duo-Coding, which also hides the entry points below.
- Title bar — the Duo-Coding button (two-people / Users icon). Hidden when the feature is disabled in Settings.
- Keyboard —
Cmd/Ctrl+Shift+Dtoggles the Duo-Coding workspace for the active project. - Idle workspace — from the workspace's idle state, Configure a Duo run opens the setup modal.
Starting a Run
Choose the agents
In the setup modal, pick the Primary and Mentor agents — Claude Code, Codex, or OpenCode. Uninstalled agents show disabled.
Pick model and effort
Choose a model and effort for each agent from the live dropdowns. These picks are applied when the sessions spawn.
Describe the task
Write the task for the pair to work on.
Start
Click Start run. The Primary begins, and the Mentor reviews after each of its turns.
The Mentor is locked read-only automatically, using each agent's own mechanism:
| Agent | Read-only enforcement |
|---|---|
| Claude Code | Plan mode |
| Codex | Read-only sandbox |
| OpenCode | Native plan mode (disallows all edit tools) |
If an OpenCode build doesn't offer a plan mode, the run refuses to start rather than running a writable mentor.
The Duo-Coding Workspace
Duo-Coding runs in an embedded workspace that takes over the center area — it is not a floating overlay. It has three parts:
- Header / run controls (always available while active) — the run status, current phase, the agent pairing (primary → mentor with models), a live elapsed timer, and Pause/Resume plus a two-step Stop (click Stop, then Confirm stop?). Stopping tears down both agent sessions and writes a Duo-Coding entry to the project changelog.
- Left area — two tabs:
- Agents — the two live agent chats side by side: the Primary (interactive) and the read-only Mentor, so you can watch both work in real time.
- Dashboard — the analyst view: an assessment headline, narrative, momentum, and confidence score; collaboration-health and code-quality gauges (0–100, color-banded); metrics (reviews, agreements, disagreements, repairs, dialogue rounds, drift incidents, agreement rate, and a per-role cost breakdown — the mentor's real reported $, the primary's estimated $ + tokens, and the analyst $); charts (changes per turn, agreements vs disagreements); and risks, recommendations, repair analysis, improvements, and watch items.
- Orchestrator card (right, behind a resizable divider) — the Mentor's running log of verdicts, decisions, and outcomes: the live dialogue between the two agents.
A right-aligned Close Duo button in the center tab bar returns to the normal Chat view at any time. If a run is still active it keeps running in the background and the Duo tab stays reachable — Close Duo only dismisses the view. To end the run itself, use Stop in the header.
Plan Gate & Live Co-Review
Beyond reviewing each completed turn, the Mentor can engage the Primary at two extra points. Both are on by default and toggled in Settings → Duo-Coding:
- Plan-review gate — before the Primary writes any code, the Mentor reviews and approves the proposed approach. This catches a wrong direction early, before effort is spent building it out.
- Live co-review — while the Primary works, the Mentor reviews changes continuously at checkpoints, not only after a full turn finishes, so drift is caught sooner.
Live co-review's cadence trades review coverage against cost, and applies only while live co-review is on:
| Cadence | Trade-off |
|---|---|
| minimal | Fewer reviews, cheaper. |
| balanced | Middle ground. |
| thorough | More reviews, costlier. |
Disagreements & Tie-Breaks
A blocking objection opens a bounded dialogue: the Mentor raises a concern, the Primary defends or fixes, and the Mentor re-judges. If they can't converge within the configured rounds — or the same concern keeps repeating — the tie-break policy applies. Configure it in Settings → Duo-Coding:
| Policy | Behavior |
|---|---|
| Pause (default) | The run pauses for you to decide. A modal shows both positions; you can let the Mentor win, let the Primary proceed, or stop. |
| Mentor wins | The Mentor's position is applied. |
| Primary proceeds | The Primary continues. |
Drift & Budget
- Drift watcher — a mid-run watcher flags severe drift (for example
rm -rf, deleting tests, or mass edits at higher sensitivities) and nudges the Primary back on track. - Budget cap — a per-run cap (USD or output tokens) pauses the run before it overspends.
Both are configured in Settings → Duo-Coding, along with the Analyst provider and model.
After a Restart
If the app exits mid-run, the Primary and Mentor sessions are gone, so the run can't resume live.
On the next launch, an interrupted run is reconciled and shown read-only — its history, metrics, and last analyst assessment are preserved — with a banner explaining it was interrupted. Start a new run to continue the work.
Tips
- Pair a cheaper Primary with a stronger Mentor to balance cost and quality.
- Keep the Analyst on a fast, cheap model — it summarizes, it doesn't code.
- Use a budget cap on long or exploratory tasks — two agents plus the analyst cost more than one.
- If the run pauses on a tie-break, read both positions before choosing. The Mentor runs the tests itself, so its verdict is evidence-based.
Related Articles
- Choosing Your Agent — Pick the right Primary and Mentor for the job
- Per-Task Agent Routing — How CodeMantis routes different agents to different work
- Multi-AI Assistants — Run Claude Code, Codex, and OpenCode in one app
- Session Modes Explained — Plan mode, which locks the Mentor read-only
- Self-Drive: Autonomous Implementation — CodeMantis's other orchestrated, hands-off run mode
- Settings Reference — Every Duo-Coding option in one place
Self-Drive: Autonomous Implementation
Let Self-Drive automatically implement your entire Implementation Guide — sending prompts, verifying output, fixing errors, and advancing through sessions without manual intervention.
Recall: Project & Cross-Project Memory
An opt-in memory layer that composes a focused brief from your project's Markdown vault before each prompt and harvests one memory note per commit — so decisions, gotchas, and conventions persist across sessions instead of being re-explained every time.