@gkoreli/ghx 0.2.1 → 2.0.2

package/README.md

@@ -1,122 +1,117 @@
-# ghx
+# ghx — GitHub Code Exploration for AI Agents
 
-GitHub code exploration for agents and humans. One command does what takes 3-5 API calls with any other tool.
+One command does what takes 3-5 API calls. Batch file reads, code maps, search — all via `gh` CLI. Write JS programs that compose operations in one round-trip.
 
-- **Repos** — search repos with README preview in 1 GraphQL call
-- **Explore** a repo (tree + README) in 1 API call
-- **Read** 1-10 files in 1 API call via GraphQL batching
-- **Map** code structure with ~92% token reduction
-- **Search** code with AND matching, matching context, token protection
+## Why
+
+AI 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."
 
-Bash script. One dependency: `gh` CLI. Cross-platform (macOS, Linux, Windows via Git Bash/WSL).
+ghx eliminates this by encoding the right defaults into every command. One call returns enough context to decide the next action.
+
+| Tool | Files per call | Matching context | Programmable | Dependencies |
+|------|---------------|-----------------|-------------|-------------|
+| GitHub MCP | 1 | No | No (~10K token schemas) | Go binary |
+| `gh` CLI | 1 | No | No (exact phrase, base64, no README) | `gh` |
+| **ghx** | **1-10 (batch)** | **Yes** | **Yes (codemode)** | **`gh`** |
 
 ## Install
 
 ```bash
-# npm (recommended)
-npm install -g @gkoreli/ghx
+# Build from source
+cd v2 && go build -o ghx .
 
-# npx (zero install)
-npx @gkoreli/ghx --help
+# Homebrew
+brew install gkoreli/tap/ghx
 
-# curl
-curl -sf https://raw.githubusercontent.com/gkoreli/ghx/main/install.sh | sh
+# One-liner
+curl -sfL https://raw.githubusercontent.com/gkoreli/ghx/mainline/install.sh | bash
 ```
 
