FAQ

General

What is ccode?

ccode is a third-party launcher for Claude Code that adds profile management. It lets you switch between different model providers (Anthropic, DeepSeek, OpenRouter, Bedrock, etc.) with a single flag.

Is ccode affiliated with Anthropic?

No. ccode is not affiliated with or endorsed by Anthropic. It’s an independent, source-available tool.

Why not just use OpenCode (or similar)?

Other harnesses like OpenCode are lovely, but some people are more familiar with Claude Code, and it also has good support for various models on a per-task basis (e.g. sub-agents), permission controls etc.

You can even do something like launch it with ccode --deepseek remote-control and view the session either in your browser or the Claude Desktop app on any of your devices, even if the underlying model is different!

So with this tool you get both the Claude Code user experience that you enjoy, as well as pricing from other providers that you may enjoy more. See also Similar Software for alternatives.

Does ccode collect any data?

No. There’s no analytics or telemetry in ccode itself. Your prompts, API keys, and usage data stay between you and your chosen model provider.

Does ccode modify Claude Code?

No. ccode is a launcher, not a patch. It sets environment variables and then runs the standard claude binary. Claude Code itself is unchanged.

Configuration

Where is my config file?

Platform	Path
Windows	`%APPDATA%\ccode\config.yaml`
Linux / macOS	`~/.config/ccode/config.yaml`

Run ccode profiles to see the exact path, or ccode edit-config to open it directly.

What’s the difference between the full and minimal config?

The full config (ccode init-config) includes commented-out examples for every supported provider: cloud providers (Bedrock, Vertex, Foundry), third-party providers (DeepSeek, OpenRouter, Z.AI, Kimi, Qwen, MiniMax), and local models. It’s 350+ lines.

The minimal config (ccode init-config --minimal) includes only the top-level settings and Anthropic direct profiles. It’s about 100 lines, and is useful for quick setup or project-level configs.

Can I use a project-level config?

Yes. Place a ccode.yaml (or .claude/ccode.yaml) in your project root. It merges with your user config at the field level, so you can put model settings in the project config and keep API keys in your user config. See Configuration for details.

How do I add a provider that isn’t in the default config?

Any provider that exposes an Anthropic-compatible API endpoint (/v1/messages) works. Set anthropic_base_url to the provider’s endpoint and anthropic_auth_token to your API key. See Providers for examples.

The fastest way to add one is ccode add-profile, which walks you through the fields interactively. You can also point it at a hosted YAML file with ccode add-profile --from-url <url> (the Importing configuration page lists ready-to-import examples for every supported provider).

Local proxy

What’s the local proxy, and when does it run?

It’s an in-process HTTP server that ccode 2.0.0+ can stand up on 127.0.0.1 to sit between Claude Code and your third-party provider. Claude Code dials it instead of the real upstream; the proxy strips inbound auth headers, attaches your configured upstream credential, and forwards the request. The full story is on the Local proxy page.

You’ll see it auto-attach when you use --control (or always_control: true) with a profile that points at a third-party provider - the combination Claude Code 2.1.139+ otherwise refuses. ccode prints a log line below the usual “using profile” line in that case, including the proxy’s bind address. For the default subscription-passthrough profile (and for cloud-provider profiles like Bedrock or Vertex) the proxy stays out of the way.

Can I run the proxy on its own, without Claude Code?

Yes - ccode proxy [--profile <name>] starts only the proxy and blocks until Ctrl+C, with no Claude Code launch. Useful for pointing several claude invocations (or any other Anthropic-compatible tool) at one upstream. Details on the Local proxy page.

Where do the proxy’s pidfiles live?

Under a per-user subdirectory of the system temp dir: <tmp>/ccode-<uid>/pid/<pid>.json on Unix, <tmp>/ccode/pid/<pid>.json on Windows (where %TEMP% is already per-user). They’re metadata only, no credentials in them. Cleaned up on clean shutdown; on the next launch the pid directory is swept for entries whose ccode process is no longer alive.

Can I switch models or providers without restarting?

Yes - launch with ccode --dynamic <profile> and then, from another terminal, run ccode sessions <id> set-profile <name> to point the running session at a different configured profile. Claude Code keeps going; in-flight requests finish on the old upstream and new ones use the new one. ccode sessions lists what’s running. See the Dynamic proxy page.

Profiles

How do profile shortcuts work?

