@gkoreli/ghx 2.0.2 → 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.2",
+  "version": "2.1.5",
   "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
   "bin": {
-    "ghx": "./ghx"
+    "ghx": "npm/bin/ghx"
   },
   "keywords": [
     "github",
@@ -16,25 +16,22 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/gkoreli/ghx"
+    "url": "git+https://github.com/gkoreli/ghx.git"
   },
   "files": [
-    "ghx",
-    "postinstall.js",
-    "v2/SKILL.md",
-    "v2/MCP-SKILL.md",
+    "npm/bin/ghx",
     "README.md",
     "LICENSE"
   ],
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
   "engines": {
     "node": ">=16"
   },
-  "scripts": {
-    "postinstall": "node postinstall.js"
+  "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/postinstall.js

@@ -1,59 +0,0 @@
-#!/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

@@ -1,175 +0,0 @@
----
-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

@@ -1,129 +0,0 @@
----
-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).