Getting started

Requirements

Claude Dialects builds a single static executable from source. Before you begin, make sure you have:

• macOS or Linux, on amd64 or arm64 — the current target platforms
• Go 1.26.9 or newer — to build from source
• Claude Code — available as claude on your PATH
• Node.js 22.13+ and npm (optional) — required only for Cursor and GitHub Copilot SDK dialects

The dashboard frontend is embedded in the executable. Running it, make build, and make install do not require Node.js; contributors need a package-compatible Node.js release when rebuilding dashboard source.

Install Claude Dialects

Clone the repository, build, and install the cc-dialect manager to ~/.local/bin:

git clone https://github.com/stefandevo/claude-dialects.git
cd claude-dialects
make install
export PATH="$HOME/.local/bin:$PATH"

# Persist PATH — Zsh (macOS default) or Bash (most Linux distributions)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

This produces one static executable at ~/.local/bin/cc-dialect. There are no prebuilt binaries or GitHub releases — everyone builds from the checked-out source.

To update later, run cc-dialect upgrade — it fetches the latest source into a temporary directory, rebuilds, atomically replaces the installed binary, and finishes with cc-dialect doctor --fix to restart stale proxies and bridge runtimes. It needs the same git and Go toolchain as the install; the original clone is not required.

Create your first dialect

Let's create an OpenAI Codex dialect using the codex-sol preset (GPT-6 Sol as the main and subagent model, Luna on haiku):

cc-dialect create cc-codex --preset codex-sol
cc-dialect auth cc-codex codex
cc-dialect shim install cc-codex
cc-codex

For preset-based routes, create prints the remaining setup steps in the correct order. An arbitrary custom model ID cannot determine its provider automatically, so you must supply and follow the appropriate authentication or token route yourself. OAuth dialects will not launch or list models before authentication — if you skip auth, the error includes the exact command to run.

Inside Claude Code you can switch models and effort live:

/model opus    # → gpt-6-sol
/model sonnet  # → gpt-6-sol
/model haiku   # → gpt-6-luna
/effort high

The four-step workflow

Every dialect follows the same rhythm, regardless of provider:

Naming convention

Use the cc-<provider> naming convention for generated commands. It makes dialects easy to recognize and avoids collisions with existing provider CLIs such as gemini or cursor.

See the full Providers guide for complete setup blocks for each route.

Run several dialects

Each dialect gets checked high-numbered localhost ports, a private local proxy key and runtime state, and its own Claude Code state. Provider credentials remain route-dependent. Create as many as you need:

cc-dialect create cc-codex-work --preset codex
cc-dialect auth cc-codex-work codex
cc-dialect shim install cc-codex-work

cc-dialect create cc-kimi-work --preset kimi
cc-dialect auth cc-kimi-work kimi
cc-dialect shim install cc-kimi-work

# Each gets its own port, local proxy state, and history
cc-codex-work    # embedded proxy :43170
cc-kimi-work     # embedded proxy :43171

Ports are actively checked and allocated per dialect starting at :43170. A port already bound by any process is skipped during creation and rejected again at startup.

Every dialect also gets a generated statusline that names the dialect — e.g. cc-codex · GPT-6 Sol · effort:auto · ctx 42% — with the name colored per provider route, so parallel terminals are easy to tell apart. cc-dialect create writes instances/<name>/statusline.sh and wires it into the dialect's isolated claude/settings.json; older dialects are backfilled the next time they run. The script uses jq — preinstalled on recent macOS, usually an explicit install on Linux — and stays empty when it is missing. To customize, point the statusLine key in that settings.json at your own script — a user-set statusLine is never overwritten. To remove it, delete the statusLine key; it is never re-added once the generated script exists.

Because that settings.json is isolated, an opt-out in your global ~/.claude never reaches a dialect — so every dialect is also seeded with "attribution": {"commit": "", "pr": ""}, which keeps the Co-Authored-By: Claude trailer out of commits and the attribution block out of pull request bodies. It is only written when the dialect has no attribution preference of its own, so a value you set is never overwritten; to bring the trailer back, set an explicit value rather than deleting the key. Existing dialects are updated the next time they run, or all at once with cc-dialect doctor --fix, which cc-dialect upgrade invokes for you.

Mix providers in one session

A single dialect can hold OAuth credentials for several providers at once, so each model tier can point at a different provider. The mixed-frontier preset runs Claude Fable 5.1 as the main model and maps opus to GPT-6 Sol, sonnet to Kimi K3, and haiku to Grok 4.7 — one Claude Code session whose agents run on different providers. Authenticate every provider into the same dialect:

cc-dialect create cc-mixed --preset mixed-frontier
cc-dialect auth cc-mixed claude
cc-dialect auth cc-mixed codex
cc-dialect auth cc-mixed kimi
cc-dialect auth cc-mixed xai
cc-dialect shim install cc-mixed
cc-mixed

cc-mixed refuses to start until every tier's provider is authenticated, and cc-dialect doctor lists any provider still needing a login. See Mixed / multi-provider dialects for the full mapping table and provider terms.

Open the web dashboard

Manage configured dialects from the bundled localhost dashboard:

cc-dialect web

# Print the URL without opening a browser
cc-dialect web --no-browser

# Use a fixed numeric loopback address
cc-dialect web --listen 127.0.0.1:8765

The default is an available ephemeral port on 127.0.0.1. The command stays in the foreground; press Ctrl-C to stop it. Numeric loopback addresses are required — localhost, wildcard addresses, remote access, and reverse proxies are not supported.

The dashboard can inspect safe configuration views, create and update dialects, start or stop runtimes, manage tracked native launchers, and install or refresh the Cursor runtime. OAuth login, Copilot setup, logs, shims, and launching Claude Code sessions remain CLI workflows.

Next steps