Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Changelog

4.0.0

ccode now supports per-slot model routing in dynamic mode. Instead of every tier (Opus, Sonnet, Haiku) collapsing to a single model, each tier can use a different model - the same way Claude Code works on a subscription.

  • New models: config block, the recommended way to configure models under a profile. Each slot (model, opus, sonnet, haiku, subagent) can set its own model ID, display name, description, and supported capabilities. For example, a DeepSeek profile can route Opus-tier requests to DeepSeek V4 Pro and Haiku-tier requests to DeepSeek V4 Flash, while a ZhipuAI profile routes Opus to GLM-5.1 and Haiku to GLM-4.5 Air. The old flat fields (anthropic_model, etc.) keep working, so existing profiles need no changes.
  • Per-slot display metadata: the name, description, and capabilities you set for each slot now show up in Claude Code’s /model picker. A plain (non-dynamic) profile shows its provider’s own names; a dynamic session shows generic labels (“ccode-Opus”, “ccode-Sonnet”, “ccode-Haiku”) instead, since its backend can be swapped mid-session. Remote Control sessions keep working as before.
  • New capabilities block per slot to tell Claude Code which features a provider supports (effort levels, thinking, interleaved thinking, and so on). Each is a simple on/off toggle, with provider-appropriate defaults shown in the config examples.
  • Provider examples and configuration docs now lead with the models: block, and the Config Reference has a new per-slot model routing section.
  • Newer Claude Code environment variables (claude_code_enable_auto_mode, claude_code_sync_skills_install_timeout_ms, otel_metrics_include_resource_attributes) can now be set as profile fields, and recent Claude Code subcommand flags pass through cleanly.

3.1.0

The dynamic proxy can now start on and switch to or from your Claude subscription, not only third-party providers.

  • ccode --dynamic works whatever profile you start from. Start on a third-party provider as before, or start on your Claude subscription (with an active claude /login) and the session forwards your login to Anthropic directly.
  • A running dynamic session can be switched to your Claude subscription and back to a third-party provider at any time with ccode sessions <id> set-profile <name> (or from the ccode sessions tui view), without restarting Claude Code.
  • Updated the Dynamic proxy page to cover starting on and switching to or from the subscription.

3.0.0

ccode can now run a dynamic proxy: one launch that serves several provider profiles and lets you switch which backend Claude Code talks to at runtime, without restarting it or dropping a Remote Control session. Everything from 2.x keeps working unchanged - this release only adds the dynamic proxy on top.

  • New --dynamic launch mode (and an always_dynamic config flag). It starts the local proxy and pins Claude Code to a stable virtual model name, so ccode can repoint the session at a different provider on the fly while Claude Code keeps running. The starting profile needs a base URL, a credential, and a model.
  • New ccode sessions command to see and steer running sessions. ccode sessions lists them; ccode sessions <id> set-profile <name> switches one to another configured profile; ccode sessions <id> kill stops one. Use all in place of an id to act on every session at once (all kill asks to confirm, or pass --yes). <id> is the session’s process id or a unique prefix of it. In-flight requests finish on the old provider and new requests use the new one.
  • New ccode sessions tui interactive terminal view: it lists running sessions and lets you switch a session’s profile, kill one, or kill all without retyping session ids. Exit with q or Ctrl+C. The plain ccode sessions subcommands above still work for scripting.
  • New optional proxy.model_map config to rewrite model names per request (inbound name to upstream name), at the top level or per profile.
  • New website page: Dynamic proxy. The Local proxy, FAQ, and Config Reference pages point at it.
  • Track recent Claude Code additions as first-class profile fields: skills syncing (claude_code_sync_skills, claude_code_sync_skills_wait_timeout_ms), claude_code_disable_workflows, claude_code_propagate_traceparent, and otel_metrics_include_entrypoint; plus the exec and prompt-suggestions subcommands as reserved names so a profile by either name won’t shadow them. See the Config Reference for the full list.

2.0.0

