githits

Code examples from global open source for developers and AI assistants.

GitHits gives your AI coding assistant access to verified, canonical code examples drawn from all of open source. When your assistant is stuck, needs an up-to-date API example, or encounters a vague error, GitHits helps it find a working solution in seconds.

Quick Start

npx githits init

init walks you through setup: choose the local MCP server or Agent Skills, detect your coding tools, sign in, and connect everything to GitHits.

Supported tools: Claude Code, Cursor, Windsurf, VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI, Google Antigravity, OpenCode, and Hermes Agent.

If you are using a tool that is not listed above, use the manual MCP setup instructions near the end of this README.

Plugin Installation (Open Plugin standard)

The npm package includes Open Plugin-compatible files:

• .plugin/plugin.json (vendor-neutral, used by Cursor/Codex/Copilot-compatible hosts)
• .claude-plugin/plugin.json (Claude Code compatibility)
• .claude-plugin/marketplace.json (Claude Code marketplace catalog)
• .mcp.json (Open Plugin MCP server config for plugin hosts)
• plugins/claude/ (Claude plugin runtime payload: .claude-plugin/plugin.json, .mcp.json, skills/, and commands/)

Root .claude-plugin/marketplace.json provides marketplace metadata. Claude Code loads the plugin runtime payload from plugins/claude/.

Claude Code Plugin (Marketplace)

Install from terminal (recommended):

claude plugin marketplace add githits-com/githits-cli
claude plugin install githits@githits-plugins

This is preferred over in-session install so the plugin is loaded cleanly on next claude launch.

Alternative (inside Claude input):

/plugin marketplace add githits-com/githits-cli
/plugin install githits@githits-plugins

If installed inside a running Claude session, reload/restart Claude if the plugin is not immediately available.

For unpublished/local testing of this repository:

claude plugin marketplace add "$PWD"
claude plugin install githits@githits-plugins

By default, the plugin starts MCP with npx -y githits@latest mcp start so installs track the latest published GitHits CLI.

For unpublished/local testing, install from your local repository path and verify behavior in your host before publishing.

In Claude Code, run /mcp and confirm plugin:githits:githits is listed for the plugin path.

Note: when running Claude in this repository directory, root .mcp.json can also register githits for project-level MCP. For plugin-only attribution during testing, run Claude from a different working directory.

Gemini CLI extension install

gemini extensions install https://github.com/githits-com/githits-cli

For plugin-based hosts, install from npm/GitHub using your agent's plugin workflow and enable plugin githits.

Agent Coverage

• Cursor: reads vendor-neutral .plugin/ for Open Plugin installs
• Claude Code: supports .claude-plugin/ and Open Plugin components
• Codex: supports Open Plugin components
• GitHub Copilot: supports Open Plugin components
• Gemini CLI: supports gemini-extension.json and GEMINI.md

That's it. Your assistant now has GitHits example-search tools and indexed dependency/package inspection tools.

How It Works

GitHits runs as an MCP server that your AI assistant connects to over stdio.

Core tools available in every authenticated session:

Tool	Purpose
get_example	Find canonical code examples by describing what you need in natural language
search_language	Look up supported programming language names
feedback	Submit result or session feedback to improve future quality

The assistant decides when to call these tools on its own — typically when it's stuck, needs a working example for an unfamiliar API, or encounters an error it can't resolve from its training data alone.

GitHits also exposes indexed package/source tools:

Tool	Purpose
search	Unified indexed search across dependency/repository code, docs, and symbols
search_status	Follow up a prior indexed search by searchRef
docs_list	Browse mixed package documentation pages
docs_read	Read a documentation page by page ID
pkg_info	Quick package triage: version, license, repository popularity, downloads, vulnerabilities
pkg_vulns	CVE / OSV advisories for a package or specific version, with filter echo and compact/verbose modes
pkg_deps	Direct dependencies, dependency groups, and optional transitive graph
pkg_changelog	Release notes / changelog entries for a package or GitHub repo, with compact timeline and body-preview controls
pkg_upgrade_review	Evidence for dependency upgrades, including vulnerabilities, changelog entries, deprecation metadata, peer changes, and dependency changes
code_files	Discover what files a dependency or repo contains
code_read	Read a dependency file by path
code_grep	Deterministic text grep across indexed dependency or repo files

License Filtering

Search results respect license filtering by default, excluding copyleft-licensed code. Three modes are available:

• strict (default) — excludes copyleft licenses
• yolo — includes all licenses, no filtering
• custom — uses your custom blocklist configured at githits.com

Authentication

GitHits requires authentication. There are two options:

Browser Login (recommended)

