> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commanderplugin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting CC Commander — Common Issues and Fixes

> Fixes for the most common CC Commander problems: command not found, failing self-tests, split mode issues, context overflow, daemon problems, and more.

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.

<AccordionGroup>
  <Accordion title="`ccc: command not found`">
    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:**

    ```bash theme={null}
    npm install -g cc-commander
    ```

    **Fix — add npm bin to PATH:**

    ```bash theme={null}
    # Add to ~/.bashrc or ~/.zshrc
    export PATH="$HOME/.npm-bin:$PATH"
    # or
    export PATH="$(npm bin -g):$PATH"
    ```

    Then reload your shell:

    ```bash theme={null}
    source ~/.zshrc  # or ~/.bashrc
    ```

    **Fix — run the installer again:**

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/KevinZai/cc-commander/main/install-remote.sh | bash
    ```

    After reinstalling, verify with `which ccc`.
  </Accordion>

  <Accordion title="`ccc --test` fails">
    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:

    ```bash theme={null}
    node --version
    ```

    If it is below 18, install Node.js 18 or later via [nodejs.org](https://nodejs.org) or your version manager (`nvm`, `fnm`).

    **State corruption** — If the test reports corrupt state files, repair them:

    ```bash theme={null}
    ccc --repair
    ```

    **After repair, re-run:**

    ```bash theme={null}
    ccc --test
    ```

    If specific tests still fail after repair, run the installer again with `--verify`:

    ```bash theme={null}
    ./install.sh --verify
    ```
  </Accordion>

  <Accordion title="Split mode not working">
    Split mode requires `tmux`. If it is not installed, `ccc` falls back or errors on launch.

    **Check if tmux is installed:**

    ```bash theme={null}
    which tmux
    ```

    **Install tmux:**

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    ccc --simple
    ```

    This opens the menu in your current terminal without creating tmux windows.
  </Accordion>

  <Accordion title="Context fills up too fast">
    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.
  </Accordion>

  <Accordion title="Skills not appearing">
    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:**

    ```bash theme={null}
    ccc --skills list
    ```

    **Install a specific skill:**

    ```bash theme={null}
    ccc --skills install <skill-name>
    ```

    **Install a full tier:**

    ```bash theme={null}
    ./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.
  </Accordion>

  <Accordion title="Daemon not processing tasks">
    If queued tasks are not being picked up, work through these checks in order.

    **Check the queue:**

    ```bash theme={null}
    ccc --queue-list
    ```

    **Check daemon status:**

    ```bash theme={null}
    ccc --status
    ```

    **Restart the daemon:**

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Cost alerts firing too often">
    The `cost-alert` hook fires at approximately $0.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):

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="YOLO mode stopped early">
    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:**

    ```bash theme={null}
    ls ~/.claude/commander/yolo-stop
    ```

    **Remove it to allow YOLO to run again:**

    ```bash theme={null}
    rm ~/.claude/commander/yolo-stop
    ```

    You can also create this file intentionally to stop an in-progress YOLO run at the next cycle boundary:

    ```bash theme={null}
    touch ~/.claude/commander/yolo-stop
    ```
  </Accordion>

  <Accordion title="Knowledge not compounding between sessions">
    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:**

    ```bash theme={null}
    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`.
  </Accordion>

  <Accordion title="Vendor packages outdated">
    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:

    ```bash theme={null}
    ccc --update
    ```

    This pulls the latest release and reinstalls. Your state, sessions, and knowledge base are preserved.
  </Accordion>

  <Accordion title="OpenClaw integration not detecting">
    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.
  </Accordion>
</AccordionGroup>

***

## Still Stuck?

Run the full self-test and share the output when asking for help:

```bash theme={null}
ccc --test
```

Report issues at [github.com/KevinZai/cc-commander](https://github.com/KevinZai/cc-commander) and include the output of `ccc --test` and your Node.js version (`node --version`).