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

# FAQ

> Fix common issues with Node, SDKs, CLIs, provider auth, stopping generation, and debug logs.

Match the message you see below. If it still fails, send the logs from **Output → CC GUI** and the steps to reproduce to [GitHub Issues](https://github.com/hpstream/vscode-cc-gui/issues).

## Install and open

<AccordionGroup>
  <Accordion title="The Marketplace search does not find CCGUI">
    Search `CCGUI` or `MossX`. The full display name is **CCGUI / CC GUI（Claude Codex OpenCode Kimi）**, and the extension ID is `MossX.vscode-cc-gui`.

    You can also open the [Marketplace page](https://marketplace.visualstudio.com/items?itemName=MossX.vscode-cc-gui) and click Install. VS Code must be 1.85 or later.
  </Accordion>

  <Accordion title="The sidebar is empty after install">
    Open a workspace folder first. Without a workspace root, file mentions, sessions, and the working directory have no context.

    Then click **CC GUI** in the Activity Bar, or run **CC GUI: Open CC GUI**.
  </Accordion>
</AccordionGroup>

## Node.js and SDKs

<AccordionGroup>
  <Accordion title="It says Node.js was not found or the version is too old">
    CC GUI needs Node.js 20+, and it only uses the extension's own path. It does not change the project terminal.

    1. Install a separate Node 20+
    2. Run `node -p "process.execPath"`
    3. Paste the full path into **Settings → General → Environment**, or into `ccGui.nodePath`
    4. On Windows it must point to `node.exe`

    See [Prepare your environment](/en/vscode/start/setup).
  </Accordion>

  <Accordion title="It says the SDK is not installed">
    Open **Settings → SDK dependencies** and install the Claude Agent SDK or Codex SDK. **Go to install** in the chat area jumps to this page.

    If Codex is missing CLI integrity, it also shows as not installed and you need to install it again.
  </Accordion>

  <Accordion title="SDK install failed">
    Copy the install log to an AI in your local terminal, or send it to GitHub. Common causes:

    * Wrong Node path
    * npm registry or network blocked
    * No write permission on `~/.codemoss/dependencies/`
  </Accordion>
</AccordionGroup>

## Providers and login

<AccordionGroup>
  <Accordion title="Claude says no provider is configured">
    Open **Settings → Provider management → Claude Code** and pick one:

    * Add a provider with an API key
    * Authorize reading `~/.claude/settings.json`
    * Authorize an existing CLI login

    After you revoke local settings.json access, you must enable another provider. Otherwise Claude stays disabled.
  </Accordion>

  <Accordion title="A subscription account works in the terminal but not in the extension">
    For Claude:

    1. Sign in successfully in a terminal
    2. Keep `env` empty in `~/.claude/settings.json`
    3. Restart VS Code
    4. If it still fails, add `HTTP_PROXY` using the proxy example in [Claude Code](/en/vscode/providers/claude)

    For Codex: run `codex login` first, authorize reading `~/.codex/`, then restart VS Code.
  </Accordion>

  <Accordion title="A CLI stays Not installed">
    The extension does not install Grok / Kimi / OpenCode / Pi for you. Confirm `xxx --version` works in a system terminal, then go to **Settings → Provider management → CLI** and click **Detect again**.

    VS Code launched from the Dock / Start menu sometimes cannot see the terminal `PATH`. Add the install directory to the system environment variables, then restart VS Code. See [Detect and install](/en/vscode/providers/cli).
  </Accordion>
</AccordionGroup>

## During a chat

<AccordionGroup>
  <Accordion title="I clicked Send and got no reply">
    Check in this order:

    1. Is the current provider enabled?
    2. Is the SDK or CLI ready?
    3. Are you stuck on a permission / question dialog?
    4. Is there an error in **Output → CC GUI**?
  </Accordion>

  <Accordion title="Stop does not kill a CLI">
    From 0.1.3, Stop ends the Grok / Kimi / OpenCode / Pi child process. Upgrade to the latest Marketplace version. After you stop it yourself, the completion toast and sound do not play.
  </Accordion>

  <Accordion title="An old message still flashes in a new session">
    0.1.3 fixed leftovers from delayed writes. If it still happens after you upgrade, open another editor tab instead of reusing the current one.
  </Accordion>

  <Accordion title="A tool call spinner never stops">
    0.1.2 fixed a spinner that stayed after multi-step tools finished. Upgrade first. If it still happens, turn on the debug log, keep that turn, and file an issue.
  </Accordion>

  <Accordion title="I cannot click the bottom provider / mode buttons">
    0.1.1 fixed a clipped toolbar. If you still cannot click them after upgrading, widen the sidebar or open CC GUI in an editor tab.
  </Accordion>

  <Accordion title="Grok cannot see an image I sent">
    From 0.1.2, images are passed to Grok with `--prompt-file`. Upgrade, and confirm the attachment thumbnail is still in the input box.
  </Accordion>
</AccordionGroup>

## Debugging

<AccordionGroup>
  <Accordion title="How do I turn on the debug log and developer tools">
    1. Open **Settings → General → Behavior → Debug log**, or enable `ccGui.enableDebugLog`
    2. Logs are in **View → Output → CC GUI**
    3. A developer tools button appears in the view title bar. You can also run **CC GUI: Open Webview Developer Tools**

    The debug log is off by default.
  </Accordion>
</AccordionGroup>