Per-Task Agent Routing

The Agents tab in Settings (new in v1.3.0, expanded in v1.5.0) is where you see which coding-agent CLIs CodeMantis has detected and choose which one new sessions use by default. From v1.5.0 onward you can also route specific task categories — main chat, the Assistant panel, SpecWriter, Help — to different agents independently, splitting your workload (and your subscription pool) across Claude Code and Codex.

Where It Lives

Open Settings › Agents (gear icon in the title bar, or press Cmd ,, then click the Agents tab).

What You See

Per-agent status rows

One row per supported agent. Each row shows:

• An install badge — green "Installed (vX.X.X)" or red "Not installed" with the install command.
• An authentication badge — green "Logged in" or yellow "Sign-in required" with the sign-in command.
• A "Make default" button — promotes that agent to the primary selectedAgentId for new sessions.

Per-task Defaults (v1.5.0)

Shown only when both CLIs are installed and signed in. A small table mapping task categories to agents:

Each row is a dropdown. Pick a specific agent, or leave it on "Use primary" to inherit whichever agent you've made the default. The setting is persisted as a sparse map (defaultAgentByTask in settings) — categories you don't touch stay on "Use primary."

Self-Drive is not a task category. Self-Drive always inherits the agent of the session it attaches to. If your main_chat is routed to Codex, Self-Drive runs on Codex too. The pre-run gate (Preflight) and orchestrator preamble still apply, but the agent is fixed by the underlying session. This is deliberate — Self-Drive's evidence vocabulary is calibrated per agent.

Usage split (last 7 days)

An AgentCostBreakdown card at the bottom of the tab shows, for the last 7 days:

• Per-agent token counts (input, output, cache read, cache write).
• An estimated-cost breakdown.
• A horizontal bar chart showing the Claude / Codex split.

Use this to see where your subscription pool actually goes and rebalance routing if either pool drains faster than expected.

User Actions

Route a task to a specific agent

In the Per-task Defaults table, change the dropdown for main_chat, assistant, spec_writer, or help to a specific agent. The change is persisted to defaultAgentByTask in settings.

Reset task routing

Change a dropdown back to "Use primary" to clear that category's entry from the map. The task will then follow whatever you've set as the default agent.

Change the default (primary) agent

Click "Make default" on the agent row you want as primary. This updates selectedAgentId in settings. Any task category set to "Use primary" will follow the new default immediately.

States

• Both installed: Both rows show green install + auth badges. Per-task Defaults table is visible.
• One installed: The other row shows "Not installed" with its install command. The Per-task Defaults table is hidden (it only makes sense when there is more than one agent to choose).
• One installed but signed out: Install badge is green but auth badge is yellow with the sign-in command. Sessions on that agent will fail at spawn time until you sign in.
• Neither installed: Both rows show "Not installed". Sessions cannot start at all (the Welcome Screen handles install guidance).

Configuration

• Settings path: Settings › Agents › Default agent → selectedAgentId
• Settings path: Settings › Agents › Per-task Defaults → defaultAgentByTask (sparse map)
• Internal: Detection IPC calls are checkClaudeStatus() and checkCodexStatus(). Both return { installed, version, parsed_version, authenticated }.

Why Route Per Task?

A common configuration: write specs with Claude (long-form reasoning), run hot main chat on Codex (cheaper subscription headroom), leave Help and Assistant on "Use primary." See Choosing Your Coding Agent for the decision framework and the blog post Why CodeMantis Now Supports Two Coding Agents (and Soon More) for the reasoning behind the design.