Every profile name automatically becomes a --<name> CLI shortcut. If you have a profile called deepseek, then ccode --deepseek is equivalent to ccode --profile deepseek.

If a profile name collides with a Claude Code flag (e.g. you named a profile model), the shortcut is disabled and you’ll need to use --profile model instead.

Can I use multiple profiles at once?

No. Only one profile is active per session. However, you can set a different default_profile in a project-level config, so different projects can use different providers automatically.

How do I set a default profile?

Set default_profile in your config:

default_profile: "deepseek"

This profile is used when you run ccode without specifying one.

Troubleshooting

“No configuration found” on first run

This is normal. ccode creates a default config automatically on first run and tells you where it is. Edit the file to add your API keys, then run ccode again.

My profile shows “[no auth]”

This means the profile has no authentication mechanism set up. For third-party providers, you need anthropic_auth_token. For Anthropic API, you need anthropic_api_key. For cloud providers (Bedrock, Vertex, Foundry), set the corresponding claude_code_use_* flag (those use your AWS/GCP/Azure credentials). Run ccode profiles to see which profiles have this warning.

Claude Code flags aren’t working

Make sure you’re putting ccode flags before Claude Code flags:

# Correct
ccode --deepseek --continue

# Also correct (-- forces everything after it to pass through)
ccode --deepseek -- --some-flag

All flags that aren’t recognized by ccode are passed through to Claude Code automatically.

Licensing and pricing

Why source available license, not open source? Why not develop on GitHub?

A source available license was picked, so people wouldn’t just resell this app or sidestep the distribution method.

The limitation on no distribution of binaries is there so people also can’t just put something in the app that might be malicious or problematic, like telemetry. You are allowed to make forks and even make them available to others, but it must be a source distribution - so people can inspect the code and compile it themselves.

The source is not on GitHub, because I’m not really interested in the social aspects of development and providing free support. You can e-mail me, just don’t be mean.

Why charge money for this at all? Why allow 0 USD prices (free downloads)? Why Itch.io?

Someone has to pay for the Apple Developer account license, so I can sign the software and not have to ask people to work around quarantine restrictions.

At the same time, if someone doesn’t want to pay, they can still download the program for free, since that’s probably a bit safer than something like torrenting. Treat it like a WinRAR trial if you please.

I also chose Itch.io for the pay-what-you-want features, so it meets people’s needs better, given how many with different circumstances there are. If this shows that people will just download it for free and not pay, then so be it.

Frankly I’m helping a friend with their medical expenses, so I don’t really get to bad about trying to earn a buck in addition to my job with this.

What about updates? Do I have to pay if I only want the source?

I mostly ask for money for the prebuilt binaries and even that is optional.

If you feel like throwing a few dollars my way for the source, then that’s nice, if not, then that’s okay.

If updates come out and you’ve bought an older version, I don’t see an issue of you downloading the new version for free.

Can’t this be replicated in an evening?

Sure, probably in a few days. I just made something that I wanted to use. No reason why I couldn’t make it more widely available.

There was some annoying stuff around changing env variables and just multi-OS support in general, and OpenRouter seems to not work too well with claude -p and needs workarounds.

Development questions

I found a bug, how do I report it?

If you want, you can send me an e-mail, the details are on my homepage.

I’ve also created a dedicated Itch.io thread for reporting any bugs or issues: Bug Reports

Past that, I can’t commit to an SLA, since my job takes up most of my time.

Is there a roadmap?

Not quite, I’ll add whatever features seem nice.

The profile-management commands (add-profile with interactive / --from-file / --from-url flavors, remove-profile, and set-default-profile) shipped in 1.3.0, along with hosted example YAMLs for every supported provider you can pull in with one command.

2.0.0 added the Local proxy - an in-process Anthropic passthrough that auto-attaches around your session to keep Remote Control working with third-party providers on Claude Code 2.1.139+. 3.0.0 built on it with the Dynamic proxy: ccode --dynamic plus a ccode sessions CLI (and an interactive TUI) for switching a running session’s backend on the fly. The remaining idea on my mind is an optional Anthropic API to OpenAI API translation layer for providers that don’t speak Anthropic-compat natively - I’ve done something similar already internally for a company project.

If you have any other ideas, you can ask about them in the new Itch.io thread: Feature Requests

ccode - Custom Claude Code launcher

FAQ