Documentation — claude-codex-local

┌─ /install 3 paths · pick one

Get started

01Installation

Available on PyPI. Pip, uv, or a one-line shell installer. All paths end at the same wizard.

01 pip

recommended

$pip install claude-codex-local

02 uv

alternative

$uv tool install claude-codex-local

03 curl · no clone required

shell

$bash <(curl -sSL https://raw.githubusercontent.com/luongnv89/claude-codex-local/main/install.sh)

04 from source

advanced

$git clone https://github.com/luongnv89/claude-codex-local.git

$cd claude-codex-local

$python3 -m venv .venv && source .venv/bin/activate

$pip install -e .

$ccl

├─ /usage ~10 min · first run

Workflow

02Three steps. Ten minutes.

Local-first or cloud-routed — same wizard, same aliases, same skills intact.

01STEP

Install

Run one command. The wizard auto-detects your installed runtimes, checks your hardware, and flags anything missing.

02STEP

Configure

Answer a few prompts. Pick your runtime and model — or let llmfit pick one that fits your machine.

03STEP

Run

Type cc or cx for local. cc9/cx9 for 9router. cco/cxo for OpenRouter.

├─ /commands 5 subcommands

CLI reference

03Available commands

Everything you need lives under ccl. No daemons. No background services.

ccl setup

Interactive setup wizard. Auto-detects hardware and installed runtimes, then guides you through every config step.

Options

--resume — resume from last failed step

--non-interactive — CI mode, no prompts

ccl doctor

Verify your configuration. Checks API keys, model availability, server connectivity, and config integrity.

ccl find-model

Hardware-aware model recommendations via llmfit. Analyzes RAM and GPU; suggests models that actually fit.

ccl serve

Start the llama-server with automatic restart on crashes. MTP auto-detect: Multi-Token Prediction variants (Qwen, GLM, DeepSeek) are detected via GGUF metadata probe + filename fallback, and --spec-type draft-mtp --spec-draft-n-max 5 is added for faster decode. Conflict guard disables MTP when --mmproj or --parallel > 1 are present.

Env overrides

LLAMACPP_MTP_ENABLED=0/1 — force off/on

LLAMACPP_SPEC_DRAFT_N_MAX=N — override default 5 (range 1–16)

ccl run -p "prompt"

Non-interactive mode for scripted workflows. Execute a single prompt and exit. Streams output to stdout. Automatically prepends the freshest *other* harness's transcript for $PWD as a [prior context] block so you can hand off mid-task.

Options

--no-context — skip the cross-harness bridge (also via CCL_SESSION_BRIDGE=0)

ccl session

Inspect and manage the shared conversation JSONL files under ~/.claude-codex-local/sessions/. CCL auto-imports each harness's native session for $PWD after every ccl run; this command surface is for review and manual sync. cwd-scoped, 7-day staleness cap, best-effort secret redaction.

Subcommands

list — show all captured harness files + counts

show <agent> — print one harness's messages

sync --from A --to B — copy messages A → B (idempotent, redacted)

truncate <agent> --keep N — keep only the last N (--keep required)

clear <agent> — delete one harness's file

├─ /config isolated · ~/.claude-codex-local/

Advanced

04Configuration

All state lives in one folder. Delete it to roll back. Your real ~/.claude and ~/.codex are never touched.

Configuration files [4]

config.json

Main configuration file. Stores selected runtime, model, harness, and routing backend.

models.json

Model registry and metadata. Populated by find-model and the wizard.

.9router_key

9router API key. Stored with mode 0600.

.openrouter_key

OpenRouter API key. Stored with mode 0600.

Shell aliases [3 groups]

cc · cx · ccp

Local model sessions. Claude Code, Codex CLI, and Pi harness — each backed by your selected local runtime.

cc9 · cx9

9router cloud routing. Same harnesses, alternate providers (OpenAI, DeepSeek, etc.).

cco · cxo · cpo

OpenRouter hosted routing. Dozens of models via a unified API. No daemon to install.

Environment variables [2]

CCL_OPENROUTER_MODEL

Override the default OpenRouter model. Defaults to anthropic/claude-sonnet-4.6.

NO_COLOR

Disable colored output across all ccl subcommands.

└─ /proven-paths end-to-end tested

Compatibility

05Tested combinations

Combinations that have been smoke-tested end-to-end. ✓ verified, ⚠ partial.

✓ Claude Code + Ollama + gemma4:26b ✓ Codex CLI + Ollama + gemma4:26b ✓ Claude Code + 9router + OpenAI/DeepSeek ✓ Claude Code + OpenRouter + claude-sonnet-4.6 ⚠ Claude Code + LM Studio + Qwen3 ✓ Any + llama.cpp + GGUF (Hugging Face) ✓ Any + llama.cpp + MTP variant (Qwen / GLM / DeepSeek)

/docs_