githits 0.1.7 → 0.1.8

package/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "githits-plugins",
+  "owner": {
+    "name": "GitHits",
+    "email": "support@githits.com"
+  },
+  "metadata": {
+    "description": "GitHits plugins for Claude Code - code examples from global open source",
+    "version": "0.1.8"
+  },
+  "plugins": [
+    {
+      "name": "githits",
+      "source": "./plugins/claude",
+      "description": "Code examples from global open source for developers and AI assistants",
+      "author": {
+        "name": "GitHits"
+      },
+      "homepage": "https://githits.com",
+      "repository": "https://github.com/githits-com/githits-cli",
+      "license": "Apache-2.0",
+      "keywords": ["code-search", "open-source", "examples"],
+      "category": "developer-tools"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "githits",
+  "version": "0.1.8",
+  "description": "Code examples from global open source for developers and AI assistants",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+}

package/.mcp.json

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

package/.plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "githits",
+  "version": "0.1.8",
+  "description": "Code examples from global open source for developers and AI assistants",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+}

package/GEMINI.md

@@ -0,0 +1,75 @@
+# GitHits
+
+Code examples from global open source for developers and AI assistants.
+
+## Available Tools
+
+### search
+
+Find code examples from open source repositories.
+
+**Parameters:**
+
+- `query` (string, required) - natural language description of what you need
+- `language` (string, required) - programming language name (use `search_language` to verify)
+- `license_mode` (string, optional) - one of `strict` (default), `yolo`, or `custom`
+
+### search_language
+
+Look up supported programming language names. Use this before calling `search` to get the correct language identifier.
+
+**Parameters:**
+
+- `query` (string, required) - partial or full language name to look up
+
+### feedback
+
+Rate a search result. Submit feedback after each search to improve future result quality.
+
+**Parameters:**
+
+- `solution_id` (string, required) - the ID of the search result
+- `accepted` (boolean, required) - whether the result was useful
+- `feedback_text` (string, optional) - additional context about why the result was or was not helpful
+
+## When to Use
+
+Use `search` when:
+
+- You are stuck or blocked on an implementation problem
+- You need up-to-date examples for an API, library, or framework
+- The user mentions GitHits or asks you to search for code examples
+- You encounter an error you cannot resolve from your training data
+
+Do not use `search` for:
+
+- General knowledge questions that do not require code examples
+- Problems you can already solve confidently
+
+## Authentication
+
+- If any GitHits tool returns an authentication error, immediately run
+  `npx -y githits login` in the terminal. This opens the user's browser for
+  quick OAuth approval. Wait for the command to complete, then retry the
+  original tool call.
+- If the environment has no display (SSH, containers), use
+  `npx -y githits login --no-browser` instead, which prints a URL for the
+  user to open on another device.
+- Do NOT ask the user to run login manually - handle it automatically.
+- If login fails, inform the user of the error.
+
+## How to Search Well
+
+- Call `search_language` first to confirm the correct language name before calling `search`
+- Formulate queries as natural language questions (e.g., "How to stream responses with the Vercel AI SDK in Next.js")
+- Include specific error messages, library names, or API names when relevant
+- Keep queries focused: 3-4 technical terms maximum
+- Submit `feedback` after every search result you use or discard
+
+## License Filtering
+
+Results respect license filtering by default. Three modes:
+
+- **strict** (default) - excludes copyleft licenses
+- **yolo** - includes all licenses
+- **custom** - uses the user's blocklist configured at githits.com

package/README.md

@@ -14,6 +14,74 @@ npx githits init
 
 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):
+
+```sh
+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):
+
+```sh
+/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:
+
+```sh
+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**
+
+```sh
+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
@@ -81,6 +149,31 @@ githits auth status    Show current authentication status
 | `GITHITS_MCP_URL` | Override MCP server URL | `https://mcp.githits.com` |
 | `GITHITS_API_URL` | Override REST API URL | `https://api.githits.com` |
 
