githits 0.5.4 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "GitHits plugins for Claude Code - code examples from global open source",
-    "version": "0.5.4"
+    "version": "0.6.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

package/.plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

package/README.md

@@ -1,273 +1,345 @@
-# 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.
+<p align="center">
+  <img src="./github-githits.png" alt="GitHits" width="100%" />
+</p>
+
+<h1 align="center">GitHits CLI</h1>
+
+<p align="center">
+  Version-aware open-source context for agentic software development.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/githits"><img alt="npm version" src="https://img.shields.io/npm/v/githits.svg"></a>
+  <a href="https://www.npmjs.com/package/githits"><img alt="npm downloads" src="https://img.shields.io/npm/dm/githits.svg"></a>
+  <a href="https://github.com/githits-com/githits-cli/actions/workflows/main.yml"><img alt="Main" src="https://github.com/githits-com/githits-cli/actions/workflows/main.yml/badge.svg"></a>
+  <a href="https://github.com/githits-com/githits-cli/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
+  <a href="https://www.npmjs.com/package/githits"><img alt="Node" src="https://img.shields.io/node/v/githits.svg"></a>
+  <a href="https://modelcontextprotocol.io/"><img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-5C4EE5"></a>
+  <a href="https://skills.sh/githits-com/githits-cli"><img alt="skills.sh" src="https://skills.sh/b/githits-com/githits-cli"></a>
+</p>
+
+<p align="center">
+  <a href="https://githits.com">Website</a> ·
+  <a href="https://docs.githits.com">Documentation</a> ·
+  <a href="https://github.com/githits-com/githits-cli/issues">Issues</a>
+</p>
+
+GitHits connects AI coding agents to public open-source evidence across the
+full software development lifecycle: discovery, planning, research,
+implementation, debugging, and maintenance.
+
+The CLI runs a local [MCP](https://modelcontextprotocol.io/) server that your
+coding tool starts on demand. Agents can then search indexed package and
+repository source, read exact files and documentation pages, inspect package
+health, compare dependency upgrades, and find source-cited examples from real
+open-source projects when model knowledge and local repository context are not
+enough.
 
 ## Quick Start
 
 ```sh
-npx githits init
+npx githits@latest 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.
+`init` signs you in, detects supported coding tools, and configures the local
+GitHits MCP server for the tools you select.
 
-If you are using a tool that is not listed above, use the manual MCP setup instructions near the end of this README.
+Automatic setup currently supports Claude Code, Cursor, Windsurf,
+VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI,
+Google Antigravity, OpenCode, Hermes Agent, Zed, Junie, Qwen Code,
+Kiro, Kilo Code, Factory Droid, and Amazon Q CLI.
 
-### Plugin Installation (Open Plugin standard)
+After setup, open your coding agent and work normally. Many agents call GitHits
+when they need source-backed context. If your agent starts guessing, prompt it
+directly:
 
-The npm package includes Open Plugin-compatible files:
+```text
+Use GitHits Code Navigation to inspect npm:express. Find how middleware
+errors are handled, read the relevant source, and explain the fix before
+editing code.
+```
 
-- `.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/`)
+## What GitHits Adds
 
-Root `.claude-plugin/marketplace.json` provides marketplace metadata. Claude Code
-loads the plugin runtime payload from `plugins/claude/`.
+GitHits is designed for the point where an agent needs evidence from the
+broader open-source ecosystem, not just model memory or local repo context:
 
-**Claude Code Plugin (Marketplace)**
+| Capability | MCP tools | CLI commands |
+|---|---|---|
+| Code examples | `get_example`, `search_language` | `githits example`, `githits languages` |
+| Code navigation | `search`, `search_status`, `code_files`, `code_read`, `code_grep` | `githits search`, `githits search-status`, `githits code ...` |
+| Documentation access | `docs_list`, `docs_read` | `githits docs ...` |
+| Package inspection | `pkg_info`, `pkg_vulns`, `pkg_deps`, `pkg_changelog`, `pkg_upgrade_review` | `githits pkg ...` |
+| Feedback | `feedback` | `githits feedback` |
 
-Install from terminal (recommended):
+Use GitHits when your agent needs to:
 
-```sh
-claude plugin marketplace add githits-com/githits-cli
-claude plugin install githits@githits-plugins
-```
+- discover, plan, or research how OSS projects solve a vague issue or unfamiliar error
+- find broad prior art or rare needle-in-the-haystack examples across repositories
+- inspect source, tests, symbols, or docs for a known package or repository
+- verify how a dependency actually behaves before changing code
+- debug stack traces that point into third-party code
+- review package health, licenses, vulnerabilities, dependencies, and changelogs
+- compare dependency upgrades using factual evidence
 
-This is preferred over in-session install so the plugin is loaded cleanly on
-next `claude` launch.
+## Examples
 
-Alternative (inside Claude input):
+Find prior art across open source:
 
 ```sh
-/plugin marketplace add githits-com/githits-cli
-/plugin install githits@githits-plugins
+npx githits@latest example "HTTP retries with exponential backoff in Python"
 ```
 
-If installed inside a running Claude session, reload/restart Claude if the
-plugin is not immediately available.
-
-For unpublished/local testing of this repository:
+Search indexed code, docs, and symbols for a dependency:
 
 ```sh
-claude plugin marketplace add "$PWD"
-claude plugin install githits@githits-plugins
+npx githits@latest search "router middleware" --in npm:express
+npx githits@latest search '"body parser" OR multer' --in npm:express --source docs
+npx githits@latest search "debounce" --in npm:lodash --source symbol
 ```
 
-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**
+Read and grep dependency source without cloning:
 
 ```sh
-gemini extensions install https://github.com/githits-com/githits-cli
+npx githits@latest code files npm:express lib
+npx githits@latest code read npm:express lib/router/index.js --lines 120-200
+npx githits@latest code grep npm:express "router.use" lib --regex
 ```
 
-For plugin-based hosts, install from npm/GitHub using your agent's plugin workflow and enable plugin `githits`.
-
-### Agent Coverage
+Inspect package health and upgrade evidence:
 
-- **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.
+```sh
+npx githits@latest pkg info npm:express
+npx githits@latest pkg vulns npm:lodash@4.17.20 --severity high
+npx githits@latest pkg deps npm:express@4.18.2 --depth 2
+npx githits@latest pkg changelog npm:express --from 4.18.2 --to 5.2.1
+npx githits@latest pkg upgrade-review npm:zod@4.3.6 --to 4.4.3
+```
 
-## How It Works
+Browse and read package documentation:
 
-GitHits runs as an [MCP server](https://modelcontextprotocol.io/) that your AI assistant connects to over stdio.
+```sh
+npx githits@latest docs list npm:express
+npx githits@latest docs read <page-id> --lines 20-80
+```
 
-Core tools available in every authenticated session:
+## Supported Sources
 
-| 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 |
+GitHits works with package and repository targets such as:
 
-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.
+- package specs: `npm:react`, `npm:react@18.2.0`, `pypi:requests`, `crates:serde`
+- GitHub repos: `https://github.com/expressjs/express`, `github:expressjs/express#main`
 
-GitHits also exposes indexed package/source tools:
+Package inspection supports npm, PyPI, Hex, Crates, NuGet, Maven, Packagist,
+RubyGems, Go, Swift, vcpkg, and Zig. Advisory data is unavailable for vcpkg and
+Zig; dependency graph support varies by registry.
 
-| 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
 
-### License Filtering
+Code example search supports license filtering:
 
-Search results respect license filtering by default, excluding copyleft-licensed code. Three modes are available:
+- `strict` is the default and filters repositories with copyleft or undeclared licenses
+- `custom` uses your account blocklist configured at [githits.com](https://githits.com)
+- `yolo` disables license filtering
 
-- **strict** (default) — excludes copyleft licenses
-- **yolo** — includes all licenses, no filtering
-- **custom** — uses your custom blocklist configured at [githits.com](https://githits.com)
+```sh
+npx githits@latest example "async file reading" --lang python --license strict
+```
 
 ## Authentication
 
-GitHits requires authentication. There are two options:
-
-### Browser Login (recommended)
+Normal local setup is handled by:
 
 ```sh
-npx githits login
+npx githits@latest init
 ```
 
-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.
+For manual login:
 
-Useful flags:
+```sh
+npx githits@latest login
+```
 
-- `--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
+Browser OAuth is recommended for local development. Credentials are stored in
+the system keychain by default and refreshed automatically. Useful flags:
 
-### API Token
+- `--no-browser` prints a login URL for SSH, containers, or headless sessions
+- `--force` re-authenticates even if you are already logged in
+- `--port <port>` uses a specific local callback port
 
-For CI or environments where browser login isn't practical, set an environment variable:
+For CI or non-interactive environments, use an API token:
 
 ```sh
 export GITHITS_API_TOKEN=ghi-your-token-here
 ```
 
-### Keychain Prompts and File Storage
+Inspect auth and runtime state with:
 
-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.
+```sh
+npx githits@latest auth status
+npx githits@latest doctor
+```
 
-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.
+See the [authentication docs](https://docs.githits.com/authentication) for
+keychain behavior, file storage mode, CI setup, and troubleshooting.
 
-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.
+## Manual MCP Setup
 
-If your agent keeps showing keychain prompts even after **Always Allow**, switch OAuth storage to file mode:
+If your coding tool is not auto-configured by `init`, add GitHits to its MCP
+configuration manually:
 
-```toml
-# macOS/Linux: ~/.config/githits/config.toml, or $XDG_CONFIG_HOME/githits/config.toml
-# Windows: %APPDATA%\githits\config.toml
-[auth]
-storage = "file"
+```json
+{
+  "mcpServers": {
+    "githits": {
+      "command": "npx",
+      "args": ["-y", "githits@latest", "mcp", "start"]
+    }
+  }
+}
 ```
 
-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`.
+Your tool runs this command over stdio. No background daemon or global install
+is required.
 
-You can also opt in for one process:
+To remove configuration written by `init`:
 
 ```sh
-GITHITS_AUTH_STORAGE=file githits login --force
+npx githits@latest init uninstall
 ```
 
-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.
+This removes GitHits MCP configuration and preserves stored credentials. Run
+`npx githits@latest logout` separately to remove credentials.
 
-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.
+## Project Setup
 
-To inspect the current auth setup, run:
+For project-local MCP config, run:
 
 ```sh
-githits auth status
+npx githits@latest init --project
 ```
 
-For redacted environment/configuration diagnostics when GitHits behaves
-differently across terminals or agents, run `githits doctor` or
-`githits doctor --json`.
+Project setup is available only for tools with verified project-local MCP
+support. Project config contains no secrets, but it may be committed like other
+tooling configuration, so review generated files before adding them to source
+control.
 
-## Commands
+Agent-safe non-interactive setup uses staged discovery and explicit install:
 
+```sh
+npx githits@latest init --detect-agents --json
+npx githits@latest init --install-agents cursor,codex
 ```
-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 doctor           Print redacted diagnostics for config/auth troubleshooting
-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
+
+## Plugin and Extension Packaging
+
+The npm package also includes the existing plugin and extension assets used by
+compatible hosts:
+
+- `.plugin/plugin.json`
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `.mcp.json`
+- `gemini-extension.json`
+- `GEMINI.md`
+- `plugins/claude/`
+- `skills/`
+- `commands/`
+
+For Claude Code marketplace installs:
+
+```sh
+claude plugin marketplace add githits-com/githits-cli
+claude plugin install githits@githits-plugins
 ```
 
-These indexed package/source commands are also available:
+For Gemini CLI extension installs:
 
+```sh
+gemini extensions install https://github.com/githits-com/githits-cli
 ```
-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
+
+## Command Reference
+
+```text
+githits init             Connect GitHits to your coding agents
+githits init uninstall   Remove GitHits MCP configuration
+githits login            Sign in to your GitHits account
+githits logout           Remove stored credentials
+githits mcp              Show setup instructions or start the local MCP server
+githits mcp start        Always start the local MCP server over stdio
+githits example          Find real-world implementations from open source
+githits languages        List or filter supported programming languages
+githits feedback         Submit feedback about GitHits results
+githits doctor           Diagnose configuration and auth state
+githits search           Explore repository code, dependencies, docs, and symbols
+githits search-status    Check the status of a previous indexed search
+githits code             List, read, and grep indexed dependency source
+githits pkg              Inspect package metadata, vulnerabilities, deps, and changelogs
+githits docs             Browse and read package documentation
+githits auth             Manage authentication
+githits auth status      Show authentication status
 ```
 
+Full CLI reference: https://docs.githits.com/cli/commands
+
 ## Environment Variables
 
+Most users do not need environment variables. These are the common overrides for
+CI, auth storage, and local diagnostics:
+
 | 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.
+| `GITHITS_API_TOKEN` | API token for authentication | unset |
+| `GITHITS_AUTH_STORAGE` | Override OAuth storage mode: `keychain` or `file` | `keychain` |
+| `GITHITS_DISABLE_UPDATE_CHECK` | Disable npm latest-version update notices | unset |
+| `GITHITS_TELEMETRY` | Emit local timing diagnostics to stderr | unset |
 
-The same MCP server command exposes both the core example-search tools and the indexed package/source inspection tools. No separate install is required.
+Full reference: https://docs.githits.com/cli/environment-variables
 
-Use this MCP server command in your tool's MCP config (the host/agent runs this command):
+## Source Layout
 
-```sh
-npx -y githits@latest mcp start
-```
+This repository contains the GitHits CLI and reusable MCP package:
 
-A typical MCP config looks like this (check your tool's docs for exact schema/key names):
+- `src/` - CLI commands, local auth, setup flows, and local MCP stdio startup
+- `packages/mcp/` - public `@githits/mcp` package for transport-neutral MCP
+  server APIs, tool registration, instructions, and smoke-test helpers
+- `packages/core-internal/` - shared workspace implementation used by the CLI
+  and MCP package
+- `docs/` - implementation notes and contributor guidelines
+- `scripts/` - package validation, smoke tests, and development utilities
 
-```json
-{
-  "mcpServers": {
-    "githits": {
-      "command": "npx",
-      "args": ["-y", "githits@latest", "mcp", "start"]
-    }
-  }
-}
-```
+## Development
 
-If you'd like another tool to be included in `githits init` for auto-configuration, open an issue or PR.
+Requirements:
 
-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.
+- Node.js `^20.12.0 || >=22.13.0`
+- Bun
 
-## Development
+Common commands:
 
 ```sh
+bun install
+bun run dev --help
+bun test
+bun run typecheck
 bun run build
-npm link
-githits --version
 ```
 
-After the initial `npm link`, only `bun run build` is needed for subsequent changes.
+When changing MCP tools, CLI commands, shared formatters, auth/error envelopes,
+or MCP/CLI parity behavior, also run the relevant smoke suites:
 
-## Requirements
+```sh
+bun run smoke:mcp
+bun run smoke:cli
+```
+
+When changing MCP instructions, tool descriptions, or agent-facing behavior,
+use the targeted agent evals described in `eval/agentic/README.md`:
 
-- Node.js 20.12+, 22.13+, or later
+```sh
+bun run agent:e2e
+```
 
 ## License