npx githits login

Opens your browser for secure OAuth authentication. Tokens are stored in the system keychain by default and refreshed automatically on next use. If a refresh fails (for example, after an extended idle period), run githits login again.

Useful flags:

• --no-browser — prints a URL instead of opening a browser (for SSH sessions, CI, or headless environments)
• --force — re-authenticate even if already logged in
• --port <port> — use a specific port for the local callback server

API Token

For CI or environments where browser login isn't practical, set an environment variable:

export GITHITS_API_TOKEN=ghi-your-token-here

Keychain Prompts and File Storage

GitHits uses the system keychain by default because OAuth credentials include a refresh token. On macOS this means Keychain Access; on Windows it means Credential Manager; on Linux it means the available Secret Service or keyring backend.

If macOS shows a prompt such as "githits wants to access ... in your keychain", choose Always Allow when you trust the installed githits CLI. GitHits cannot customize that operating-system prompt with extra explanation; it is generated by macOS.

GitHits also writes a small non-secret metadata file so recent startup checks do not need to read the keychain. The keychain is only read when GitHits actually needs the token, for example during a tool call, token refresh, githits auth status, or a login check after metadata is stale or expired.

If your agent keeps showing keychain prompts even after Always Allow, switch OAuth storage to file mode:

# macOS/Linux: ~/.config/githits/config.toml, or $XDG_CONFIG_HOME/githits/config.toml
# Windows: %APPDATA%\githits\config.toml
[auth]
storage = "file"

The config directory may be empty until you create config.toml or GitHits writes auth metadata. Older macOS installs may have used ~/Library/Application Support/githits; GitHits still reads that location for migration, but new auth config and file storage use ~/.config/githits.

You can also opt in for one process:

GITHITS_AUTH_STORAGE=file githits login --force

File mode stores OAuth credentials as JSON files under the GitHits config directory. The files are written with private permissions where the platform supports it, but they are not encrypted. Any process that can read files as your operating-system user may be able to read the tokens.

Use file mode only on machines where you trust local user-account access. For CI and automation, prefer GITHITS_API_TOKEN instead of browser OAuth.

To inspect the current auth setup, run:

githits auth status

Commands

githits init             Authenticate and configure your coding tools with GitHits MCP
githits init uninstall   Remove GitHits MCP configuration from your coding tools
githits login            Authenticate with your GitHits account (also runs as part of init)
githits logout           Remove stored credentials
githits mcp              Show setup instructions in a terminal; starts MCP server when piped
githits mcp start        Always start MCP server (for use in MCP config files)
githits auth status      Show current authentication status
githits example          Get canonical code examples from global open source
githits languages        List or filter supported language names
githits feedback         Send feedback on a result, command, or session

These indexed package/source commands are also available:

githits search ...     Unified indexed dependency/repository search
githits search-status  Follow up a prior indexed search
githits pkg ...        Package metadata: overview, advisories, deps, changelog, upgrade reviews
githits docs ...       Package documentation: browse pages and read content
githits code ...       Dependency source inspection: search, files, read, grep

Environment Variables

Variable	Purpose	Default
GITHITS_API_TOKEN	API token for authentication	—
GITHITS_AUTH_STORAGE	Override OAuth storage mode (keychain or file)	keychain
GITHITS_MCP_URL	Override MCP server URL	https://mcp.githits.com
GITHITS_API_URL	Override REST API URL	https://api.githits.com
GITHITS_CODE_NAV_URL	Override package/source service URL	https://pkgseer.dev
GITHITS_TELEMETRY	Emit end-of-run timing spans to stderr for local profiling	—
GITHITS_DISABLE_UPDATE_CHECK	Disable npm latest-version update notices	—

Manual Setup

If your tool is not in the supported githits init list, configure GitHits manually.

The same MCP server command exposes both the core example-search tools and the indexed package/source inspection tools. No separate install is required.

Use this MCP server command in your tool's MCP config (the host/agent runs this command):

npx -y githits@latest mcp start

A typical MCP config looks like this (check your tool's docs for exact schema/key names):

{
  "mcpServers": {
    "githits": {
      "command": "npx",
      "args": ["-y", "githits@latest", "mcp", "start"]
    }
  }
}

If you'd like another tool to be included in githits init for auto-configuration, open an issue or PR.

To undo automatic setup, run githits init uninstall. It removes only GitHits MCP/plugin configuration and preserves stored credentials; use githits logout separately to remove credentials.

Development

bun run build
npm link
githits --version

After the initial npm link, only bun run build is needed for subsequent changes.

Requirements

• Node.js 20.12+, 22.13+, or later

License

Apache-2.0