+## Manual Setup
+
+If your tool is not in the supported `githits init` list, configure GitHits manually.
+
+Use this MCP server command in your tool's MCP config (the host/agent runs this command):
+
+```sh
+npx -y githits@latest mcp start
+```
+
+A typical MCP config looks like this (check your tool's docs for exact schema/key names):
+
+```json
+{
+  "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.
+
 ## Development
 
 ```sh

package/commands/help.md

@@ -0,0 +1,46 @@
+---
+description: Show available GitHits commands and usage
+disable-model-invocation: true
+---
+
+# GitHits Help
+
+Run the GitHits CLI help command in the terminal:
+
+```
+npx -y githits help
+```
+
+Then display the command output clearly to the user, followed by this plugin
+context summary:
+
+## Slash Commands
+
+- `/githits:search <query>` — Search for code examples from open source.
+- `/githits:login` — Authenticate with your GitHits account.
+- `/githits:status` — Show your current authentication status.
+- `/githits:logout` — Remove stored credentials.
+- `/githits:help` — Show this help message.
+
+## MCP Tools
+
+This plugin connects to the GitHits MCP server and exposes three tools:
+
+- **search** — Find code examples by describing what you need in natural
+  language. Requires `query` and `language` parameters.
+- **search_language** — Look up supported programming language names before
+  searching.
+- **feedback** — Rate a search result to improve future quality.
+
+## Authentication
+
+Run `npx -y githits login` to authenticate via browser, or set the
+`GITHITS_API_TOKEN` environment variable for headless environments.
+
+If users want to verify MCP tools loaded, suggest `/mcp`.
+
+If the command fails, report the error and suggest running:
+
+```
+npx -y githits login
+```

package/commands/login.md

@@ -0,0 +1,36 @@
+---
+description: Log in to your GitHits account
+---
+
+# Login
+
+Authenticate the user with GitHits by running the CLI login command in the
+terminal:
+
+```
+npx -y githits login
+```
+
+This opens the user's browser for secure OAuth authentication. Tokens are stored
+locally and refreshed automatically.
+
+If the environment has no display (SSH, CI, containers), use the `--no-browser`
+flag instead:
+
+```
+npx -y githits login --no-browser
+```
+
+This prints a URL the user can open on another device.
+
+Other useful flags:
+
+- `--force` — re-authenticate even if already logged in.
+- `--port <port>` — use a specific port for the local callback server.
+
+After running the command, inform the user of the result. If login succeeds,
+confirm they are authenticated. If it fails, provide the error and suggest they
+try again.
+
+Alternative: the user can set the `GITHITS_API_TOKEN` environment variable
+instead of using browser login.

package/commands/logout.md

@@ -0,0 +1,16 @@
+---
+description: Log out of your GitHits account
+---
+
+# Logout
+
+Sign the user out of GitHits by running the CLI logout command in the terminal:
+
+```
+npx -y githits logout
+```
+
+This removes the locally stored authentication tokens.
+
+Confirm to the user that they have been logged out successfully. If the logout
+fails, provide the error details.

package/commands/search.md

@@ -0,0 +1,23 @@
+---
+description: Search for code examples from open source via GitHits
+---
+
+# Search
+
+Search for code examples using GitHits for the query: "$ARGUMENTS"
+
+Use the GitHits MCP `search` tool with the user's query. The tool requires two
+parameters:
+
+- **query**: The user's search query, formulated in natural language.
+- **language**: The programming language. If the language is unclear from
+  context, use the `search_language` tool first to find the correct language
+  name.
+
+Optional parameter:
+
+- **license_mode**: `"strict"` (default, excludes copyleft), `"yolo"` (all
+  licenses), or `"custom"` (user's blocklist).
+
+Present the results clearly. After the user has reviewed the result, use the
+`feedback` tool to report whether the example was helpful.

package/commands/status.md

@@ -0,0 +1,22 @@
+---
+description: Show your GitHits authentication status
+---
+
+# Status
+
+Check the user's current GitHits authentication status by running the CLI
+command in the terminal:
+
+```
+npx -y githits auth status
+```
+
+This shows whether the user is authenticated, where credentials are sourced
+from, and token expiry details when available.
+
+After running the command, report the status clearly. If the user is not
+authenticated, suggest running:
+
+```
+npx -y githits login
+```

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-hg653b0a.js";
+} from "./shared/chunk-6w8an8m7.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -1534,12 +1534,7 @@ var claudeCode = {
     commands: [
       {
         command: "claude",
-        args: [
-          "plugin",
-          "marketplace",
-          "add",
-          "githits-com/githits-claude-code-plugin"
-        ]
+        args: ["plugin", "marketplace", "add", "githits-com/githits-cli"]
       },
       {
         command: "claude",
@@ -1692,7 +1687,7 @@ var geminiCli = {
         args: [
           "extensions",
           "install",
-          "https://github.com/githits-com/githits-gemini-cli"
+          "https://github.com/githits-com/githits-cli"
         ]
       }
     ],

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-hg653b0a.js";
+} from "./shared/chunk-6w8an8m7.js";
 export {
   version
 };

package/dist/shared/{chunk-hg653b0a.js → chunk-6w8an8m7.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.1.7";
+var version = "0.1.8";
 
 export { version };

package/gemini-extension.json

@@ -0,0 +1,12 @@
+{
+  "name": "githits",
+  "version": "0.1.8",
+  "description": "Code examples from global open source for developers and AI assistants.",
+  "mcpServers": {
+    "githits": {
+      "command": "npx",
+      "args": ["-y", "githits@latest", "mcp", "start"]
+    }
+  },
+  "contextFileName": "GEMINI.md"
+}

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "githits",
   "description": "CLI companion for GitHits - code examples from global open source for developers and AI assistants",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".plugin",
+    ".claude-plugin",
+    ".mcp.json",
+    "gemini-extension.json",
+    "GEMINI.md",
+    "plugins",
+    "skills",
+    "commands"
   ],
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/plugins/claude/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "githits",
+  "version": "0.1.8",
+  "description": "Code examples from global open source for developers and AI assistants",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+}

