Browse documentation

Technical documentation / Reference

Claude subscription

Use an installed Claude Code CLI for claude.ai access while magi-code manages tools, approvals, history, and compaction.

Setup: Provider authentication.

Runtime ownership

OwnerResponsibility
Installed Claude CLISubscription login, refresh, model access and authenticated Messages requests
Rust providerProjection, native process, deadlines, cancellation, ordered events and tool validation
One-admission relayForward one generation to Anthropic, replace placeholder with ordered host history, validate response
Host agent runnerDurable history, approvals, tools, continuation and compaction

Each request launches installed claude -p with one ordinary placeholder prompt. The relay replaces its messages with the complete host conversation. There is no SDK dependency, manual assistant-input protocol, mirrored Claude session, or second credential-refresh owner. Temporary system prompt, settings and inert tool inventory live in an owner-private directory. Native session persistence is disabled.

Built-in CLI tools and skills are disabled. User/project/local settings are disabled; managed policy still applies. Strict MCP configuration exposes only the inert host inventory. Magi-code replaces the system prompt and disables native compaction. The CLI and inert MCP server share a process group, terminated on completion, failure or cancellation.

The subscription guidance permits CLI, SDK and third-party usage against subscription limits. It does not specifically certify this history-rewriting relay. API-key and alternate-backend environment overrides are removed from children, but existing subscription usage credits may still be charged. Magi-code never enables credits or changes billing settings.

Readiness accepts signed-in CLI status for either claude.ai or oauth_token. The probe and request share the same subscription-only environment and preserve CLAUDE_CODE_OAUTH_TOKEN; the CLI chooses that token before a stored login. Magi-code does not inspect, log, or store the variable's value. Both methods use the same relay. The relay reads quota from upstream anthropic-ratelimit-unified-5h-* and -7d-* response headers and keeps only the latest values in memory. Setup-token logins have no account metadata for a direct quota lookup, so they show quota only after the first request completes. Magi-code does not substitute a stored account's usage, and an account switch discards quota relayed before the switch.

Execution and failure policy

CLAUDE_CODE_MAX_RETRIES=0 and CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 constrain native retries. They are not enforcement: the relay refuses every Messages request after the first admission. Unexpected history replacement fails before upstream I/O. Both native and restored requests are capped at 8 MiB; captured response at 16 MiB.

The relay retries transport failures before response headers up to twice, waiting one then two seconds. It reuses the same admitted request and host history; no synthetic “Continue” message or native CLI restart is needed. Native retry multiplication is disabled. HTTP rejections, refusals, response-body failures and local forwarding failures are not retried. Cancellation and existing generation deadlines cover attempts and backoff without resetting. A lost response does not prove Anthropic never processed the request; retries may consume subscription usage.

Relay diagnostics include upstream attempt count, typed timeout/DNS/connection/request/body/decode flags and, when available, I/O kind and OS error code. Raw transport source messages remain excluded because they can contain credentials or proxy URLs.

The CLI is launched with --thinking-display summarized to request provider-generated thinking summaries. They use the same live reasoning display and saved-history path as other providers. Provider-record signatures and opaque redacted thinking payloads are stored unchanged and never displayed; ordinary text still undergoes secret redaction. Request projection omits unsigned, malformed or redaction-damaged thinking blocks without changing stored history, assistant text or tool calls/results. Empty or provider-hidden thinking produces no reasoning card.

Text, reasoning and usage may stream before completion. Tools and the remaining ordered suffix require:

A completed tool-use response may end the one-turn CLI with error_max_turns and exit 1. Only that exact subtype with a validated upstream tool call permits exit 1. Other errors, missing terminal records and incomplete streams fail without releasing tools. Accepted partial text remains durable. A later host continuation is a new request, not a retry within the same admission.

An upstream refusal fails the turn without releasing tools. The error identifies Anthropic as the source, includes its refusal category and explanation when supplied, and takes precedence over the CLI's subsequent retry errors. Missing explanations are reported explicitly. Category and explanation are redacted, stripped of terminal controls, normalized to one line, and capped at 128 and 1,024 characters respectively. Magi-code does not retry refusals or change models automatically; the relay still blocks every additional request.

Native lines are capped at 1 MiB and cross a bounded 16-message channel. Startup allows five minutes; configured semantic inactivity applies after progress. Upstream completion starts one fixed finalization grace interval. Each generation has a 30-minute overall limit. Diagnostics exclude raw prompts, authorization headers and native stderr.

Context capacity

Explicit model selectionInput ceiling
Opus 4.6 and newer with [1m], including claude-opus-5-5[1m]1,000,000
Fable 5 and newer with [1m], including claude-fable-5-2[1m]1,000,000
Sonnet 5.5 and newer and Haiku 5.5 and newer with [1m], including claude-sonnet-5-5[1m] and claude-haiku-5-5[1m]1,000,000
All other selections, including aliases202,000

The subscription catalog surfaces eligible one-million-token [1m] variants, plus standard-context claude-sonnet-5 and claude-haiku-4-5. Explicit selections without the suffix retain the conservative ceiling above; existing selections are not rewritten. Compaction uses the same settings, context reserve, model inheritance and prompt-border display as every other provider. Defaults are an 80% automatic trigger and four compactions per run; no separate Claude controls or required alternative model. Catalog windows and native modelUsage cannot raise transport limits.

Candidates come from models.dev. claude-fable-5-2[1m], claude-sonnet-5-5[1m], claude-haiku-5-5[1m], claude-sonnet-5 and claude-haiku-4-5 are always listed, even when models.dev omits them. Enable a model in Settings → Choose models → Available models, then select it in /model. Candidate listing does not guarantee subscription access. The Anthropic API catalog uses the authenticated Models API and includes Fable 5.2 when returned by that API; published limits, effort levels and API pricing supplement missing models.dev metadata.

The explicit suffix matters when ANTHROPIC_BASE_URL points at a relay: native gateway defaults can differ from direct subscription defaults. See Claude model configuration. Account entitlements still decide acceptance. Estimates are not provider token counts; token-dense input can exceed them substantially. Keep headroom. Oversize rejection uses host compaction, not a hidden model or billing fallback.

Verification limits

The input ceilings above are enforced limits, not promises that every CLI version, account, or model accepts a full window. Native observations include successful large-history replay, tool calls, cancellation, and recovery, alongside rate-limit and retry failures.

See the archived observations for versions, measured token counts, failures, and the direct-CLI/SDK comparison. Those observations do not establish current billing or model access.

Edit this page on GitHub ↗