CLI Providers vs. API / Subscription Providers

TatsuCode treats two very different kinds of provider as first-class citizens. They look similar in the model picker, but they work differently under the hood — and that affects which features you can use them with. This page is the honest map.

Short answer: Use API / subscription providers when you want a regular conversational model — fast switching, parallel Task Agents, full feature support. Use CLI providers when you want to delegate a self-contained task to a vendor's own coding agent and get a structured archived report back. The two are complementary, not redundant.

What's an "API / subscription provider"?

These are providers TatsuCode talks to over HTTP, using your API key or OAuth token, then drives the conversation itself.

When you chat with one of these, TatsuCode is in charge of the loop. The model emits tool-call JSON; TatsuCode runs the tool in C# and feeds the result back. Stop conditions, tool whitelists, parallelism, cancellation — all controlled by TatsuCode.

What's a "CLI provider"?

A CLI provider is a vendor-built command-line agent that TatsuCode launches as a child process. The CLI brings its own model auth, its own tool set, and its own internal loop.

When you chat with one of these, the CLI is in charge of the loop. TatsuCode just hands it a prompt, watches its streaming output, and renders progress. The CLI decides which tools to call (its own native Read/Edit/Bash, plus the TatsuCode tools we expose to it via MCP) and when to stop.

Why the difference matters

These differences are why you'd choose one or the other for a given job — and they're also why some TatsuCode features are restricted to one or the other.

Feature support matrix

This is the part most people came here for.

Why CLI providers are not valid Task Agent assignees

It's a fair question — Claude Code is good at exploring code, so why can't you assign it as the Code Explorer Task Agent?

Three reasons, all structural:

1. The Task Agent's tool whitelist doesn't apply. Task Agents are configured with a specific list of TatsuCode-internal tools (e.g., ReadFile, ListDirectory, CodebaseReadOnly, Grep, SearchFiles, TerminalReadOnly, SaveNote for Code Explorer). When the assignee is a CLI provider, the CLI ignores that list — it has its own internal tools (Read, Bash, Grep, …) and uses whatever it wants. You'd think you got a read-only agent and might get something quite different.

1. The end-of-turn contract is different. Task Agents extract result.FinalOutput from the assistant's last message text. CLI providers in delegated mode put their structured deliverable in tatsu_report.full_content instead — Task Agent infrastructure doesn't read that, so the actual work product would be lost.

1. No archive is produced. CLI providers shine because every run is archived as a report.md that any other CLI provider can read (Cross-Agent Relay). Task Agent runs aren't archived, so you'd get the cost of running Claude Code without the durable artifact that makes it valuable in the first place.

If you want Claude Code (or any CLI provider) to do code exploration, ask your main chat model to delegate to it. Every main model has a ClaudeAgent tool available — you don't invoke it yourself, you request it in plain language:

"Use Claude Agent to explore the auth flow — find every place the auth middleware decides whether to issue a session token. We're investigating CVE-2026-0001, see /docs/incident.md. Then summarize the findings."

"Delegate this to Claude Code and continue from the prior exploration."

The main model packages the request, runs Claude Code in the background, and returns with a structured report.md you can hand to any other agent later. That's the relay.

"But I edited config.json by hand to assign Claude Code as a Task Agent…"

We catch that at three layers:

1. The picker hides CLI models — they don't appear in /models-taskagents at all.
2. The bridge rejects them — setTaskAgentModel returns an explicit error if the assignee resolves to a CLI provider.
3. The runtime ignores them — when a Task Agent runs, if its assigned model is CLI-backed, the override is silently dropped and the primary model is used instead.

Three independent gates so a stale config or a curious user doesn't accidentally produce a confusing partial result.

When to use each

Use an API / subscription provider when…

• You want a normal conversational model in /models.
• You want parallel agents on a single problem (3 Task Agents on a Unity bug at once).
• You want exact token/cost accounting per turn.
• You want TatsuCode's tool whitelist enforcement (e.g., truly read-only Code Explorer).
• You want the model to use the same chat history across many turns.

Use a CLI provider when…

• You want to delegate a self-contained task and get a structured deliverable back.
• You want to chain agents across vendors (Claude → Gemini → Local) on the same project, with each handoff producing a durable artifact.
• You want to use a subscription you already pay for (Claude Pro / Max / Team / Enterprise) without pasting tokens into TatsuCode.
• You want vendor-native tool use — Claude's own Read/Edit/Bash rather than TatsuCode's wrappers — for a specific job.

The two compose well: have GPT-5 (API) orchestrate, call ClaudeAgent (CLI) for a focused chunk, take the resulting report.md and feed it to a Gemini CLI run via continueFrom. You stay in charge; each agent does what it's best at.

Roadmap

These limitations are by design today, but a few are explicit roadmap items:

• Parallel CLI execution — multiple Claude Code (or mixed-vendor) runs at the same time, each archived to its own cli-providers/<runId>/.
• Task Agent CLI relay — making CLI providers valid Task Agent assignees by giving them a TaskAgent-flavored MCP profile, a TaskAgent bridge prompt, and an archive integration. This requires a new MCP profile, a new prompt, and a parallel execution branch in SubAgentService. Tracked separately because the whitelist mismatch (item 1 above) needs a thoughtful answer first.
• Additional CLI providers — Gemini CLI is the next planned entry. The schema, the manifest builder, and the stdin safety net are all already provider-neutral.

If something on this matrix isn't behaving as documented, that's a bug — please file it.