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

# Troubleshooting GitHits: auth, MCP, and startup issues

> Fix common GitHits problems: keychain prompts, expired tokens, MCP server not loading, Node.js version errors, and slow npx startup.

If something is not working as expected, start with `npx githits@latest auth status` to confirm you are authenticated and the CLI is reachable. The issues below cover the most common problems and how to resolve them.

<AccordionGroup>
  <Accordion title="Keychain prompts keep appearing on macOS">
    macOS asks for permission when GitHits accesses the system keychain. When the prompt appears, click **Always Allow** to stop it from appearing again for this CLI binary.

    If prompts persist even after selecting **Always Allow** — for example, because your agent calls GitHits frequently and macOS keeps re-prompting — switch to file storage mode. Add the following to your config file, then run `npx githits@latest login --force` to re-store credentials:

    ```toml theme={null}
    # ~/.config/githits/config.toml
    [auth]
    storage = "file"
    ```

    Or switch for a single session:

    ```bash theme={null}
    GITHITS_AUTH_STORAGE=file npx githits@latest login --force
    ```

    Note that file storage is not encrypted. Use it only on machines where you trust local user-account access.
  </Accordion>

  <Accordion title="Login token expired or refresh failed">
    GitHits refreshes tokens automatically on next use. After an extended idle period, the refresh may fail and you will see an authentication error.

    Run `npx githits@latest login` again to re-authenticate:

    ```bash theme={null}
    npx githits@latest login
    ```

    If you are in a headless environment, use:

    ```bash theme={null}
    npx githits@latest login --no-browser
    ```

    This prints a URL you can open on another device to complete login.
  </Accordion>

  <Accordion title="Agent isn't calling GitHits tools">
    First, confirm the GitHits MCP server is connected to your agent. In Claude Code, run `/mcp` and check that a GitHits entry appears in the list. In other tools, check your MCP server panel or equivalent.

    If GitHits is not listed:

    1. Re-run `npx githits@latest init` to re-configure your tool:

       ```bash theme={null}
       npx githits@latest init
       ```

    2. If that does not detect your tool, check the MCP config file for your tool manually and verify the `githits` entry is present.

    3. Verify you are authenticated:

       ```bash theme={null}
       npx githits@latest auth status
       ```

    If GitHits is listed but the agent is not calling its tools, prompt it directly. See [Trigger GitHits manually](/guides/trigger-githits) for copy-paste prompt patterns.
  </Accordion>

  <Accordion title="`npx githits@latest init` didn't detect my tool">
    `npx githits@latest init` supports a fixed list of local coding tools. For any MCP-capable client that supports remote servers, configure GitHits manually by adding the remote MCP server entry to your client's config:

    ```json theme={null}
    {
      "mcpServers": {
        "githits": {
          "url": "https://mcp.githits.com"
        }
      }
    }
    ```

    Check your client's documentation for the exact config file location and schema. See [Manual remote MCP setup](/installation/manual-setup) for a full walkthrough.

    If you would like your tool to be supported by `npx githits@latest init` auto-detection, [open a GitHub issue](https://github.com/githits-com/githits-cli/issues) to request it.
  </Accordion>

  <Accordion title="Node.js version error">
    GitHits requires Node.js 20 or later. Check your current version:

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

    If you are on an older version, upgrade using [nvm](https://github.com/nvm-sh/nvm):

    ```bash theme={null}
    nvm install 24
    nvm use 24
    ```

    Or download the latest LTS release from [nodejs.org](https://nodejs.org).
  </Accordion>

  <Accordion title="MCP server is slow to start">
    GitHits is normally started through `npx` so the MCP server uses the latest CLI. In an MCP config, use the explicit server command:

    ```json theme={null}
    {
      "mcpServers": {
        "githits": {
          "command": "npx",
          "args": ["-y", "githits@latest", "mcp", "start"]
        }
      }
    }
    ```

    If startup latency remains a problem, check whether your package manager or network is repeatedly downloading packages without cache reuse.
  </Accordion>

  <Accordion title="Search returns no results">
    If a search returns no results, the repository or package may not yet be indexed. Use `npx githits@latest search-status` to check indexing progress for a prior search, or run a new indexed search and follow up:

    ```bash theme={null}
    npx githits@latest search "your query"
    npx githits@latest search-status <searchRef>
    ```

    Indexing a new or recently updated repository typically takes around 10 seconds for an average-sized repo. If results are still missing after a short wait, try rephrasing your query or searching by a related package name.
  </Accordion>

  <Accordion title="Auth status shows unauthenticated despite logging in">
    If `npx githits@latest auth status` shows you as unauthenticated even though you have logged in, check the following:

    1. **API token conflict**: If `GITHITS_API_TOKEN` is set in your environment, GitHits uses it instead of stored OAuth credentials. Run `echo $GITHITS_API_TOKEN` to see if it is set, and verify the token is valid.

    2. **Stale credentials**: Run `npx githits@latest login --force` to re-authenticate and overwrite any stale credentials:

       ```bash theme={null}
       npx githits@latest login --force
       ```

    3. **Wrong storage mode**: If you previously used file storage and later switched back to keychain, credentials may be missing from the keychain. Re-run `npx githits@latest login` to store them in the current mode.

    After re-authenticating, verify with:

    ```bash theme={null}
    npx githits@latest auth status
    ```
  </Accordion>
</AccordionGroup>