githits

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 authenticates with your GitHits account, then auto-detects your installed coding tools and configures each one with GitHits MCP.

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

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 a search tool it will use automatically when it needs code examples.

How It Works

GitHits runs as an MCP server that your AI assistant connects to over stdio. The assistant gets three tools:

Tool	Purpose
search	Find code examples by describing what you need in natural language
search_language	Look up supported programming language names
feedback	Rate search results 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.

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 locally and refreshed automatically on next use. If a refresh fails (e.g., 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