@gkoreli/ghx 2.0.0 → 2.1.5

package/README.md

@@ -17,18 +17,39 @@ ghx eliminates this by encoding the right defaults into every command. One call
 ## Install
 
 ```bash
-# Build from source
-cd v2 && go build -o ghx .
+# Zero install — just run it
+npx @gkoreli/ghx explore vercel/next.js
 
 # Homebrew
 brew install gkoreli/tap/ghx
 
-# One-liner
-curl -sfL https://raw.githubusercontent.com/gkoreli/ghx/mainline/install.sh | bash
+# npm (global)
+npm install -g @gkoreli/ghx
+
+# Go
+go install github.com/gkoreli/ghx/v2@latest
+
+# Build from source
+cd v2 && go build -o ghx .
 ```
 
 Requires: [gh CLI](https://cli.github.com/) authenticated (`gh auth login`).
 
+### MCP Config (Claude Desktop, Cursor)
+
+```json
+{
+  "mcpServers": {
+    "ghx": {
+      "command": "npx",
+      "args": ["@gkoreli/ghx", "serve"]
+    }
+  }
+}
+```
+
+No install step — npx downloads and caches the binary on first run.
+
 ## Commands
 
 ```bash

package/npm/bin/ghx

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+const { platform, arch } = process;
+
+const PLATFORMS = {
+  darwin:  { arm64: "@gkoreli/ghx-darwin-arm64/ghx", x64: "@gkoreli/ghx-darwin-x64/ghx" },
+  linux:   { arm64: "@gkoreli/ghx-linux-arm64/ghx",  x64: "@gkoreli/ghx-linux-x64/ghx" },
+  win32:   { arm64: "@gkoreli/ghx-win32-arm64/ghx.exe", x64: "@gkoreli/ghx-win32-x64/ghx.exe" },
+};
+
+const bin = PLATFORMS[platform]?.[arch];
+if (!bin) {
+  console.error(`ghx: unsupported platform ${platform}/${arch}`);
+  process.exitCode = 1;
+} else {
+  const result = require("child_process").spawnSync(
+    require.resolve(bin),
+    process.argv.slice(2),
+    { shell: false, stdio: "inherit" }
+  );
+  if (result.error) throw result.error;
+  process.exitCode = result.status;
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@gkoreli/ghx",
-  "version": "2.0.0",
-  "description": "GitHub code exploration for agents and humans. Batch file reads, code maps, search — all via gh CLI.",
+  "version": "2.1.5",
+  "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
   "bin": {
-    "ghx": "./v1/ghx"
+    "ghx": "npm/bin/ghx"
   },
   "keywords": [
     "github",
@@ -16,20 +16,22 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/gkoreli/ghx"
+    "url": "git+https://github.com/gkoreli/ghx.git"
   },
   "files": [
-    "v1/ghx",
-    "v1/SKILL.md",
+    "npm/bin/ghx",
     "README.md",
     "LICENSE"
   ],
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
   "engines": {
     "node": ">=16"
+  },
+  "optionalDependencies": {
+    "@gkoreli/ghx-darwin-arm64": "2.1.5",
+    "@gkoreli/ghx-darwin-x64": "2.1.5",
+    "@gkoreli/ghx-linux-arm64": "2.1.5",
+    "@gkoreli/ghx-linux-x64": "2.1.5",
+    "@gkoreli/ghx-win32-arm64": "2.1.5",
+    "@gkoreli/ghx-win32-x64": "2.1.5"
   }
 }

package/v1/README.md

@@ -1,74 +0,0 @@
-# ghx v1 — Bash Implementation
-
-> For the current Go version with codemode, MCP server, and typed stubs, see the [root README](../README.md).
-
-The bash implementation — zero dependencies beyond `gh` CLI. Useful if you want a single shell script you can drop anywhere without compiling Go.
-
-## Install
-
-```bash
-# npm
-npm install -g @gkoreli/ghx
-
-# npx (zero install)
-npx @gkoreli/ghx --help
-
-# curl
-curl -sf https://raw.githubusercontent.com/gkoreli/ghx/mainline/v1/install.sh | sh
-
-# manual
-cp v1/ghx /usr/local/bin/ghx
-```
-
-Requires [`gh` CLI](https://cli.github.com/) authenticated (`gh auth login`).
-
-### Platform Support
-
-| Platform | Status | Notes |
-|----------|--------|-------|
-| macOS | ✅ Native | bash + readlink -f (12.3+) |
-| Linux | ✅ Native | bash + GNU coreutils |
-| Windows | ✅ Git Bash / WSL | Ships with Git for Windows |
-
-## Usage
-
-```bash
-ghx repos "react state management"              # Search repos with README preview
-ghx explore plausible/analytics                  # Branch + tree + README in 1 API call
-ghx read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js  # Batch read
-ghx read plausible/analytics --map lib/plausible/stats/query.ex        # Code map (~92% reduction)
-ghx read plausible/analytics --grep "defmodule" lib/plausible/stats/query.ex
-ghx read plausible/analytics --lines 42-80 lib/plausible/stats/query.ex
-ghx search "useState repo:facebook/react"        # Code search with matching lines
-ghx tree plausible/analytics assets/js           # Full recursive tree
-```
-
-## Code Map (`--map`)
-
-Extracts only structural declarations — imports, exports, function signatures, class definitions, type declarations. Implementation bodies are stripped.
-
-| File | Full | Map | Reduction |
-|------|------|-----|-----------|
-| repomix/parseFile.ts | 5,599 | 812 | 86% |
-| github-mcp/repositories.go | 68,862 | 1,551 | 97.7% |
-| aider/repomap.py | 27,346 | 1,496 | 94.5% |
-
-Average: **92% reduction**. Map 16 files in the space of reading 1 file fully.
-
-Supported: TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin, Ruby. Generic fallback for unknown extensions.
-
-## How It Works
-
-Wraps `gh` CLI with GraphQL batching. `repos` and `explore` batch search + metadata + README into 1 call. `read` uses GraphQL aliases to fetch up to 10 files in 1 call. `search` hits REST `/search/code` with `text_matches` for matching context and 200-char token protection.
-
-## Agent Skill
-
-```bash
-ghx skill    # outputs SKILL.md to stdout
-```
-
-See [`SKILL.md`](./SKILL.md) for agent-optimized instructions.
-
-## License
-
-MIT

package/v1/SKILL.md

@@ -1,314 +0,0 @@
----
-name: ghx
-description: GitHub code exploration for AI agents. Use for repo exploration, reading remote files, code search, code maps. Wraps gh CLI with GraphQL batching — one command does what takes 3-5 API calls.
----
-
-# ghx — GitHub Code Exploration for AI Agents
-
-Use `ghx` via `execute_bash` for anything on GitHub — repos, files, code search. Authenticated via `gh` CLI, structured output, zero context overhead.
-
-## Why This Exists
-
-Agents exploring GitHub face a reliability gap: *"Did I find nothing because nothing exists, or because I used the tool wrong?"* Raw `gh` commands have silent failure modes — `gh search code` wraps in quotes without telling you, `gh api contents/` returns base64, README requires a separate call. The agent can't distinguish "no results" from "wrong flags."
-
-ghx eliminates this by encoding the right defaults into every command. One call returns enough context to decide the next action. You opt into the ghx skill and stop worrying about whether you searched correctly — the right behavior is the default behavior.
-
-## Commands
-
-```bash
-ghx explore <owner/repo>                    # Branch + tree + README in 1 API call
-ghx explore <owner/repo> <path>             # Subdirectory listing
-ghx read <owner/repo> <f1> [f2] [f3]       # Read 1-10 files in 1 API call (GraphQL batching)
-ghx read <owner/repo> --map <f1> [f2]       # Structural map: signatures, imports, types (~92% token reduction)
-ghx read <owner/repo> --grep "pat" <f>      # Read file, show only matching lines (2 lines context)
-ghx read <owner/repo> --lines 42-80 <f>     # Read specific line range
-ghx repos "<query>"                         # Search repos with README preview (default: 10 results)
-ghx repos "<query>" --limit 5               # Limit repo results (max: 20)
-ghx search "<query>"                        # Code search (AND matching, default: 30 results)
-ghx search "<query>" --limit 10             # Limit code search results (max: 100)
-ghx search --full "<query>"                 # Code search without line truncation (for minified files)
-ghx tree <owner/repo> [path]                # Full recursive tree listing
-```
-
-**Exit codes:** 0 = results returned, 1 = no results (query valid), 2 = usage error (bad flags/args).
-**Flag safety:** Unknown flags always error (exit 2). Never silently absorbed into queries.
-
-## Chain of Thought: Progressive Disclosure
-
-**Always start surgical, escalate only when needed.** This mirrors how developers work: scan structure → identify interesting files → read specific sections.
-
-```
-1. ghx explore owner/repo          → What's in this repo? (structure + README)
-2. ghx read owner/repo --map *.ts  → What do these files define? (signatures only, 92% fewer tokens)
-3. ghx read owner/repo --grep "X" f → Where exactly is X in this file? (targeted lines)
-4. ghx read owner/repo f            → Show me the full file (only when needed)
-```
-
-**Why this order matters:** At 92% reduction, `--map` lets you scan 7 files in the space of reading 1 full file. The agent can understand an entire module's structure before committing context to any single file. Aider's docs confirm: *"The LLM can see classes, methods and function signatures from everywhere in the repo. This alone may give it enough context to solve many tasks."*
-
-**When to escalate beyond ghx:**
-- "Understand this entire module" → `gitingest https://github.com/owner/repo/tree/branch/path -i "*.ts" -o - 2>/dev/null`
-- "Compressed view of a codebase" → `npx repomix --remote owner/repo --compress --include "src/**" --stdout`
-
-## Search Query Syntax
-
-`ghx search` uses the GitHub REST code search API (legacy). Multi-word queries use AND matching — both words must appear in the file but not necessarily adjacent. This is different from `gh search code` which silently wraps in quotes (exact phrase).
-
-**Output format:**
-```
-201472 results (showing 30)                              ← stderr (total + page count)
-jquery/jquery src/attributes/classes.js: addClass: function( value ) {   ← stdout (repo path: matching line)
-```
-
-Agents get: result count (stderr) + one line per result with matching context (stdout).
-
-```bash
-ghx search "addClass repo:jquery/jquery"                  # Scoped to repo
-ghx search "useState language:typescript"                 # Language filter
-ghx search "filename:package.json repo:owner/repo"        # Find specific filename
-ghx search "form path:cgi-bin extension:py"               # Path + extension filter
-ghx search '"progress_bar" repo:plausible/analytics'      # Exact phrase (shell quotes around double quotes)
-ghx search "path:llms.txt"                                # Find files by name
-```
-
-**Valid REST API qualifiers:** `repo:`, `org:`, `user:`, `path:`, `filename:`, `extension:`, `language:`, `in:file`, `in:path`, `size:`, `fork:true`
-
-**Web-only (DO NOT USE — silently treated as literal text):** `OR`, `NOT`, `symbol:`, `content:`, `is:`, regex (`/pattern/`), `enterprise:`, glob in `path:`. ghx warns on stderr if you use these.
-
-**Rate limit:** 9 req/min for code search (strictest endpoint). Authentication required — `gh auth login` first.
-
-**Special characters:** Dots act as word separators, not wildcards. `console.log` matches files with both `console` and `log` — it does NOT match `consolelog`.
-
-## Search Strategy for Agents
-
-**Search is the entry point.** Agents search first, then read. Bad search = wasted follow-up reads = token explosion. ghx search is designed to give you enough context to decide your next action in one call.
-
-### Reading search output
-
-```
-90 results (showing 30)                                          ← stderr: is this too broad?
-⚠ Lines truncated to 200 chars (use --full for complete fragments) ← stderr: token protection kicked in
-⚠ Query too broad — add repo:, language:, or path: to narrow      ← stderr: >1000 results
-jquery/jquery src/attributes/classes.js: addClass: function( value ) {  ← stdout: repo path: matching line
-```
-
-**Decision tree after seeing results:**
-- `0 results` → query too specific, broaden (remove qualifiers, try synonyms)
-- `1-30 results` → good. Scan matching lines, `ghx read` the relevant files
-- `30-1000 results` → workable but noisy. Add `repo:`, `language:`, or `path:` to narrow
-- `>1000 results` → too broad. MUST add qualifiers before trusting results
-- `⚠ incomplete` → query timed out, results are partial. Narrow the scope
-
-### Token protection (safe by default)
-
-ghx truncates each matching line to 200 chars. This prevents minified JS files (10,000+ char lines) from exploding your context window. One untruncated minified result can consume more tokens than the other 29 results combined.
-
-- **Default**: 200 char truncation. You see `⚠ Lines truncated` on stderr only when it triggers.
-- **`--full`**: Disables truncation. Use when you specifically need the complete matching line.
-- **When to use `--full`**: Almost never. The truncated line is enough to decide "relevant" or "skip." Use `ghx read` to get the full file context after you've identified the right file.
-
-### Search refinement chain of thought
-
-```
-1. ghx search "useState"                              → 201K results. Too broad.
-2. ghx search "useState language:typescript"           → 50K results. Still broad.
-3. ghx search "useState repo:vercel/next.js"           → 89 results. Workable.
-4. ghx search "useState path:packages/next extension:tsx repo:vercel/next.js"  → 12 results. Surgical.
-```
-
-**Refine, don't paginate.** At 9 req/min, pagination burns rate limit on the same broad query. Adding one qualifier is always better than fetching page 2.
-
-### Two search systems (why some things don't work)
-
-GitHub has two code search engines. The REST API (what ghx uses) is the legacy one. The web UI uses Blackbird (new). No programmatic tool — ghx, `gh` CLI, GitHub MCP, Octocode — can access Blackbird. This is a platform limitation, not a ghx limitation.
-
-**What this means for agents:**
-- `OR`, `NOT`, `symbol:`, regex, `content:`, `is:` → web-only, don't use
-- `repo:`, `path:`, `filename:`, `language:`, `extension:`, `in:`, `size:`, `fork:` → work in REST API
-- ghx warns on stderr if you use web-only qualifiers, but the results will be wrong
-
-### ghx search vs `gh search code`
-
-| Behavior | `ghx search` | `gh search code` |
-|---|---|---|
-| Multi-word matching | AND (both words anywhere) | Exact phrase (words must be adjacent) |
-| Matching context | Shows matching line per result | No matching context |
-| Result count | stderr: "90 results (showing 30)" | Not shown |
-| Token protection | 200 char truncation, `--full` opt-out | None |
-| Web-only warnings | Warns on stderr | Silent |
-| Rate limit | Same (9 req/min) | Same |
-
-AND matching is almost always what agents want. `gh search code "useState fetchData"` returns zero results if the words aren't adjacent — with no error. `ghx search "useState fetchData"` finds files containing both terms.
-
-## Gotchas
-
-1. **Web-only qualifiers silently degrade.** `symbol:`, `OR`, `NOT`, `content:`, `is:`, regex — these only work in GitHub's new web code search (Blackbird). The REST API treats them as literal text. `symbol:foo` searches for the TEXT "symbol:foo" inside files. ghx warns on stderr, but the results will be wrong. No programmatic tool can use these features — it's a GitHub platform limitation.
-
-2. **`filename:` vs `path:` — both valid, different systems.** `filename:package.json` works in the REST API (legacy) for exact filename match. `path:` also works and is more flexible (matches directories too). In the NEW web code search, only `path:` works — `filename:` is not recognized. Since ghx uses the REST API, both work.
-
-3. **`language:markdown` won't find `.txt` files.** GitHub's linguist detection doesn't classify .txt as markdown. Use `extension:txt` instead. `language:` = linguist detection, `extension:` = literal file extension.
-
-4. **`gh search code` silently wraps queries in quotes.** `gh search code "foo bar"` sends `q="foo bar"` (exact phrase), not `q=foo bar` (AND). If the words aren't adjacent in the file, you get zero results with no error. `ghx search` sends AND queries — both words must appear but in any order. This is almost always what you want. ghx also shows result count on stderr and matching line context — `gh search code` shows neither.
-
-5. **GraphQL returns null for missing paths.** `object(expression: "branch:path")` returns null silently if the path doesn't exist. No error. `ghx` handles this, but if using `gh api graphql` directly, check for null.
-
-6. **Flag ordering in `read` command.** `ghx read owner/repo file --map` works. `ghx read --map owner/repo file` does NOT — repo must be the first positional arg.
-
-7. **Not all repos use `main`.** cli/cli uses `trunk`, others use `master`. `ghx` handles this automatically. For raw `gh api` calls, query the default branch first: `gh repo view owner/repo --json defaultBranchRef --jq '.defaultBranchRef.name'`
-
-8. **`gh` field names are inconsistent.** `stargazersCount` (search) vs `stargazerCount` (repo view). Always check with `--json` (no fields) to see available fields for any command.
-
-9. **`gh api repos/.../contents/` returns base64 by default.** Without `-H "Accept: application/vnd.github.raw+json"`, you get a JSON blob with base64-encoded content. `ghx read` returns plain text via GraphQL — no decoding needed.
-
-10. **`gh search repos` and `gh search code` use different rate limit pools.** Repo search: 30/min (generous). Code search: 10/min (restrictive). Don't assume one rate limit applies to both.
-
-11. **Unknown flags are rejected, not silently absorbed.** `ghx search "query" --json` exits 2 with a clear error. This is intentional — silent flag absorption was the #1 cause of agent failures (flags like `--limit` would get concatenated into the query string, corrupting it). If you get exit 2, check your flags.
-
-## Anti-Patterns
-
-- ❌ `web_fetch`/`web_search` on github.com — returns HTML noise, wastes thousands of tokens for zero useful information
-- ❌ `gh api repos/.../contents/<path>` WITHOUT `-H "Accept: application/vnd.github.raw+json"` — returns base64-encoded JSON blob instead of readable text
-- ❌ Reading entire large files when you need 10 lines — use `--grep "pattern"` or `--lines N-M`
-- ❌ Multiple sequential `gh api` calls for explore workflows — use `ghx explore` (1 GraphQL call) or `ghx read` (batch files)
-- ❌ Using web-only qualifiers (`OR`, `NOT`, `symbol:`, regex) in `ghx search` — silently treated as literal text, returns wrong results. ghx warns but can't prevent it
-- ❌ Firing multiple code search requests in parallel — 9 req/min rate limit, you'll get 403s
-- ❌ Dumping entire repos into context for a specific question — use targeted `ghx` commands. Reserve `gitingest`/`repomix` for "understand this whole module" tasks
-- ❌ Relying on `gh search code` for multi-word queries — silently wraps in quotes (exact phrase), returns nothing when words aren't adjacent. Use `ghx search` (AND matching + matching context)
-- ❌ Using `ghx search` to find repos — ghx search is for code. Use `ghx repos "query"` for repo discovery
-- ❌ Using `gh` for batch file reads — 1 API call per file, base64 encoded. Use `ghx read repo f1 f2 f3` (1 GraphQL call, plain text)
-- ❌ Using `gh repo view` to explore a repo — gets metadata but not tree listing or README content in one call. Use `ghx explore` (1 call for all three)
-
-## Best Practices
-
-- **Batch file reads.** `ghx read owner/repo f1 f2 f3` = 1 API call. Three separate reads = 3 calls.
-- **Map before reading.** `ghx read --map` first to understand structure, then `--grep` or `--lines` for specifics.
-- **Refine search, don't paginate.** If `ghx search` shows "201472 results (showing 30)", add qualifiers (`repo:`, `language:`, `path:`) — don't try to page through. 9 req/min rate limit makes pagination expensive.
-- **Use `--limit` to control token budget.** `ghx repos "query" --limit 5` for quick checks, `--limit 15` for thorough discovery. `ghx search "query" --limit 10` when you only need top results.
-- **Check exit codes.** 0 = got results, 1 = no results (query was valid, broaden it), 2 = usage error (fix your command).
-- **Use `gh api --cache 1h`** for repeated lookups when using raw `gh` commands.
-- **Use `--json fields --jq 'expr'`** on `gh` commands to get structured output and reduce noise.
-- **Piped output is machine-formatted.** Tab-delimited, no truncation, no color codes — agents always get clean output.
-
-## The `--map` Flag: Why It Matters
-
-`--map` extracts only structural declarations (imports, exports, function/class/type signatures) via per-language regex patterns. Tested on 6 real files across TypeScript, Python, Go:
-
-| Metric | Result |
-|--------|--------|
-| Average token reduction | 92% |
-| Files scannable per context window | 7x more than full reads |
-| Implementation | ~15 lines of bash, zero dependencies |
-
-Output includes line numbers and token stats:
-```
-=== src/core/parseFile.ts (5544 bytes) ===
-21:import type { RepomixConfigMerged } from '../../config/configSchema.js';
-35:export const CHUNK_SEPARATOR = '⋮----';
-38:export const parseFile = async (fileContent: string, filePath: string, config: RepomixConfigMerged) =>
-107:const getLanguageParserSingleton = async () =>
-# map: 812/5544 chars (~1386 tokens full, ~203 tokens map)
-```
-
-Supported: TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin, Ruby. Generic fallback for unknown extensions.
-
-## Examples
-
-### Simple: Explore a repo and read a file
-
-```bash
-# What's in this repo?
-ghx explore plausible/analytics
-
-# Read the main config
-ghx read plausible/analytics config/runtime.exs
-```
-
-### Advanced: Research a codebase you've never seen
-
-```bash
-# 1. Explore structure
-ghx explore yamadashy/repomix
-
-# 2. Map the core module — understand what exists (92% fewer tokens)
-ghx read yamadashy/repomix --map src/core/output/outputGenerate.ts src/core/file/fileProcess.ts src/core/treeSitter/parseFile.ts
-
-# 3. Found interesting function in map output — grep for usage details
-ghx read yamadashy/repomix --grep "processFiles" src/core/file/fileProcess.ts
-
-# 4. Search across the whole repo for a pattern
-ghx search "CHUNK_SEPARATOR repo:yamadashy/repomix"
-# → stderr: "3 results (showing 3)"
-# → stdout: yamadashy/repomix src/core/output/outputGenerate.ts: const CHUNK_SEPARATOR = '⋮----';
-
-# 5. Read specific lines of a file you've narrowed down
-ghx read yamadashy/repomix --lines 38-65 src/core/treeSitter/parseFile.ts
-
-# 6. If you need the full picture of a subdirectory, escalate:
-# gitingest https://github.com/yamadashy/repomix/tree/main/src/core -i "*.ts" -o - 2>/dev/null
-```
-
-## Complementary Tools
-
-| Goal | Tool | Why |
-|------|------|-----|
-| Surgical exploration | `ghx` | Batched API calls, zero overhead, targeted extraction |
-| Holistic understanding | `gitingest` / `repomix --compress` | Dump entire module for broad reasoning |
-| PRs, issues, CI | `gh pr view`, `gh issue view`, `gh pr checks` | Purpose-built commands |
-
-## ghx vs gh: When to Use What
-
-**ghx is a complement to gh, not a replacement.** Use ghx for code exploration. Use gh for everything else.
-
-### Use ghx (code exploration)
-
-| Task | Command | Why ghx wins |
-|------|---------|-------------|
-| Code search | `ghx search "query"` | AND matching (gh uses exact phrase), matching context, 37x token reduction on minified files, result count + warnings on stderr |
-| Repo search | `ghx repos "query"` | 1 GraphQL call gets name + stars + language + README preview. gh needs 1+N calls for same info, returns worse ranking, no README |
-| Repo overview | `ghx explore owner/repo` | 1 GraphQL call gets description + tree + README (gh needs 3 calls) |
-| Read multiple files | `ghx read owner/repo f1 f2 f3` | 1 GraphQL call for N files (gh needs N calls, returns base64) |
-| Targeted extraction | `ghx read --grep "pat" f` | Built-in grep with context lines — no shell piping |
-| Code map | `ghx read --map f1 f2` | ~92% token reduction, no gh equivalent |
-
-### Use gh (everything else)
-
-| Task | Command | Why gh wins |
-|------|---------|-------------|
-| Issues | `gh issue list/view -R owner/repo` | ghx doesn't touch issues |
-| Pull requests | `gh pr list/view/diff/checks -R owner/repo` | ghx doesn't touch PRs |
-| Releases | `gh release list -R owner/repo` | ghx doesn't touch releases |
-| Repo metadata | `gh repo view owner/repo --json stargazerCount,forkCount` | Detailed stats beyond what ghx repos shows |
-| Auth | `gh auth login/status` | ghx depends on gh for auth |
-| Create/update | `gh issue create`, `gh pr create` | ghx is read-only |
-
-### Rate limits (from GitHub docs)
-
-| Endpoint | Limit | Used by |
-|---|---|---|
-| Core REST | 5,000/hour | gh commands, ghx tree |
-| GraphQL | 5,000/hour | ghx explore, ghx read |
-| Search (repos, issues) | 30/min | `gh search repos/issues` |
-| Code search | 10/min (budget 9) | `ghx search`, `gh search code` |
-
-Code search is 50x more restricted than core REST. This is why "refine don't paginate" matters for search but not for explore/read.
-
-## `gh` CLI Quick Reference
-
-```bash
-# Repos
-gh search repos "<query>" -L 10 --json fullName,description,stargazersCount
-gh repo view owner/repo --json defaultBranchRef --jq '.defaultBranchRef.name'
-
-# PRs
-gh pr view 123 -R owner/repo                    # Title, body, status
-gh pr diff 123 -R owner/repo                    # Full diff
-gh pr checks 123 -R owner/repo                  # CI status
-
-# Issues
-gh issue view 456 -R owner/repo
-gh issue list -R owner/repo -S "query" -L 20
-
-# Raw API (always use the raw header for files)
-gh api repos/owner/repo/contents/path -H "Accept: application/vnd.github.raw+json"
-gh api repos/owner/repo/git/trees/main --jq '.tree[].path'   # List structure
-```

package/v1/ghx

@@ -1,385 +0,0 @@
-#!/usr/bin/env bash
-# ghx — GitHub code exploration for agents and humans
-# Efficient GitHub repo exploration via GraphQL batching, code maps, and targeted extraction.
-# One command does what takes 3-5 API calls with any other tool.
-
-set -euo pipefail
-
-VERSION="0.2.1"
-
-cmd="${1:-help}"
-shift || true
-
-case "$cmd" in
-
-# ─── explore: branch + tree + README in one GraphQL call ───
-explore)
-  repo="$1"; shift || true
-  path="${1:-}"
-  owner="${repo%%/*}"
-  name="${repo##*/}"
-
-  # First get default branch
-  branch=$(gh repo view "$repo" --json defaultBranchRef --jq '.defaultBranchRef.name')
-
-  if [[ -z "$path" ]]; then
-    # Root exploration: tree + README
-    gh api graphql -f query="
-    {
-      repository(owner: \"$owner\", name: \"$name\") {
-        description
-        tree: object(expression: \"$branch:\") {
-          ... on Tree { entries { name type } }
-        }
-        readme: object(expression: \"$branch:README.md\") {
-          ... on Blob { text }
-        }
-      }
-    }" --jq '{
-      description: .data.repository.description,
-      branch: "'"$branch"'",
-      files: [.data.repository.tree.entries[] | "\(if .type == "tree" then .name + "/" else .name end)"],
-      readme: (.data.repository.readme.text // "(no README.md)")
-    }'
-  else
-    # Subdir exploration: tree listing
-    gh api graphql -f query="
-    {
-      repository(owner: \"$owner\", name: \"$name\") {
-        tree: object(expression: \"$branch:$path\") {
-          ... on Tree { entries { name type } }
-        }
-      }
-    }" --jq '{
-      path: "'"$path"'",
-      entries: [.data.repository.tree.entries[] | "\(if .type == "tree" then .name + "/" else .name end)"]
-    }'
-  fi
-  ;;
-
-# ─── read: read 1-10 files in one GraphQL call ───
-# Supports --grep "pattern" to filter output to matching lines (with 2 lines context)
-# Supports --lines N-M to extract specific line ranges
-read)
-  repo="$1"; shift
-  owner="${repo%%/*}"
-  name="${repo##*/}"
-
-  # Parse flags (must come before file paths)
-  grep_pattern=""
-  line_range=""
-  map_mode=""
-  files=()
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --grep) grep_pattern="$2"; shift 2 ;;
-      --lines) line_range="$2"; shift 2 ;;
-      --map) map_mode=1; shift ;;
-      --*) echo "ghx read: unknown flag '$1'" >&2; exit 2 ;;
-      *) files+=("$1"); shift ;;
-    esac
-  done
-
-  if [[ ${#files[@]} -eq 0 ]]; then
-    echo "Usage: ghx read <owner/repo> <path1> [path2] [--grep pattern] [--lines N-M]" >&2
-    exit 2
-  fi
-
-  # Get default branch
-  branch=$(gh repo view "$repo" --json defaultBranchRef --jq '.defaultBranchRef.name')
-
-  # Build GraphQL query with aliases
-  query="{ repository(owner: \"$owner\", name: \"$name\") {"
-  for i in "${!files[@]}"; do
-    query+=" f$i: object(expression: \"$branch:${files[$i]}\") { ... on Blob { text byteSize } }"
-  done
-  query+=" } }"
-
-  # Execute and format output
-  result=$(gh api graphql -f query="$query")
-
-  for i in "${!files[@]}"; do
-    text=$(echo "$result" | jq -r ".data.repository.f$i.text // empty")
-    size=$(echo "$result" | jq -r ".data.repository.f$i.byteSize // empty")
-    if [[ -n "$text" ]]; then
-      echo "=== ${files[$i]} ($size bytes) ==="
-      if [[ -n "$grep_pattern" ]]; then
-        echo "$text" | grep -n -i -C2 "$grep_pattern" || echo "(no matches for '$grep_pattern')"
-      elif [[ -n "$line_range" ]]; then
-        start="${line_range%-*}"
-        end="${line_range#*-}"
-        echo "$text" | sed -n "${start},${end}p"
-      elif [[ -n "$map_mode" ]]; then
-        ext="${files[$i]##*.}"
-        case "$ext" in
-          ts|tsx|js|jsx|mjs) pat='^(import |export |const |let |var |function |class |interface |type |enum )' ;;
-          py) pat='^(import |from |class |def |    def |        def |@)' ;;
-          go) pat='^(package |import |func |type |var |const )' ;;
-          rs) pat='^(use |pub |fn |struct |enum |trait |impl |type |mod |const )' ;;
-          java|kt) pat='^(import |public |private |protected |class |interface |enum |@)' ;;
-          rb) pat='^(require |class |module |def |  def |    def )' ;;
-          *) pat='^(import |export |function |class |def |func |type |const |pub )' ;;
-        esac
-        echo "$text" | grep -nE "$pat" || echo "(no signatures detected)"
-        chars=$(echo "$text" | wc -c | tr -d ' ')
-        map_chars=$(echo "$text" | grep -E "$pat" | wc -c | tr -d ' ')
-        echo "# map: ${map_chars}/${chars} chars (~$(( chars / 4 )) tokens full, ~$(( map_chars / 4 )) tokens map)"
-      else
-        echo "$text"
-      fi
-      echo ""
-    else
-      echo "=== ${files[$i]} (not found) ==="
-      echo ""
-    fi
-  done
-  ;;
-
-# ─── search: code search via REST API ───
-search)
-  # Parse flags
-  full_mode=""
-  limit=""
-  args=()
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --full) full_mode=1; shift ;;
-      --limit) [[ $# -lt 2 ]] && { echo "ghx search: --limit requires a value" >&2; exit 2; }
-        limit="$2"; shift 2 ;;
-      --*) echo "ghx search: unknown flag '$1'" >&2; exit 2 ;;
-      *) args+=("$1"); shift ;;
-    esac
-  done
-  query="${args[*]}"
-  if [[ -z "$query" ]]; then
-    echo "Usage: ghx search <query> [--full] [--limit N]" >&2
-    echo "Examples: 'useState repo:owner/repo' | 'path:src/ extension:tsx language:typescript'" >&2
-    exit 2
-  fi
-  # Validate and clamp limit (API max: 100)
-  if [[ -n "$limit" ]]; then
-    [[ "$limit" =~ ^[0-9]+$ ]] || { echo "ghx search: --limit must be a number, got '$limit'" >&2; exit 2; }
-    (( limit > 100 )) && { echo "⚠ --limit clamped to 100 (API max)" >&2; limit=100; }
-  fi
-
-  # Prerequisite checks
-  if ! command -v gh &>/dev/null; then
-    echo "ghx requires the GitHub CLI (gh). Install: https://cli.github.com" >&2
-    exit 2
-  fi
-  if ! gh auth status &>/dev/null; then
-    echo "GitHub code search requires authentication. Run: gh auth login" >&2
-    exit 2
-  fi
-
-  # Warn on web-only qualifiers (they silently become literal text in REST API)
-  for pat in 'symbol:' 'content:' 'is:' ' OR ' ' NOT ' '/.*/' 'enterprise:'; do
-    if [[ "$query" == *$pat* ]]; then
-      echo "⚠ '$pat' is web-only (Blackbird) — REST API treats it as literal text" >&2
-    fi
-  done
-
-  # Search with text_matches for matching context
-  per_page="${limit:-30}"
-  response=$(gh api /search/code --method GET \
-    -H "Accept: application/vnd.github.text-match+json" \
-    -f q="$query" -f per_page="$per_page" 2>&1) || {
-    echo "$response" >&2
-    exit 1
-  }
-
-  # Result count + incomplete warning to stderr
-  total=$(echo "$response" | jq -r '.total_count')
-  incomplete=$(echo "$response" | jq -r '.incomplete_results')
-  count=$(echo "$response" | jq '.items | length')
-  echo "$total results (showing $count)" >&2
-  [[ "$incomplete" == "true" ]] && echo "⚠ Results may be incomplete (query timed out)" >&2
-  [[ "$total" -gt 1000 ]] 2>/dev/null && echo "⚠ Query too broad — add repo:, language:, or path: to narrow" >&2
-  [[ "$count" -eq 0 ]] && exit 1
-
-  # Output: repo path: matching context from fragment
-  # Default: 200 char window centered on the match (prevents minified JS token explosion)
-  # Uses matches[0].indices to find the actual match position in the fragment
-  if [[ -n "$full_mode" ]]; then
-    echo "$response" | jq -r '
-      .items[] |
-      .repository.full_name as $repo |
-      .path as $path |
-      (.text_matches // []) as $tm |
-      if ($tm | length) > 0 then
-        ($tm[0].fragment | gsub("\\n"; " ") | gsub("\\s+"; " ") |
-          gsub("^\\s+"; "") | gsub("\\s+$"; "")) as $line |
-        "\($repo) \($path): \($line)"
-      else
-        "\($repo) \($path)"
-      end'
-  else
-    truncated=$(echo "$response" | jq '[.items[] |
-      (.text_matches // []) as $tm |
-      if ($tm | length) > 0 then
-        ($tm[0].fragment | length) > 200
-      else false end] | any')
-    [[ "$truncated" == "true" ]] && echo "⚠ Lines truncated to 200 chars (use --full for complete fragments)" >&2
-    echo "$response" | jq -r '
-      .items[] |
-      .repository.full_name as $repo |
-      .path as $path |
-      (.text_matches // []) as $tm |
-      if ($tm | length) > 0 then
-        $tm[0] as $m |
-        ($m.fragment | gsub("\\n"; " ") | gsub("\\s+"; " ")) as $flat |
-        (if ($m.matches | length) > 0 then
-          $m.matches[0].indices[0] as $start |
-          ([$start - 80, 0] | max) as $from |
-          ($from + 200) as $to |
-          (if $from > 0 then "…" else "" end) as $prefix |
-          (if $to < ($flat | length) then "…" else "" end) as $suffix |
-          $prefix + ($flat[$from:$to] | gsub("^\\s+"; "") | gsub("\\s+$"; "")) + $suffix
-        else
-          $flat[:200]
-        end) as $line |
-        "\($repo) \($path): \($line)"
-      else
-        "\($repo) \($path)"
-      end'
-  fi
-  ;;
-
-# ─── repos: search repos with README preview in 1 GraphQL call ───
-repos)
-  limit=""
-  args=()
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --limit) [[ $# -lt 2 ]] && { echo "ghx repos: --limit requires a value" >&2; exit 2; }
-        limit="$2"; shift 2 ;;
-      --*) echo "ghx repos: unknown flag '$1'" >&2; exit 2 ;;
-      *) args+=("$1"); shift ;;
-    esac
-  done
-  query="${args[*]}"
-  if [[ -z "$query" ]]; then
-    echo "Usage: ghx repos <query> [--limit N]" >&2
-    exit 2
-  fi
-  # Validate and clamp limit (GraphQL max: 100, but README fetching makes >20 expensive)
-  first="${limit:-10}"
-  [[ "$first" =~ ^[0-9]+$ ]] || { echo "ghx repos: --limit must be a number, got '$first'" >&2; exit 2; }
-  (( first > 20 )) && { echo "⚠ --limit clamped to 20 (README fetching makes larger values slow)" >&2; first=20; }
-
-  response=$(gh api graphql -f query='
-  {
-    search(query: "'"$query"'", type: REPOSITORY, first: '"$first"') {
-      repositoryCount
-      nodes {
-        ... on Repository {
-          nameWithOwner
-          description
-          stargazerCount
-          primaryLanguage { name }
-          object(expression: "HEAD:README.md") {
-            ... on Blob { text }
-          }
-        }
-      }
-    }
-  }')
-
-  echo "$response" | jq -r '.data.search.repositoryCount | "\(.) repos found"' >&2
-  count=$(echo "$response" | jq '.data.search.nodes | length')
-  [[ "$count" -eq 0 ]] && exit 1
-  echo "$response" | jq -r '
-    .data.search.nodes[] |
-    .nameWithOwner as $name |
-    (.stargazerCount | tostring) as $stars |
-    ((.primaryLanguage.name // "?")) as $lang |
-    (.description // "") as $desc |
-    ((.object.text // "") | gsub("\\n"; " ") | gsub("\\s+"; " ") | gsub("^\\s+"; "") |
-      gsub("\\[!\\[[^]]*\\]\\([^)]*\\)\\]\\([^)]*\\)"; "") |
-      gsub("!\\[[^]]*\\]\\([^)]*\\)"; "") |
-      gsub("\\[!\\[[^]]*\\]\\([^)]*\\)\\]"; "") |
-      gsub("\\[![^]]*\\]\\([^)]*\\)"; "") |
-      gsub("<img[^>]*>"; "") |
-      gsub("<div[^>]*>"; "") | gsub("</div>"; "") |
-      gsub("<br[^>]*/?>"; "") |
-      gsub("<p[^>]*>"; "") | gsub("</p>"; "") |
-      gsub("<a[^>]*>"; "") | gsub("</a>"; "") |
-      gsub("\\s+"; " ") | gsub("^\\s+"; "") |
-      .[:300]) as $readme |
-    "\($name) (\($stars)★ \($lang)) \($desc)" +
-    (if ($readme | length) > 0 then "\n  " + $readme + (if ($readme | length) >= 300 then "…" else "" end) else "" end)
-  '
-  ;;
-
-# ─── skill: output SKILL.md for agent context injection ───
-skill)
-  script_dir="$(dirname "$(readlink -f "$0")")"
-  skill_file="$script_dir/SKILL.md"
-  if [[ -f "$skill_file" ]]; then
-    cat "$skill_file"
-  else
-    echo "SKILL.md not found at $skill_file" >&2
-    exit 1
-  fi
-  ;;
-
-# ─── tree: recursive tree listing via REST API ───
-tree)
-  repo="$1"; shift || true
-  path="${1:-}"
-  owner="${repo%%/*}"
-  name="${repo##*/}"
-
-  branch=$(gh repo view "$repo" --json defaultBranchRef --jq '.defaultBranchRef.name')
-
-  gh api "repos/$owner/$name/git/trees/$branch?recursive=1" --jq '
-    [.tree[] | select(.type == "blob") | .path] |
-    if "'"$path"'" != "" then
-      [.[] | select(startswith("'"$path"'/"))] |
-      map(ltrimstr("'"$path"'/"))
-    else . end |
-    .[]
-  '
-  ;;
-
-# ─── help ───
-version|-v|--version)
-  echo "ghx $VERSION"
-  ;;
-
-help|*)
-  cat <<'EOF'
-ghx — GitHub code exploration for agents and humans
-
-Commands:
-  ghx explore <owner/repo> [path]     Branch + tree + README in 1 API call
-  ghx read <owner/repo> <f1> [f2..]   Read 1-10 files in 1 API call
-  ghx repos <query> [--limit N]        Search repos with README preview (default: 10)
-  ghx search "<query>" [--limit N]     Code search (AND matching, default: 30)
-  ghx search --full "<query>"          Code search without line truncation
-  ghx skill                            Output SKILL.md (for agent context injection)
-  ghx tree <owner/repo> [path]         Full recursive tree listing
-
-Read flags:
-  --grep <pattern>    Filter output to matching lines (case-insensitive, 2 lines context)
-  --lines <N-M>       Extract specific line range
-  --map               Structural signatures only (~92% token reduction)
-
-Exit codes:
-  0  Success with results
-  1  No results (query valid, nothing matched)
-  2  Usage error (bad flags, missing args)
-
-Examples:
-  ghx explore plausible/analytics
-  ghx read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js
-  ghx read plausible/analytics src/app.ts --grep "useState"
-  ghx read plausible/analytics src/app.ts --lines 42-80
-  ghx repos "react state management"
-  ghx search "useState repo:plausible/analytics"
-  ghx search "filename:package.json repo:plausible/analytics"
-  ghx tree plausible/analytics assets/js
-EOF
-  ;;
-
-esac