Getting started

Requirements

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

• macOS — current target platform
• Go 1.26.5 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 across terminal restarts
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

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.

Create your first dialect

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

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-5.6-sol
/model sonnet  # → gpt-5.6-terra
/model haiku   # → gpt-5.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.

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