Direct mode · provider limits

Direct mode bypasses the Claude Code CLI and talks to the provider’s chat API straight from the kanade daemon. It’s the fast-chat path — no tools, no MCP, no skills, no hooks. Each provider has its own quirks; this page lists them in one place so you know what to expect before you flip a lane’s mode.

At a glance

Provider	Direct mode	Native images	Tools / MCP	Known issues
Anthropic (Claude)	yes	yes (base64 image parts)	no	OAuth tokens occasionally return HTTP 401/429 during alpha. Use an API key if you have one.
DeepSeek	yes	no	no	Image attachments are rejected with a clear unsupported-image error.
Gemini	yes	yes (inlineData parts)	no	Requires GOOGLE_API_KEY or GEMINI_API_KEY; not yet wired into the first-run wizard.
Codex	no	n/a	n/a	Direct mode is intentionally unsupported. Use agent mode (CLI only).

When the lane label says direct, every turn issues one HTTP call to the provider. Conversation history lives in SQLite on your machine and is sent back as the request body on every turn, so context survives daemon restarts.

Anthropic (Claude)

Direct mode uses the Messages API at https://api.anthropic.com/v1/messages.

• Auth resolution order: per-account CLAUDE_CONFIG_DIR → ~/.claude/.credentials.json → credentials.json → .claude.json → ANTHROPIC_AUTH_TOKEN → ANTHROPIC_API_KEY.
• OAuth bearer flow is supported but flaky during alpha: the maintainer’s v0.2.16 test pass reached the API and got back HTTP 401 from a freshly minted OAuth account. If you see persistent 401s with OAuth, fall back to an ANTHROPIC_API_KEY and reload accounts.
• Rate limits: 429s are surfaced verbatim. The verification harness retries 5 times with exponential backoff (1s/2s/4s/8s/16s); the runtime surfaces them once and lets you retry.
• Images: paste or drop an image into the input bar; the daemon attaches it as a base64-encoded image part. Large screenshots are downscaled client-side before upload.
• What’s lost vs agent mode: every tool, every MCP server, every skill, every hook, plan/accept-edits/bypass modes, --effort extended-thinking budget, /clear PTY semantics.

DeepSeek

Direct mode uses the OpenAI-compatible endpoint at https://api.deepseek.com/v1/chat/completions.

• Auth: DEEPSEEK_API_KEY, ANTHROPIC_AUTH_TOKEN, or ANTHROPIC_API_KEY (in that order).
• Images are not supported. Pasting an image into a DeepSeek direct lane produces a clear image input is not supported in DeepSeek direct mode error. Switch the lane to agent mode if you need vision — the agent path routes through Claude-Code-Router which may have different image support depending on your CCR config — or attach the image to a different lane.
• Models: the default model is read from the account model field; override via the request when calling /api/... directly.

Gemini

Direct mode streams from https://generativelanguage.googleapis.com/v1beta/models/<model>:streamGenerateContent.

• Auth: GOOGLE_API_KEY or GEMINI_API_KEY. The first-run wizard does not yet prompt for a Gemini key — set it in accounts.json manually or through the Settings → Accounts & Providers editor.
• Images: pasted images attach as inlineData parts. Same downscaling rules as the other lanes.
• Models: Gemini 2.5 Pro is the default for new direct lanes; override per-account.

Codex

Codex direct mode is not supported. The OpenAI Codex CLI emits NDJSON that the daemon translates into Claude-shaped stream-json so the chat-view can render it; there is no equivalent streaming HTTP API exposed by Codex that gives parity with that translation layer. Codex lanes must run in agent mode, which requires npm i -g @openai/codex and codex login on the host.

When to use direct vs agent

Use direct when…	Use agent when…
You want fast plain chat with no tools	You need file edits, shell commands, MCP servers, or skills
You’re rate-limited on the agent path and need a quick second opinion	You want --model + --effort proof from the CLI
You’re testing a provider that doesn’t have a CLI integration	You want hooks, plan/bypass modes, or --resume semantics

Direct mode is intentionally narrow. If you find yourself missing a feature in direct mode, switch the lane back to agent mode in Settings → Accounts & Providers — your conversation history is preserved.

Reporting a direct-mode bug

When reporting a direct-mode bug through the tracker or support channel configured for your build:

1. Include the provider (Anthropic / DeepSeek / Gemini) and the model id.
2. Include the exact error message Kanade rendered.
3. Copy diagnostic info from /settings (the bug-report copy button) — it redacts secrets but keeps the data-dir, channel, and structured warning ring contents the maintainer needs.
4. If the error mentions an HTTP status, include it — direct mode forwards the provider’s status code verbatim.