@gkoreli/ghx 0.2.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +76 -81
  2. package/package.json +21 -5
  3. package/v1/README.md +74 -0
  4. /package/{SKILL.md → v1/SKILL.md} +0 -0
  5. /package/{ghx → v1/ghx} +0 -0
package/README.md CHANGED
@@ -1,122 +1,117 @@
1
- # ghx
1
+ # ghx — GitHub Code Exploration for AI Agents
2
2
 
3
- GitHub code exploration for agents and humans. One command does what takes 3-5 API calls with any other tool.
3
+ 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.
4
4
 
5
- - **Repos** — search repos with README preview in 1 GraphQL call
6
- - **Explore** a repo (tree + README) in 1 API call
7
- - **Read** 1-10 files in 1 API call via GraphQL batching
8
- - **Map** code structure with ~92% token reduction
9
- - **Search** code with AND matching, matching context, token protection
5
+ ## Why
6
+
7
+ 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."
10
8
 
11
- Bash script. One dependency: `gh` CLI. Cross-platform (macOS, Linux, Windows via Git Bash/WSL).
9
+ ghx eliminates this by encoding the right defaults into every command. One call returns enough context to decide the next action.
10
+
11
+ | Tool | Files per call | Matching context | Programmable | Dependencies |
12
+ |------|---------------|-----------------|-------------|-------------|
13
+ | GitHub MCP | 1 | No | No (~10K token schemas) | Go binary |
14
+ | `gh` CLI | 1 | No | No (exact phrase, base64, no README) | `gh` |
15
+ | **ghx** | **1-10 (batch)** | **Yes** | **Yes (codemode)** | **`gh`** |
12
16
 
13
17
  ## Install
14
18
 
15
19
  ```bash
16
- # npm (recommended)
17
- npm install -g @gkoreli/ghx
20
+ # Build from source
21
+ cd v2 && go build -o ghx .
18
22
 
19
- # npx (zero install)
20
- npx @gkoreli/ghx --help
23
+ # Homebrew
24
+ brew install gkoreli/tap/ghx
21
25
 
22
- # curl
23
- curl -sf https://raw.githubusercontent.com/gkoreli/ghx/main/install.sh | sh
26
+ # One-liner
27
+ curl -sfL https://raw.githubusercontent.com/gkoreli/ghx/mainline/install.sh | bash
24
28
  ```
25
29
 