ccode now ships an in-process Local proxy that sits between Claude Code and your third-party provider. Profiles that worked in 1.x keep working identically.

  • New Local proxy mode that restores claude remote-control for third-party provider profiles on Claude Code 2.1.139+. ccode binds a small HTTP server on 127.0.0.1, points ANTHROPIC_BASE_URL at it, and forwards Anthropic-shaped requests to your real upstream (DeepSeek, OpenRouter, in-house gateway, local Ollama, etc.). Credential env vars are pulled out of Claude Code’s environment so the new auth check passes, and inbound credential and identity headers are stripped before forwarding. The proxy holds the upstream credential in memory and attaches it to outbound requests itself. See the Local proxy page for the full shape.
  • Auto-enables whenever --control (or always_control: true) is in effect for a third-party provider profile. Most users don’t need to touch the config; you’ll see a log line explaining what happened. Subscription passthrough and cloud-provider profiles (Bedrock, Vertex, Foundry) stay untouched.
  • New proxy: config block at the top level and per-profile. The simplest opt-in is proxy: { enabled: true }; the full set (enabled, bind, port, pid_file, allow_external_bind) is documented on the Local proxy page and the Config Reference.
  • New ccode proxy [--profile <name>] subcommand that starts only the local proxy and blocks until Ctrl+C, with no Claude Code launch. Useful for pointing multiple claude invocations (or any other Anthropic-compatible tool) at the same upstream.
  • Subscription passthrough with --control now works cleanly when CLAUDE_CODE_OAUTH_TOKEN is in your shell (e.g. after claude /login); the proxy auto-enable rule now also requires a non-Anthropic anthropic_base_url.
  • New website page: Local proxy. The Introduction, Usage, and FAQ pages now point at it as the fix for Remote Control on 2.1.139+.
  • Track two more Claude Code reserved names (daemon subcommand, --cwd flag) and a fresh batch of upstream env vars as first-class profile fields (notably claude_code_powershell_respect_execution_policy, claude_code_plugin_prefer_https, and the standard force_color / no_color). The retired claude_code_enable_opus_4_7_fast_mode is tracked in the Deprecated section so existing configs that mention it still parse. See the Config Reference for the full list.

1.5.0

  • New first-party cloud provider: Claude Platform on AWS, Anthropic’s first-party platform deployed on AWS (distinct from Amazon Bedrock). Six new first-class profile fields wired through: claude_code_use_anthropic_aws (the toggle), anthropic_aws_workspace_id (required on every request), anthropic_aws_api_key (workspace API key from the AWS Console, sent as x-api-key), anthropic_aws_base_url (optional endpoint override), and claude_code_skip_anthropic_aws_auth (for gateways that sign requests themselves). The toggle is treated as a cloud-provider profile by auth validation, so it skips the auth-token check (AWS SigV4 is supported as a fallback when no API key is set). anthropic_aws_api_key joins the secret-fields list, so the split-config prompt fires for it when importing into a project config.
  • New hosted profile example: anthropic-aws.yaml. Prompts for the workspace ID and the workspace API key - press ENTER at the API key prompt to leave it unset and fall back to AWS SigV4 (IAM credentials). Matching uncommented section on the Providers page (placed right below Bedrock), a row on the Importing configuration hosted-examples table, and a commented-out block in the full ccode init-config default config.
  • Track one more upstream Claude Code env var as a first-class profile field: claude_code_max_turns (caps agentic turns when no explicit --max-turns flag is passed; Claude Code rejects a value that’s not a positive integer at startup).