package/plugins/claude/.mcp.json

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

package/plugins/claude/commands/help.md

@@ -0,0 +1,46 @@
+---
+description: Show available GitHits commands and usage
+disable-model-invocation: true
+---
+
+# GitHits Help
+
+Run the GitHits CLI help command in the terminal:
+
+```
+npx -y githits help
+```
+
+Then display the command output clearly to the user, followed by this plugin
+context summary:
+
+## Slash Commands
+
+- `/githits:search <query>` — Search for code examples from open source.
+- `/githits:login` — Authenticate with your GitHits account.
+- `/githits:status` — Show your current authentication status.
+- `/githits:logout` — Remove stored credentials.
+- `/githits:help` — Show this help message.
+
+## MCP Tools
+
+This plugin connects to the GitHits MCP server and exposes three tools:
+
+- **search** — Find code examples by describing what you need in natural
+  language. Requires `query` and `language` parameters.
+- **search_language** — Look up supported programming language names before
+  searching.
+- **feedback** — Rate a search result to improve future quality.
+
+## Authentication
+
+Run `npx -y githits login` to authenticate via browser, or set the
+`GITHITS_API_TOKEN` environment variable for headless environments.
+
+If users want to verify MCP tools loaded, suggest `/mcp`.
+
+If the command fails, report the error and suggest running:
+
+```
+npx -y githits login
+```

package/plugins/claude/commands/login.md

@@ -0,0 +1,36 @@
+---
+description: Log in to your GitHits account
+---
+
+# Login
+
+Authenticate the user with GitHits by running the CLI login command in the
+terminal:
+
+```
+npx -y githits login
+```
+
+This opens the user's browser for secure OAuth authentication. Tokens are stored
+locally and refreshed automatically.
+
+If the environment has no display (SSH, CI, containers), use the `--no-browser`
+flag instead:
+
+```
+npx -y githits login --no-browser
+```
+
+This prints a URL the user can open on another device.
+
+Other useful flags:
+
+- `--force` — re-authenticate even if already logged in.
+- `--port <port>` — use a specific port for the local callback server.
+
+After running the command, inform the user of the result. If login succeeds,
+confirm they are authenticated. If it fails, provide the error and suggest they
+try again.
+
+Alternative: the user can set the `GITHITS_API_TOKEN` environment variable
+instead of using browser login.

package/plugins/claude/commands/logout.md

@@ -0,0 +1,16 @@
+---
+description: Log out of your GitHits account
+---
+
+# Logout
+
+Sign the user out of GitHits by running the CLI logout command in the terminal:
+
+```
+npx -y githits logout
+```
+
+This removes the locally stored authentication tokens.
+
+Confirm to the user that they have been logged out successfully. If the logout
+fails, provide the error details.