26
- Requires [`gh` CLI](https://cli.github.com/) authenticated (`gh auth login`).
27
-
28
- [![npm](https://img.shields.io/npm/v/@gkoreli/ghx)](https://www.npmjs.com/package/@gkoreli/ghx)
29
-
30
- ### Platform Support
31
-
32
- | Platform | Status | Notes |
33
- |----------|--------|-------|
34
- | macOS | ✅ Native | bash + readlink -f (12.3+) |
35
- | Linux | ✅ Native | bash + GNU coreutils |
36
- | Windows | ✅ Git Bash / WSL | Ships with Git for Windows. Raw cmd.exe/PowerShell not supported |
30
+ Requires: [gh CLI](https://cli.github.com/) authenticated (`gh auth login`).
37
31
 
38
- If you have `gh` CLI working, ghx works too — same prerequisites.
39
-
40
- ## Usage
32
+ ## Commands
41
33
 
42
34
  ```bash
43
- # Search repos — name, stars, language, README preview in 1 call
44
- ghx repos "react state management"
45
- ghx repos "playwright mcp" --limit 5
35
+ ghx explore <owner/repo> # Branch + tree + README in 1 API call
36
+ ghx explore <owner/repo> <path> # Subdirectory listing
37
+ ghx read <owner/repo> <f1> [f2] [f3] # Read 1-10 files (GraphQL batching)
38
+ ghx search "<query>" # Code search with matching lines
39
+ ghx repos "<query>" # Repo search with README preview
40
+ ghx tree <owner/repo> [path] # Full recursive tree
41
+ ```
46
42
 
47
- # Explore a repo — branch, file tree, and README in 1 API call
48
- ghx explore plausible/analytics
43
+ ## Codemode
49
44
 
50
- # Read multiple files in 1 API call
51
- ghx read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js
45
+ 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.
52
46
 
53
- # Code map — signatures, imports, types only (~92% token reduction)
54
- ghx read plausible/analytics --map lib/plausible/stats/query.ex
47
+ ```bash
48
+ # What branch is this repo on?
49
+ ghx code 'var r = codemode.explore({repo: "vercel/next.js"}); return r.branch;'
55
50
 
56
- # Grep within a remote file (2 lines context)
57
- ghx read plausible/analytics --grep "defmodule" lib/plausible/stats/query.ex
51
+ # Search + read composition
52
+ ghx code 'var hits = codemode.search({query: "useState repo:vercel/next.js", limit: 3});
53
+ var first = codemode.read({repo: "vercel/next.js", files: [hits.matches[0].path]});
54
+ return {file: hits.matches[0].path, lines: first[0].content.split("\n").length};'
58
55
 
59
- # Read specific line range
60
- ghx read plausible/analytics --lines 42-80 lib/plausible/stats/query.ex
56
+ # See what tools and types are available
57
+ ghx code --list
58
+ ```
61
59
 
62
- # Search code (AND matching, shows matching lines, token-protected)
63
- ghx search "useState repo:facebook/react"
64
- ghx search "path:llms.txt extension:txt" --limit 10
60
+ Type stubs tell the LLM exactly what fields exist — no guessing:
65
61
 
66
- # Full recursive tree
67
- ghx tree plausible/analytics assets/js
62
+ ```typescript
63
+ declare const codemode: {
64
+ explore: (input: ExploreInput) => { description: string; branch: string; files: { name: string; type: string }[]; readme: string };
65
+ search: (input: SearchInput) => { total: number; incomplete: boolean; matches: { repo: string; path: string; fragment: string }[] };
66
+ tree: (input: TreeInput) => string[];
67
+ // ...
68
+ }
68
69
  ```
69
70
 
70
- ## Why
71
-
72
- 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.
71
+ ## MCP Server
73
72
 
74
- | Tool | Files per call | Matching context | Smart defaults | Dependencies |
75
- |------|---------------|-----------------|---------------|-------------|
76
- | GitHub MCP | 1 | No | No (~10K token schemas) | Go binary |
77
- | `gh` CLI | 1 | No | No (exact phrase, base64, no README) | `gh` |
78
- | **ghx** | **1-10 (batch)** | **Yes** | **Yes** | **`gh`** |
73
+ ```bash
74
+ ghx serve # stdio (for Claude, Cursor, etc.)
75
+ ghx serve --http :8080 # HTTP transport
76
+ ```
79
77
 
80
- ## Agent Skill Integration
78
+ 7 tools: `explore`, `read`, `search`, `repos`, `tree`, `code` (meta-tool), `search_tools`.
81
79
 
82
- `ghx skill` outputs the full [`SKILL.md`](./SKILL.md) to stdout — designed for eager context injection via spawn hooks:
80
+ ## Agent Integration
83
81
 
84
- ```json
85
- {
86
- "hooks": {
87
- "agentSpawn": [
88
- {"command": "ghx skill"}
89
- ]
90
- }
91
- }
82
+ ```bash
83
+ ghx skill # CLI skill (for SKILL.md injection)
84
+ ghx skill --mcp # MCP skill
92
85
  ```
93
86
 
94
- 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.
87
+ Designed for eager context injection via spawn hooks — the agent always has the latest ghx knowledge without loading it mid-conversation.
95
88
 
96
- SKILL.md is included in the npm package and resolved via symlink, so this works with all installation methods.
89
+ ## How It Works
97
90
 
98
- ## Code Map (`--map`)
91
+ 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.
99
92
 
100
- The `--map` flag extracts only structural declarations — imports, exports, function signatures, class definitions, type declarations. Implementation bodies are stripped.
93
+ 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.
101
94
 
102
- | File | Full | Map | Reduction |
103
- |------|------|-----|-----------|
104
- | repomix/parseFile.ts | 5,599 | 812 | 86% |
105
- | github-mcp/repositories.go | 68,862 | 1,551 | 97.7% |
106
- | aider/repomap.py | 27,346 | 1,496 | 94.5% |
95
+ ## Architecture
107
96
 
108
- Average: **92% reduction**. An agent can map 16 files in the space of reading 1 file fully.
97
+ ```
98
+ v2/
99
+ ├── pkg/ghx/ — core library (Explore, Read, Search, Repos, Tree)
100
+ ├── pkg/codemode/ — JS executor (goja sandbox, TS transpilation, type generation)
101
+ └── cmd/ — CLI frontend (cobra) + MCP server (mcp-go)
102
+ ```
109
103
 
110
- Supported: TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin, Ruby. Generic fallback for unknown extensions.
104
+ See [docs/adr/](docs/adr/) for architectural decisions.
111
105
 
112
- ## How It Works
106
+ ## v1 (bash)
113
107
 
114
- `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.
108
+ 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.
109
+
110
+ ```bash
111
+ npm install -g @gkoreli/ghx # npm
112
+ cp v1/ghx /usr/local/bin/ghx # manual
113
+ ```
115
114
 
116
115
  ## License
117
116
 
118
117
  MIT
119
-
120
- ## For AI Agents
121
-
122
- See [`SKILL.md`](./SKILL.md) for agent-optimized instructions — chain of thought, gotchas, anti-patterns, and examples.
package/package.json CHANGED
@@ -1,18 +1,34 @@
1
1
  {
2
2
  "name": "@gkoreli/ghx",
3
- "version": "0.2.1",
3
+ "version": "2.0.0",
4
4
  "description": "GitHub code exploration for agents and humans. Batch file reads, code maps, search — all via gh CLI.",
5
5
  "bin": {
6
- "ghx": "./ghx"
6
+ "ghx": "./v1/ghx"
7
7
  },
8
- "keywords": ["github", "cli", "code-exploration", "agent", "graphql", "code-map"],
8
+ "keywords": [
9
+ "github",
10
+ "cli",
11
+ "code-exploration",
12
+ "agent",
13
+ "graphql",
14
+ "code-map"
15
+ ],
9
16
  "license": "MIT",
10
17
  "repository": {
11
18
  "type": "git",
12
19
  "url": "https://github.com/gkoreli/ghx"
13
20
  },
14
- "files": ["ghx", "SKILL.md", "README.md", "LICENSE"],
15
- "os": ["darwin", "linux", "win32"],
21
+ "files": [
22
+ "v1/ghx",
23
+ "v1/SKILL.md",
24
+ "README.md",
25
+ "LICENSE"
26
+ ],
27
+ "os": [
28
+ "darwin",
29
+ "linux",
30
+ "win32"
31
+ ],
16
32
  "engines": {
17
33
  "node": ">=16"
18
34
  }
package/v1/README.md ADDED
@@ -0,0 +1,74 @@
1
+ # ghx v1 — Bash Implementation
2
+
3
+ > For the current Go version with codemode, MCP server, and typed stubs, see the [root README](../README.md).
4
+
5
+ The bash implementation — zero dependencies beyond `gh` CLI. Useful if you want a single shell script you can drop anywhere without compiling Go.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ # npm
11
+ npm install -g @gkoreli/ghx
12
+
13
+ # npx (zero install)
14
+ npx @gkoreli/ghx --help
15
+
16
+ # curl
17
+ curl -sf https://raw.githubusercontent.com/gkoreli/ghx/mainline/v1/install.sh | sh
18
+
19
+ # manual
20
+ cp v1/ghx /usr/local/bin/ghx
21
+ ```
22
+
23
+ Requires [`gh` CLI](https://cli.github.com/) authenticated (`gh auth login`).
24
+
25
+ ### Platform Support
26
+
27
+ | Platform | Status | Notes |
28
+ |----------|--------|-------|
29
+ | macOS | ✅ Native | bash + readlink -f (12.3+) |
30
+ | Linux | ✅ Native | bash + GNU coreutils |
31
+ | Windows | ✅ Git Bash / WSL | Ships with Git for Windows |
32
+
33
+ ## Usage
34
+
35
+ ```bash
36
+ ghx repos "react state management" # Search repos with README preview
37
+ ghx explore plausible/analytics # Branch + tree + README in 1 API call
38
+ ghx read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js # Batch read
39
+ ghx read plausible/analytics --map lib/plausible/stats/query.ex # Code map (~92% reduction)
40
+ ghx read plausible/analytics --grep "defmodule" lib/plausible/stats/query.ex
41
+ ghx read plausible/analytics --lines 42-80 lib/plausible/stats/query.ex
42
+ ghx search "useState repo:facebook/react" # Code search with matching lines
43
+ ghx tree plausible/analytics assets/js # Full recursive tree
44
+ ```
45
+
46
+ ## Code Map (`--map`)
47
+
48
+ Extracts only structural declarations — imports, exports, function signatures, class definitions, type declarations. Implementation bodies are stripped.
49
+
50
+ | File | Full | Map | Reduction |
51
+ |------|------|-----|-----------|
52
+ | repomix/parseFile.ts | 5,599 | 812 | 86% |
53
+ | github-mcp/repositories.go | 68,862 | 1,551 | 97.7% |
54
+ | aider/repomap.py | 27,346 | 1,496 | 94.5% |
55
+
56
+ Average: **92% reduction**. Map 16 files in the space of reading 1 file fully.
57
+
58
+ Supported: TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin, Ruby. Generic fallback for unknown extensions.
59
+
60
+ ## How It Works
61
+
62
+ 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.
63
+
64
+ ## Agent Skill
65
+
66
+ ```bash
67
+ ghx skill # outputs SKILL.md to stdout
68
+ ```
69
+
70
+ See [`SKILL.md`](./SKILL.md) for agent-optimized instructions.
71
+
72
+ ## License
73
+
74
+ MIT
/package/{SKILL.md → v1/SKILL.md} RENAMED
File without changes
/package/{ghx → v1/ghx} RENAMED
File without changes