Skip to main content
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:
Or switch for a single session:
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:
If you are in a headless environment, use:
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:
  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:
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 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:
Check your client’s documentation for the exact config file location and schema. See Manual remote MCP 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 to request it.
GitHits requires Node.js 20 or later. Check your current version:
If you are on an older version, upgrade using nvm:
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:
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:
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:
  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: