Skip to main content
Most CC Commander issues fall into one of a few categories: installation path problems, missing system dependencies, state corruption, or configuration mismatches. Work through the relevant section below. When in doubt, run ccc --test first — it runs a 22-point check and points to the specific failure.
The ccc binary is not on your PATH. This usually means the symlink was not created during installation or ~/.npm-bin is missing from your shell’s PATH.Fix — reinstall:
npm install -g cc-commander
Fix — add npm bin to PATH:
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.npm-bin:$PATH"
# or
export PATH="$(npm bin -g):$PATH"
Then reload your shell:
source ~/.zshrc  # or ~/.bashrc
Fix — run the installer again:
curl -fsSL https://raw.githubusercontent.com/KevinZai/cc-commander/main/install-remote.sh | bash
After reinstalling, verify with which ccc.
The 22-point self-test checks Node.js version, binary paths, skill directories, hook wiring, and more. Look at which test number fails.Node.js version — CC Commander requires Node.js ≥ 18. Check your version:
node --version
If it is below 18, install Node.js 18 or later via nodejs.org or your version manager (nvm, fnm).State corruption — If the test reports corrupt state files, repair them:
ccc --repair
After repair, re-run:
ccc --test
If specific tests still fail after repair, run the installer again with --verify:
./install.sh --verify
Split mode requires tmux. If it is not installed, ccc falls back or errors on launch.Check if tmux is installed:
which tmux
Install tmux:
# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Arch
sudo pacman -S tmux
Use simple mode instead: If you prefer not to install tmux, run:
ccc --simple
This opens the menu in your current terminal without creating tmux windows.
Long sessions with verbose tool output consume context quickly. Three approaches address this:Enable the context-guard hook — it warns at ~70% and auto-saves your session for clean resumption after compaction.Use the caveman skill — strips markdown, emojis, and prose from responses for approximately 75% output token savings during fast iteration:
"use the caveman skill"
Scope your dispatches — ccc --dispatch works best with focused, single-concern tasks. Large tasks consume more context per dispatch. Split large work into smaller dispatches.Enable context-mode — sandboxes tool output into SQLite + FTS5, returning only BM25 snippets. Delivers up to 98% context reduction on tool-heavy tasks.
If a skill you expect is not available in a session, it may not be installed or may be in a tier that was not selected.Check what is installed:
ccc --skills list
Install a specific skill:
ccc --skills install <skill-name>
Install a full tier:
./install.sh --skills=recommended
Load a skill on demand without installing it — say this inside a session:
"use the skill-name skill"
This loads from disk without modifying your installed tier.
If queued tasks are not being picked up, work through these checks in order.Check the queue:
ccc --queue-list
Check daemon status:
ccc --status
Restart the daemon:
ccc --daemon-stop && ccc --daemon
If the daemon was stopped by a crash or system restart, the queue is preserved — tasks will process after restart.
The cost-alert hook fires at approximately 0.50and0.50 and 2.00 per session. If you regularly run sessions that exceed these thresholds, adjust the budget or disable the alerts.From inside a session:
/ccc:settings
Navigate to Cost → Budget to raise the alert thresholds.Disable the hook entirely (not recommended for shared environments):
KZ_DISABLE_COST_ALERT=1 ccc
For longer YOLO-mode sessions, the budget is set explicitly at $10 with a 100-turn cap — cost alerts will still fire as a secondary warning.
YOLO mode can be halted between cycles by a stop file. If a previous session placed a stop file, YOLO will not resume.Check for the stop file:
ls ~/.claude/commander/yolo-stop
Remove it to allow YOLO to run again:
rm ~/.claude/commander/yolo-stop
You can also create this file intentionally to stop an in-progress YOLO run at the next cycle boundary:
touch ~/.claude/commander/yolo-stop
The knowledge system extracts lessons only from sessions that complete normally. Force-quitting with kill, closing the terminal mid-session, or killing the process skips the extraction step.Let sessions end naturally — press Escape or q to cancel a task and return to the menu, then exit from the menu. This allows the Stop hooks to fire and the knowledge extractor to run.Check for existing lesson files:
ls ~/.claude/commander/knowledge/
ls ~/.claude/commander/sessions/
If these directories are empty after several sessions, check that auto-lessons and the knowledge hooks are wired in your ~/.claude/settings.json.
CC Commander aggregates 19 vendor packages as git submodules. They are updated automatically via GitHub Actions weekly, but your local copy only updates when you run:
ccc --update
This pulls the latest release and reinstalls. Your state, sessions, and knowledge base are preserved.
The OpenClaw adapter requires the OpenClaw process to be running before CC Commander launches. If CCC starts first, it will not find the OpenClaw socket.Correct startup order:
  1. Start OpenClaw
  2. Verify it is running: check /claw status inside OpenClaw
  3. Launch CC Commander: ccc
The openclaw-adapter and openclaw-sync hooks auto-detect the running OpenClaw process on session start. If the hooks are not listed as active in ccc --status, restart CCC after confirming OpenClaw is running.

​
Still Stuck?

Run the full self-test and share the output when asking for help: 
ccc --test
Report issues at github.com/KevinZai/cc-commander and include the output of ccc --test and your Node.js version (node --version).