1.4.2

  • New hosted profile example: openrouter-model.yaml (“OpenRouter (custom model)”). Same OpenRouter base URL as the existing openrouter.yaml, but the auth token and every model slot (anthropic_model, the three default model fields, and claude_code_subagent_model) are part of the prompt: list - so you can pick your own slugs for non-Anthropic models (Llama, Mistral, GPT, Gemini, DeepSeek, etc.) at import time without editing YAML afterwards. ENTER skips any slot. Slots into the docs above the existing openrouter-preset.yaml (“OpenRouter (custom preset)”) variant. The existing openrouter.yaml (Claude defaults) and openrouter-preset.yaml (preset slug workflow) are unchanged.
  • All hosted profile examples, the default config templates (init-config and init-config --minimal), and every YAML example across the README, Providers, Configuration, and Importing configuration pages now use double-quoted string values consistently (anthropic_auth_token: "YOUR_KEY_HERE" instead of anthropic_auth_token: YOUR_KEY_HERE). Booleans stay unquoted. Defensive against pasted values that happen to contain YAML-reserved characters - cuts down the surface area for “my key starts with @ and now nothing works” kinds of bugs.
  • The Providers page is rewritten so each provider section shows the corresponding hosted YAML file 1:1 (header comments included), with the only deviation being that the API key/token field is uncommented with a YOUR_KEY_HERE placeholder and the prompt: block is dropped. Easier to skim the field set, single source of truth between the page and the hosted file. The “OpenRouter (custom model)” variant is documented on the Importing configuration hosted-examples table only, since its body is mostly a prompt: list and doesn’t fit the page format.
  • Side notes on the Providers, Introduction, Configuration, and Usage pages, plus the bundled README, now use a consistent > Note: blockquote format (no bolded “Tip:”/“New:” inline labels).
  • Track six new Claude Code subcommands (attach, bg, kill, logs, respawn, rm, stop) as reserved names, so a profile called e.g. kill won’t try to claim a --kill shortcut that would collide with Claude Code itself. Also added the claude_code_disable_agent_view profile field (and matching CLAUDE_CODE_DISABLE_AGENT_VIEW env var) to track an upstream Claude Code addition.

1.4.1