-Requires [`gh` CLI](https://cli.github.com/) authenticated (`gh auth login`).
-
-[![npm](https://img.shields.io/npm/v/@gkoreli/ghx)](https://www.npmjs.com/package/@gkoreli/ghx)
-
-### 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. Raw cmd.exe/PowerShell not supported |
+Requires: [gh CLI](https://cli.github.com/) authenticated (`gh auth login`).
 
-If you have `gh` CLI working, ghx works too — same prerequisites.
-
-## Usage
+## Commands
 
 ```bash
-# Search repos — name, stars, language, README preview in 1 call
-ghx repos "react state management"
-ghx repos "playwright mcp" --limit 5
+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 (GraphQL batching)
+ghx search "<query>"                        # Code search with matching lines
+ghx repos "<query>"                         # Repo search with README preview
+ghx tree <owner/repo> [path]                # Full recursive tree
+```
 
-# Explore a repo — branch, file tree, and README in 1 API call
-ghx explore plausible/analytics
+## Codemode
 
-# Read multiple files in 1 API call
-ghx read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js
+Write JS programs that compose multiple operations in one round-trip. All `codemode.*` calls are synchronous — no `await`. Full TypeScript type stubs with return types are injected into the sandbox.
 
-# Code map — signatures, imports, types only (~92% token reduction)
-ghx read plausible/analytics --map lib/plausible/stats/query.ex
+```bash
+# What branch is this repo on?
+ghx code 'var r = codemode.explore({repo: "vercel/next.js"}); return r.branch;'
 
-# Grep within a remote file (2 lines context)
-ghx read plausible/analytics --grep "defmodule" lib/plausible/stats/query.ex
+# Search + read composition
+ghx code 'var hits = codemode.search({query: "useState repo:vercel/next.js", limit: 3});
+var first = codemode.read({repo: "vercel/next.js", files: [hits.matches[0].path]});
+return {file: hits.matches[0].path, lines: first[0].content.split("\n").length};'
 
-# Read specific line range
-ghx read plausible/analytics --lines 42-80 lib/plausible/stats/query.ex
+# See what tools and types are available
+ghx code --list
+```
 
-# Search code (AND matching, shows matching lines, token-protected)
-ghx search "useState repo:facebook/react"
-ghx search "path:llms.txt extension:txt" --limit 10
+Type stubs tell the LLM exactly what fields exist — no guessing:
 
-# Full recursive tree
-ghx tree plausible/analytics assets/js
+```typescript
+declare const codemode: {
+  explore: (input: ExploreInput) => { description: string; branch: string; files: { name: string; type: string }[]; readme: string };
+  search: (input: SearchInput) => { total: number; incomplete: boolean; matches: { repo: string; path: string; fragment: string }[] };
+  tree: (input: TreeInput) => string[];
+  // ...
+}
 ```
 
-## Why
-
-AI agents exploring GitHub face a reliability gap: *"Did I find nothing because nothing exists, or because I used the tool wrong?"* ghx eliminates this with smart defaults — AND matching instead of exact phrase, README previews instead of bare names, matching context instead of bare paths. Unknown flags are rejected loudly (not silently absorbed into queries). The right behavior is the default behavior, and the wrong behavior is impossible.
+## MCP Server
 
-| Tool | Files per call | Matching context | Smart defaults | Dependencies |
-|------|---------------|-----------------|---------------|-------------|
-| GitHub MCP | 1 | No | No (~10K token schemas) | Go binary |
-| `gh` CLI | 1 | No | No (exact phrase, base64, no README) | `gh` |
-| **ghx** | **1-10 (batch)** | **Yes** | **Yes** | **`gh`** |
+```bash
+ghx serve                                   # stdio (for Claude, Cursor, etc.)
+ghx serve --http :8080                       # HTTP transport
+```
 
-## Agent Skill Integration
+7 tools: `explore`, `read`, `search`, `repos`, `tree`, `code` (meta-tool), `search_tools`.
 
-`ghx skill` outputs the full [`SKILL.md`](./SKILL.md) to stdout — designed for eager context injection via spawn hooks:
+## Agent Integration
 
-```json
-{
-  "hooks": {
-    "agentSpawn": [
-      {"command": "ghx skill"}
-    ]
-  }
-}
+```bash
+ghx skill                                   # CLI skill (for SKILL.md injection)
+ghx skill --mcp                             # MCP skill
 ```
 
-This loads the skill eagerly into every session — not on-demand like a typical skill file. Use this for agent identities where GitHub exploration is a core capability (not occasional). The agent always has the latest ghx knowledge (commands, gotchas, search strategy) without needing to load it mid-conversation.
+Designed for eager context injection via spawn hooks — the agent always has the latest ghx knowledge without loading it mid-conversation.
 
-SKILL.md is included in the npm package and resolved via symlink, so this works with all installation methods.
+## How It Works
 
-## Code Map (`--map`)
+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.
 
-The `--map` flag extracts only structural declarations — imports, exports, function signatures, class definitions, type declarations. Implementation bodies are stripped.
+Codemode runs JS in a [goja](https://github.com/nicholasgasior/goja) sandbox with esbuild TypeScript transpilation. Tools are injected as synchronous functions on a `codemode` global object. Max 20 tool calls per execution, 64KB code size limit.
 
-| 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% |
+## Architecture
 
-Average: **92% reduction**. An agent can map 16 files in the space of reading 1 file fully.
+```
+v2/
+├── pkg/ghx/       — core library (Explore, Read, Search, Repos, Tree)
+├── pkg/codemode/  — JS executor (goja sandbox, TS transpilation, type generation)
+└── cmd/           — CLI frontend (cobra) + MCP server (mcp-go)
+```
 
-Supported: TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin, Ruby. Generic fallback for unknown extensions.
+See [docs/adr/](docs/adr/) for architectural decisions.
 
-## How It Works
+## v1 (bash)
 
-`ghx` wraps `gh` CLI with GraphQL batching. `repos` and `explore` use GraphQL to batch search + metadata + README into 1 call. `read` uses GraphQL aliases to fetch up to 10 files in 1 call. `search` hits the REST `/search/code` endpoint with `text_matches` for matching context and 200-char token protection.
+The original bash implementation is in [`v1/`](v1/). Zero dependencies beyond `gh` and `jq` — useful if you just want a shell script you can drop anywhere without compiling Go.
+
+```bash
+npm install -g @gkoreli/ghx    # npm
+cp v1/ghx /usr/local/bin/ghx   # manual
+```
 
 ## License
 
 MIT
-
-## For AI Agents
-
-See [`SKILL.md`](./SKILL.md) for agent-optimized instructions — chain of thought, gotchas, anti-patterns, and examples.

package/package.json

@@ -1,19 +1,40 @@
 {
   "name": "@gkoreli/ghx",
-  "version": "0.2.1",
-  "description": "GitHub code exploration for agents and humans. Batch file reads, code maps, search — all via gh CLI.",
+  "version": "2.0.2",
+  "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
   "bin": {
     "ghx": "./ghx"
   },
-  "keywords": ["github", "cli", "code-exploration", "agent", "graphql", "code-map"],
+  "keywords": [
+    "github",
+    "cli",
+    "code-exploration",
+    "agent",
+    "graphql",
+    "code-map"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/gkoreli/ghx"
   },
-  "files": ["ghx", "SKILL.md", "README.md", "LICENSE"],
-  "os": ["darwin", "linux", "win32"],
+  "files": [
+    "ghx",
+    "postinstall.js",
+    "v2/SKILL.md",
+    "v2/MCP-SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
   "engines": {
     "node": ">=16"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
   }
 }

package/postinstall.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Downloads the ghx Go binary from GitHub releases on npm install
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+
+const REPO = "gkoreli/ghx";
+const BIN = path.join(__dirname, "ghx");
+
+const PLATFORM_MAP = { darwin: "darwin", linux: "linux", win32: "windows" };
+const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
+
+const os = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+if (!os || !arch) {
+  console.error(`Unsupported platform: ${process.platform}/${process.arch}`);
+  process.exit(1);
+}
+
+const ext = os === "windows" ? "zip" : "tar.gz";
+const url = `https://github.com/${REPO}/releases/latest/download/ghx_${os}_${arch}.${ext}`;
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return download(res.headers.location, dest).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      const file = fs.createWriteStream(dest);
+      res.pipe(file);
+      file.on("finish", () => file.close(resolve));
+    }).on("error", reject);
+  });
+}
+
+async function main() {
+  const tmp = path.join(__dirname, `ghx-download.${ext}`);
+  try {
+    console.log(`Downloading ghx (${os}/${arch})...`);
+    await download(url, tmp);
+    if (ext === "tar.gz") {
+      execSync(`tar xzf "${tmp}" -C "${__dirname}" ghx`, { stdio: "pipe" });
+    } else {
+      execSync(`unzip -o "${tmp}" ghx.exe -d "${__dirname}"`, { stdio: "pipe" });
+    }
+    fs.chmodSync(BIN, 0o755);
+    console.log("ghx installed successfully");
+  } finally {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+main().catch((e) => {
+  console.error(`Failed to install ghx: ${e.message}`);
+  console.error("Install manually: https://github.com/gkoreli/ghx#install");
+  process.exit(1);
+});

package/v2/MCP-SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ghx-mcp
+description: GitHub code exploration via MCP. 7 tools — 5 direct + code meta-tool + search_tools. The code tool lets you write JS programs that compose operations in one round-trip.
+---
+
+# ghx MCP — GitHub Code Exploration via MCP
+
+7 tools for GitHub exploration. 5 direct tools for simple queries. 1 `code` meta-tool for complex multi-step operations. 1 `search_tools` for discovery.
+
+## Tools
+
+### Direct Tools (simple one-shot queries)
+
+| Tool | Input | What it does |
+|------|-------|-------------|
+| `explore` | `repo` (required), `path` | Branch, file tree, README in 1 API call |
+| `read` | `repo` + `paths` (required), `grep`, `lines`, `map` | Read 1-10 files in 1 API call. `map` = signatures only (~92% reduction) |
+| `search` | `query` (required), `limit`, `full` | Code search with AND matching + matching lines |
+| `repos` | `query` (required), `limit` | Search repos with README preview |
+| `tree` | `repo` (required), `path` | Full recursive file tree |
+
+### Meta-Tools (compose operations)
+
+| Tool | Input | What it does |
+|------|-------|-------------|
+| `code` | `code` (required) | Execute JS that calls any combination of the 5 tools above |
+| `search_tools` | `query` (optional) | List available tools with TypeScript type stubs |
+
+## When to Use `code` vs Direct Tools
+
+**Direct tools** — simple, single-operation queries:
+```
+explore({ repo: "vercel/next.js" })              → one call, one result
+read({ repo: "vercel/next.js", paths: "README.md" })  → one call, one result
+```
+
+**`code` tool** — multi-step, filtering, conditional logic:
+```javascript
+// Explore → filter → read in ONE round-trip (not three)
+var repo = codemode.explore({ repo: "vercel/next.js" });
+var tsFiles = repo.files.filter(f => f.name.endsWith(".ts")).slice(0, 5);
+var contents = codemode.read({ repo: "vercel/next.js", files: tsFiles.map(f => f.name), map: true });
+return contents;
+```
+
+**Rule of thumb:** If you need the result of tool A to decide what to call for tool B → use `code`. Otherwise use direct tools.
+
+## The `code` Tool
+
+### Available API
+
+```typescript
+type ExploreInput = { repo: string; path?: string }
+type ReadInput = { repo: string; files: string[]; grep?: string; map?: boolean }
+type ReposInput = { query: string; limit?: number }
+type SearchInput = { query: string; limit?: number; fullMode?: boolean }
+type TreeInput = { repo: string; path?: string }
+
+declare const codemode: {
+  explore: (input: ExploreInput) => any;
+  read: (input: ReadInput) => any;
+  repos: (input: ReposInput) => any;
+  search: (input: SearchInput) => any;
+  tree: (input: TreeInput) => any;
+}
+```
+
+Use `search_tools` to get the latest type stubs at runtime.
+
+### Writing Code
+
+```javascript
+// ✅ Correct: plain JavaScript, synchronous calls, return a value
+var repo = codemode.explore({ repo: "dop251/goja" });
+return { branch: repo.branch, fileCount: repo.files.length };
+
+// ❌ Wrong: await (tools are synchronous, await causes transpile error)
+const r = await codemode.explore(...)  // top-level await not supported
+
+// ❌ Wrong: TypeScript syntax
+const r: ExploreResult = codemode.explore(...)  // no type annotations
+
+// ❌ Wrong: no return value
+codemode.explore({ repo: "dop251/goja" });  // result is lost
+```
+
+### Rules
+
+- Write plain JavaScript, not TypeScript (no type annotations, interfaces, generics)
+- `codemode.*` calls are synchronous — do NOT use `await`
+- Must `return` a value — the return value is what you see in the response
+- `console.log()` output appears in the response under "Console:" (useful for debugging)
+- Max 20 tool calls per execution
+- Max 64KB code size
+- Response truncated at 24K chars (use `map: true` or `grep` to reduce output)
+
+### Patterns
+
+**Explore and filter:**
+```javascript
+var repo = codemode.explore({ repo: "owner/repo" });
+var goFiles = repo.files.filter(f => f.name.endsWith(".go"));
+return goFiles.map(f => f.name);
+```
+
+**Map multiple files (understand structure before reading):**
+```javascript
+var repo = codemode.explore({ repo: "owner/repo" });
+var srcFiles = repo.files.filter(f => f.name.startsWith("src/") && f.type === "blob").slice(0, 8);
+return codemode.read({ repo: "owner/repo", files: srcFiles.map(f => f.name), map: true });
+```
+
+**Search then read matches:**
+```javascript
+var hits = codemode.search({ query: "GraphQL repo:owner/repo", limit: 5 });
+var files = hits.results.map(r => r.path);
+return codemode.read({ repo: "owner/repo", files: files });
+```
+
+**Conditional logic:**
+```javascript
+var repo = codemode.explore({ repo: "owner/repo" });
+var hasGo = repo.files.some(f => f.name === "go.mod");
+var hasPython = repo.files.some(f => f.name === "requirements.txt");
+if (hasGo) {
+  return { lang: "go", mod: codemode.read({ repo: "owner/repo", files: ["go.mod"] }) };
+} else if (hasPython) {
+  return { lang: "python", reqs: codemode.read({ repo: "owner/repo", files: ["requirements.txt"] }) };
+}
+return { lang: "unknown", files: repo.files.slice(0, 10) };
+```
+
+## Chain of Thought
+
+**Always start surgical, escalate only when needed.**
+
+```
+1. explore({ repo: "owner/repo" })                    → What's in this repo?
+2. read({ repo: "...", paths: "f1,f2", map: true })   → What do these files define? (92% fewer tokens)
+3. read({ repo: "...", paths: "f1", grep: "pattern" }) → Where exactly is X?
+4. read({ repo: "...", paths: "f1" })                  → Full file (only when needed)
+```
+
+**When to escalate to `code`:**
+- Step 1 result determines what to do in step 2 → use `code` (one round-trip)
+- Need to filter/transform results before returning → use `code`
+- Simple single query → use direct tool
+
+## Search Query Syntax
+
+Same as GitHub REST code search API. Multi-word = AND matching.
+
+**Valid qualifiers:** `repo:`, `org:`, `path:`, `filename:`, `extension:`, `language:`, `in:file`, `in:path`
+
+**DO NOT USE (web-only, silently wrong):** `OR`, `NOT`, `symbol:`, `content:`, `is:`, regex
+
+**Rate limit:** 9 req/min for code search. Refine queries, don't paginate.
+
+## Gotchas
+
+1. **`read` paths are comma-separated.** `paths: "f1.go,f2.go"` not `paths: ["f1.go", "f2.go"]`.
+2. **Response truncation at 24K chars.** Use `map: true` or `grep` to keep results small. The `code` tool is especially prone to this when reading multiple full files.
+3. **`search` uses AND matching.** `"foo bar"` finds files with both words anywhere. For exact phrase, wrap in escaped quotes: `"\"foo bar\""`.
+4. **Web-only qualifiers silently degrade.** `symbol:`, `OR`, `NOT` are treated as literal text in the REST API.
+5. **`code` tool: no TypeScript.** Type stubs are for your reference. Write plain JS.
+6. **`code` tool: return is required.** Bare expressions don't auto-return (except simple identifiers). Always use `return`.
+
+## Anti-Patterns
+
+- ❌ Three sequential tool calls when `code` can do it in one
+- ❌ Reading full files when you need 10 lines — use `grep` or `map: true`
+- ❌ Paginating broad searches — refine with `repo:`, `language:`, `path:`
+- ❌ Writing TypeScript in the `code` tool — stripped by transpiler but may cause subtle issues
+- ❌ Forgetting `return` in `code` — you get `undefined` back
+- ❌ Reading 10 full files in `code` — hits 24K truncation. Use `map: true` first

package/v2/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ghx
+description: GitHub code exploration for AI agents. CLI + codemode. One command does what takes 3-5 API calls. Write JS programs that compose operations in one round-trip.
+---
+
+# ghx — GitHub Code Exploration for AI Agents
+
+Use `ghx` via `execute_bash` for anything on GitHub — repos, files, code search, codemode. Authenticated via `gh` CLI, structured output, zero context overhead.
+
+## 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 in 1 GraphQL call
+ghx search "<query>"                        # Code search (AND matching, shows matching lines)
+ghx search --full "<query>"                 # Code search without line truncation
+ghx tree <owner/repo> [path]                # Full recursive tree listing
+ghx code "<js>"                             # Execute JS with access to all ghx tools
+ghx code -                                  # Read code from stdin
+ghx code --list                             # List available tools with type stubs
+```
+
+**Exit codes:** 0 = success, 1 = no results, 2 = usage error.
+
+## Chain of Thought: Progressive Disclosure
+
+**Start surgical, escalate only when needed.**
+
+```
+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)
+```
+
+At 92% reduction, `--map` lets you scan 7 files in the space of reading 1 full file.
+
+## When to Use `ghx code`
+
+Use direct commands for simple one-shot queries. Use `ghx code` when you need to:
+- **Chain operations** — explore → filter → read in one shot
+- **Filter results** — JS logic runs locally, not in the LLM
+- **Conditional logic** — read different files based on what you find
+
+```bash
+# Simple: use direct command
+ghx explore vercel/next.js
+
+# Complex: use ghx code (one round-trip instead of three)
+ghx code "
+  var repo = codemode.explore({ repo: 'vercel/next.js' });
+  var goFiles = repo.files.filter(f => f.name.endsWith('.go'));
+  var contents = codemode.read({ repo: 'vercel/next.js', files: goFiles.map(f => f.name) });
+  return contents;
+"
+```
+
+### Codemode API
+
+```bash
+ghx code --list   # See all available tools with type stubs
+```
+
+```typescript
+declare const codemode: {
+  explore: (input: { repo: string; path?: string }) => any;
+  read: (input: { repo: string; files: string[]; grep?: string; map?: boolean }) => any;
+  repos: (input: { query: string; limit?: number }) => any;
+  search: (input: { query: string; limit?: number; fullMode?: boolean }) => any;
+  tree: (input: { repo: string; path?: string }) => any;
+}
+```
+
+### Codemode Rules
+
+- Write plain JavaScript, not TypeScript (no type annotations)
+- `codemode.*` calls are synchronous — no `await` needed
+- Must `return` a value — bare expressions don't auto-return (except simple identifiers)
+- Must `return` a value — bare expressions don't auto-return (except simple identifiers)
+- Console output goes to stderr, return value goes to stdout
+- Max 20 tool calls per execution, 64KB code size limit
+
+## Search Query Syntax
+
+`ghx search` uses GitHub REST code search API. Multi-word = AND matching (both words anywhere in file).
+
+```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 '"exact phrase" repo:plausible/analytics'      # Exact phrase (shell quotes)
+ghx search "path:llms.txt"                                # Find files by name
+```
+
+**Valid qualifiers:** `repo:`, `org:`, `path:`, `filename:`, `extension:`, `language:`, `in:file`, `in:path`, `size:`, `fork:true`
+
+**DO NOT USE (web-only, silently wrong):** `OR`, `NOT`, `symbol:`, `content:`, `is:`, regex
+
+**Rate limit:** 9 req/min for code search. Refine queries, don't paginate.
+
+## Gotchas
+
+1. **Web-only qualifiers silently degrade.** `symbol:`, `OR`, `NOT` are treated as literal text. ghx warns on stderr.
+2. **`gh search code` wraps in quotes.** `gh search code "foo bar"` = exact phrase. `ghx search "foo bar"` = AND. Use ghx.
+3. **Flag ordering in `read`.** `ghx read owner/repo file --map` works. `ghx read --map owner/repo file` does NOT.
+4. **Not all repos use `main`.** ghx handles this automatically.
+5. **Unknown flags are rejected.** Exit 2 with clear error. Intentional — prevents silent query corruption.
+
+## Anti-Patterns
+
+- ❌ `web_fetch` on github.com — HTML noise, zero useful info
+- ❌ Reading entire large files when you need 10 lines — use `--grep` or `--lines`
+- ❌ Multiple `gh api` calls for explore — use `ghx explore` (1 call)
+- ❌ Using web-only qualifiers in search — silently wrong results
+- ❌ Paginating broad searches — refine with `repo:`, `language:`, `path:` instead
+- ❌ `gh search code` for multi-word queries — silently wraps in quotes, returns nothing
+
+## Best Practices
+
+- **Batch reads.** `ghx read repo f1 f2 f3` = 1 API call. Three separate reads = 3 calls.
+- **Map before reading.** `--map` first, then `--grep` or `--lines` for specifics.
+- **Refine search, don't paginate.** Add qualifiers instead of fetching page 2.
+- **Use `ghx code` for multi-step workflows.** One round-trip beats three sequential commands.
+- **Check exit codes.** 0 = results, 1 = no results (broaden query), 2 = usage error (fix command).

package/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/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