package/plugins/claude/commands/search.md

@@ -0,0 +1,23 @@
+---
+description: Search for code examples from open source via GitHits
+---
+
+# Search
+
+Search for code examples using GitHits for the query: "$ARGUMENTS"
+
+Use the GitHits MCP `search` tool with the user's query. The tool requires two
+parameters:
+
+- **query**: The user's search query, formulated in natural language.
+- **language**: The programming language. If the language is unclear from
+  context, use the `search_language` tool first to find the correct language
+  name.
+
+Optional parameter:
+
+- **license_mode**: `"strict"` (default, excludes copyleft), `"yolo"` (all
+  licenses), or `"custom"` (user's blocklist).
+
+Present the results clearly. After the user has reviewed the result, use the
+`feedback` tool to report whether the example was helpful.

package/plugins/claude/commands/status.md

@@ -0,0 +1,22 @@
+---
+description: Show your GitHits authentication status
+---
+
+# Status
+
+Check the user's current GitHits authentication status by running the CLI
+command in the terminal:
+
+```
+npx -y githits auth status
+```
+
+This shows whether the user is authenticated, where credentials are sourced
+from, and token expiry details when available.
+
+After running the command, report the status clearly. If the user is not
+authenticated, suggest running:
+
+```
+npx -y githits login
+```

package/plugins/claude/skills/search/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: search
+description:
+  Use GitHits MCP tools to find real-world code examples when model knowledge
+  is insufficient.
+---
+
+Use GitHits when:
+
+- You are blocked, uncertain about an API, or need up-to-date OSS usage.
+- You have attempted a solution twice and it still fails - search for a working example before trying again.
+- The user asks to search for examples or explicitly mentions GitHits.
+- You are implementing non-trivial code in languages where confidence is lower.
+
+Authentication:
+
+- If any GitHits tool returns an authentication error, immediately run
+  `npx -y githits login` in the terminal. This opens the user's browser for
+  quick OAuth approval. Wait for the command to complete, then retry the
+  original tool call.
+- If the environment has no display (SSH, containers), use
+  `npx -y githits login --no-browser` instead, which prints a URL for the
+  user to open on another device.
+- Do NOT ask the user to run login manually -- handle it automatically.
+- If login fails, inform the user of the error and suggest they set the
+  `GITHITS_API_TOKEN` environment variable as an alternative.
+
+Guidelines:
+
+- Prefer existing search context if it already answers the problem.
+- Use `search_language` first when language naming is uncertain.
+- Use `search` for one focused question at a time.
+- After using results, send `feedback` with helpful/unhelpful outcome.
+
+Tool argument details and rich query guidance are provided directly in the MCP
+tool descriptions; follow those descriptions as the source of truth.

package/skills/search/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: search
+description:
+  Use GitHits MCP tools to find real-world code examples when model knowledge
+  is insufficient.
+---
+
+Use GitHits when:
+
+- You are blocked, uncertain about an API, or need up-to-date OSS usage.
+- You have attempted a solution twice and it still fails - search for a working example before trying again.
+- The user asks to search for examples or explicitly mentions GitHits.
+- You are implementing non-trivial code in languages where confidence is lower.
+
+Authentication:
+
+- If any GitHits tool returns an authentication error, immediately run
+  `npx -y githits login` in the terminal. This opens the user's browser for
+  quick OAuth approval. Wait for the command to complete, then retry the
+  original tool call.
+- If the environment has no display (SSH, containers), use
+  `npx -y githits login --no-browser` instead, which prints a URL for the
+  user to open on another device.
+- Do NOT ask the user to run login manually -- handle it automatically.
+- If login fails, inform the user of the error and suggest they set the
+  `GITHITS_API_TOKEN` environment variable as an alternative.
+
+Guidelines:
+
+- Prefer existing search context if it already answers the problem.
+- Use `search_language` first when language naming is uncertain.
+- Use `search` for one focused question at a time.
+- After using results, send `feedback` with helpful/unhelpful outcome.
+
+Tool argument details and rich query guidance are provided directly in the MCP
+tool descriptions; follow those descriptions as the source of truth.