A small follow-up to 1.4.0 with quality-of-life improvements to the profile-management commands.

  • On Linux and macOS, configs that ccode writes (init-config, add-profile, remove-profile, set-default-profile) now use mode 0600 so saved credentials aren’t readable by other users on the same machine. No-op on Windows, where access is controlled by ACLs instead.
  • Stricter URL handling on ccode add-profile --from-url: the scheme check is case-insensitive (HTTPS:// is accepted just like https://), and redirects are constrained to http(s) with no transport-security downgrade.
  • More robust split-key flow: when you choose to save the API key to your user config, ccode writes the user config first so a problem there can’t affect the project file.
  • Cleaner error messages on failed URL fetches.
  • app/README.md now documents --value and --no-prompts with examples for unattended and CI use.
  • Expanded internal test coverage.

1.4.0

  • The hosted profile examples on Importing configuration now cover every provider documented in the default config (15 files instead of 8). New additions: Amazon Bedrock, Bedrock Mantle, Google Vertex AI, Microsoft Foundry (Azure), OpenRouter custom-preset variant, Local/self-hosted, and an Organization gateway template. Each file follows the rule “prompt only for fields that are required AND have no sensible default” - so Bedrock/Mantle have no prompts at all (AWS creds handle auth), Vertex prompts for the GCP project ID, Foundry prompts for both the resource URL and API key, the gateway template prompts for both the URL and the auth token, and the rest prompt for just the auth token. The OpenRouter preset and Local examples leave the slug/model name as a placeholder you edit after import (since the same value is repeated across five model slots, prompting once-per-field would be redundant - both files explain this in the leading comment).
  • The hosted YAMLs now include a commented-out body line for every prompted field with a hint explaining where the value comes from (# the API key is part of the prompt field below, user will fill this out when pulling). Reads as a near-mirror of the corresponding default_config profile, so the field set is visible to anyone browsing the file on the website, not just at the moment of import.
  • The Providers page is rewritten to mirror default_config.yaml field-for-field across every provider section (no more trimmed Kimi/Qwen/MiniMax bodies), with a ccode add-profile --from-url ... snippet under each provider that has a hosted file. DeepSeek Flash, the OpenRouter custom-preset workflow, and the organization gateway pattern get their own dedicated subsections instead of being mentioned in passing. The China-endpoint variants for Z.AI and Moonshot Kimi are documented inline.
  • The “Hosted example profiles” table on Importing configuration now lists all 15 files with a “Prompts for” column so the trade-off between auto-filled and user-supplied fields is visible at a glance. The Bedrock/Mantle/gateway files are flagged as particularly useful when paired with init-config --minimal or as templates for orgs to fork and host on their own internal network.

1.3.0

  • New ccode add-profile command for adding profiles without hand-editing YAML. Three modes: interactive (walks you through name + the most common fields, with Anthropic and DeepSeek shown as examples and ENTER to skip), --from-file <path> (or - for stdin), and --from-url <url> (https only by default; pass --allow-http for plain HTTP). All three show what’s about to be added and ask for confirmation before writing. Each invocation adds exactly one profile; to add multiple, run it once per profile. Comments and unrelated content in the target file are preserved.
  • New --set-default flag on add-profile: also points default_profile: at the new profile in the same file. The confirmation diff shows both changes side by side, so the add and the default-flip are accepted or aborted together.
  • New prompt: field on profile YAMLs: a list of profile field names that ccode should ask the user to fill in at import time (e.g. prompt: [anthropic_auth_token]). Each name must be a valid Profile field; typos surface immediately. The list is stripped before writing, so the saved profile contains only the user’s answers, never the directive itself. ENTER skips a prompt; the field stays unset. Use --value <field>=<value> (repeatable) to pre-fill specific prompt slots non-interactively, or --no-prompts to skip them all (CI use). --value only fills declared prompt slots; arbitrary fields require writing your own YAML.
  • New split-key prompt: when add-profile targets a project config (./ccode.yaml, etc.) and the profile carries a real auth token, ccode offers a numbered choice between saving the auth fields in the user config (default; safer for committable repos) or in the project file. Splitting works through ccode’s existing field-level merge, so the two halves combine seamlessly at runtime. Refuses cleanly with the exact init-config command if the user picks “user config” but it doesn’t exist yet.
  • New ccode remove-profile <name> command, with a [Y/n] confirmation that defaults to yes (skip with --yes/-y). Warns if the profile being removed is the file’s default_profile.
  • New ccode set-default-profile <name> command for changing default_profile: in a config file without opening an editor. Validates that the named profile actually exists in that file (lists what’s available if not). One-line edit, so no confirmation prompt; no-op if already set.
  • All three commands accept an optional positional [target] argument (a directory, ., or an explicit file path) so they can edit project-level configs as well as the user config. If the target file doesn’t exist, ccode prints the exact init-config command needed to scaffold it first.
  • --from-file/--from-url accept one profile per file/URL: the top-level key in the YAML is the profile name, and its value is the profile body. Multi-profile imports are rejected so the workflow stays “one URL = one profile” (matching the hosted examples). Field names are validated strictly against the Config Reference, catching typos like anthropic_base_ur at import time. The env: map remains the escape hatch for anything not first-class.
  • Profile names are validated to avoid collisions with Claude Code or ccode flags, so the auto-generated --<name> shortcut keeps working. Trying to add a profile named model (or any other reserved name) is rejected with a clear error.
  • Conflict handling for --from-file/--from-url: if a profile of the same name already exists in the target file, ccode refuses unless --overwrite is passed.
  • HTTP fetching has a 10-second timeout, a 256 KiB response cap, surfaces non-2xx responses as errors, and logs the post-redirect URL.
  • ccode uninstall confirmations now default to yes (the user already typed uninstall); prompts updated from [y/N] to [Y/n] accordingly.
  • New website page: Importing configuration, with hosted example profile YAMLs for Anthropic, DeepSeek (Pro + Flash as separate files), OpenRouter, Z.AI, Kimi, Qwen, and MiniMax. Each example uses the prompt: field for its auth token, so import is one command + one paste. There’s also a short section on hosting your own profile YAMLs for your team or org.
  • Short cross-links to the new page from introduction.md, providers.md, and usage.md.

1.2.0

  • macOS builds are now signed and notarized, so Gatekeeper accepts them without the xattr -d com.apple.quarantine ./ccode workaround. The signed binary is universal (Intel and Apple Silicon in one binary), so the previous separate macos-amd64 and macos-arm64 ZIPs collapse into a single ccode-1.2.0-macos-universal.zip.
  • New macOS .pkg installer (ccode-1.2.0-macos.pkg) for one-click installs. Double-click, enter your admin password, and ccode lands in /usr/local/bin/ (already on PATH on every Mac). The .pkg is signed and notarized, so it works even without an internet connection at install time. The existing ccode install flow still works exactly as before from the universal ZIP, for anyone who prefers user-level installs or wants to inspect the binary first.
  • Documentation: removed the xattr quarantine step from the macOS install snippets in app/README.md, the Installation page, and the Introduction page. Added a short note about choosing between the universal ZIP and the .pkg installer.
  • Documentation: updated the “Known limitations” section in the Usage page to reflect that macOS code signing is now in place.

1.1.0

  • ccode init-config now accepts a directory (or .) as the path argument and creates ccode.yaml inside it. For example, ccode init-config --minimal . drops a project-level config in the current directory, ready to commit alongside your code.
  • ccode edit-config now accepts a directory as a positional argument and opens the project-level ccode.yaml inside it (checking <dir>/ccode.yaml and <dir>/.claude/ccode.yaml). If no project config is found there, ccode prints a hint instead of silently falling back to the user config.
  • ccode init-config now tailors its post-creation editor hint to whatever it just created. Creating a project config with init-config --minimal . prints ccode edit-config . (and ... vim .) instead of the generic user-config hint, so the suggested follow-up actually opens the file you just made. Custom-filename targets (init-config foo.yaml) skip the hint, since edit-config wouldn’t find them by directory.
  • Documentation: new “Practical examples” section in the Usage page walking through three split-config scenarios (different default profiles per project, different DeepSeek models per project, different env/telemetry settings per project).
  • Documentation: the Introduction page now shows the per-project default-profile pattern with a short example, so the split-config workflow is discoverable from the landing page.
  • Documentation: new “Known limitations” section in the Usage page covering Remote Control’s occasional flakiness, the permission-mode handoff into claude remote-control, and the macOS code-signing situation.
  • Documentation: a concrete macOS Zed example for ccode edit-config showing how to point at the in-bundle CLI (/Applications/Zed.app/Contents/MacOS/cli) when “Install CLI” from the Zed menu hasn’t been run, with a note on why GUI editors don’t need a --wait flag here. The shorter ccode edit-config zed form is shown alongside the other editors (vim, nano) in the generic examples list.

1.0.1

  • Documentation: the install snippets now show both PowerShell (.\ccode.exe install) and cmd (ccode.exe install) forms on Windows, since the leading .\ is required in PowerShell but optional in cmd.
  • Fix ccode uninstall on Windows leaving ccode.exe.old behind with an “Access is denied” error. The uninstaller now schedules a detached cleanup helper that removes the renamed binary and the install directory after the process exits.
  • Fix ccode uninstall failing to re-run after a previously failed uninstall: a stale ccode.exe.old in the install directory is now overwritten instead of blocking the rename.

1.0.0

First stable release.

  • Launcher that sets environment variables per profile and runs the official claude binary
  • All 235 official Claude Code environment variables supported as first-class YAML fields, plus an env: escape hatch for anything unmapped
  • Named profiles with automatic --<profile> shortcuts, collision-checked against Claude Code flags
  • Two-level config merge: user-level config (carries secrets) and optional project-level config (./ccode.yaml or ./.claude/ccode.yaml) merged at the field level
  • --config <path> flag to swap in an explicit project-level config
  • Global env: block applied to all profiles; per-profile env: blocks take priority
  • Subscription passthrough via the empty default: {} profile (launches Claude Code as-is with your existing subscription)
  • Auth validation per profile with [no auth] warning in ccode profiles
  • Built-in profile examples for Anthropic (direct + API), Amazon Bedrock, Bedrock Mantle, Google Vertex AI, Microsoft Foundry, DeepSeek, OpenRouter (with preset support), Z.AI, Moonshot Kimi, Alibaba Qwen, and MiniMax
  • Local model support (llama.cpp, vLLM, Ollama, LM Studio) via anthropic_base_url
  • Launch modes: always_control / always_auto / always_yolo config flags with matching --control / --auto / --yolo CLI overrides (and --no-* counterparts)
  • Warning when combining --control with --auto or --yolo, since Claude Code’s remote-control ignores permission flags at the time of writing
  • ccode init-config with --reset, --minimal, and custom output path
  • ccode edit-config opens the config in your preferred editor (command arg > $EDITOR > $VISUAL > platform default)
  • ccode install for user-level install, --system for system-wide; PATH updated via Windows registry + WM_SETTINGCHANGE broadcast, or shell rc files on Unix (bash, zsh, fish, .profile)
  • ccode profiles lists available profiles, default, launch modes, shortcuts, and auth status
  • Argument passthrough for unknown flags, with -- as the explicit passthrough sentinel
  • Subcommand typo hints (ccode init -> init-config, ccode --install -> install, etc.)
  • Cross-platform builds for Windows, Linux, and macOS (amd64 + arm64)
  • Documentation site at ccode.kronis.dev