Skip to main content

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.

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.
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:
# ~/.config/githits/config.toml
[auth]
storage = "file"
Or switch for a single session:
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.
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:
npx githits@latest login
If you are in a headless environment, use:
npx githits@latest login --no-browser
This prints a URL you can open on another device to complete login.
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: 
    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: 
    npx githits@latest auth status
If GitHits is listed but the agent is not calling its tools, prompt it directly. See Trigger GitHits manually for copy-paste prompt patterns.
npx githits@latest init supports a fixed list of tools. If your tool is not on the list, configure GitHits manually by adding the following MCP server entry to your tool’s config:
{
  "mcpServers": {
    "githits": {
      "command": "npx",
      "args": ["-y", "githits@latest", "mcp", "start"]
    }
  }
}
Check your tool’s documentation for the exact config file location and schema. See the manual setup guide for a full walkthrough.If you would like your tool to be supported by npx githits@latest init auto-detection, open a GitHub issue to request it.
GitHits requires Node.js 24 or later. Check your current version:
node --version
If you are on an older version, upgrade using nvm:
nvm install 24
nvm use 24
Or download the latest LTS release from nodejs.org.
GitHits is normally started through npx so the MCP server uses the latest CLI. In an MCP config, use the explicit server command:
{
  "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.
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:
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.
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: 
    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:
npx githits@latest auth status