@gkoreli/ghx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goga Koreli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# ggcode
+
+GitHub code exploration for agents and humans. One command does what takes 3-5 API calls with any other tool.
+
+- **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 full GitHub search syntax
+
+~135 lines of bash. One dependency: `gh` CLI.
+
+## Install
+
+```bash
+# Homebrew (macOS/Linux)
+brew install gkoreli/tap/ggcode
+
+# gh extension (coming soon — requires separate gh-ggcode repo)
+gh extension install gkoreli/gh-ggcode
+
+# npx (zero install)
+npx ggcode --help
+
+# curl
+curl -sf https://raw.githubusercontent.com/gkoreli/ggcode/main/install.sh | sh
+
+# Manual — just copy the script
+curl -sf https://raw.githubusercontent.com/gkoreli/ggcode/main/ggcode -o ~/.local/bin/ggcode && chmod +x ~/.local/bin/ggcode
+```
+
+Requires [`gh` CLI](https://cli.github.com/) authenticated (`gh auth login`).
+
+## Usage
+
+```bash
+# Explore a repo — branch, file tree, and README in 1 API call
+ggcode explore plausible/analytics
+
+# Read multiple files in 1 API call
+ggcode read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js
+
+# Code map — signatures, imports, types only (~92% token reduction)
+ggcode read plausible/analytics --map lib/plausible/stats/query.ex
+
+# Grep within a remote file (2 lines context)
+ggcode read plausible/analytics --grep "defmodule" lib/plausible/stats/query.ex
+
+# Read specific line range
+ggcode read plausible/analytics --lines 42-80 lib/plausible/stats/query.ex
+
+# Search code (full GitHub search syntax)
+ggcode search "useState repo:facebook/react"
+ggcode search "path:llms.txt extension:txt"
+
+# Full recursive tree
+ggcode tree plausible/analytics assets/js
+```
+
+## Why
+
+AI agents exploring GitHub repos face a tooling gap:
+
+| Tool | Files per API call | Context overhead | Dependencies |
+|------|-------------------|-----------------|-------------|
+| GitHub MCP | 1 | ~10K tokens (50+ tool schemas) | Go binary |
+| Octocode MCP | 1 (parallel) | ~10K tokens | npm + Docker |
+| Raw `gh` CLI | 1 | 0 | `gh` |
+| Gitingest | N (clones first) | 0 | pip + tiktoken |
+| **ggcode** | **1-10 (GraphQL batch)** | **0** | **`gh`** |
+
+`ggcode` reads 10 files in 1 API call. No other tool does this.
+
+## Code Map (`--map`)
+
+The `--map` flag extracts only structural declarations — imports, exports, function signatures, class definitions, type declarations. Implementation bodies are stripped.
+
+Tested on 6 real files across TypeScript, Python, and Go:
+
+| File | Full | Map | Reduction |
+|------|------|-----|-----------|
+| repomix/parseFile.ts | 5,599 | 812 | 86% |
+| github-mcp/repositories.go | 68,862 | 1,551 | 97.7% |
+| aider/repomap.py | 27,346 | 1,496 | 94.5% |
+
+Average: **92% reduction**. An agent can map 16 files in the space of reading 1 file fully.
+
+Supported: TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin, Ruby. Falls back to generic pattern for unknown extensions.
+
+## How It Works
+
+`ggcode` wraps `gh` CLI with GraphQL batching. The `explore` command fetches tree + README in 1 GraphQL call. The `read` command uses GraphQL aliases (`f0:`, `f1:`, ...) to fetch up to 10 files in 1 call. The `search` command hits the REST `/search/code` endpoint directly (GraphQL has no code search).
+
+The `--map` flag applies per-language regex patterns to extract structural declarations from the fetched content. No Tree-sitter, no AST parsing — just regex on the first line of each declaration. This works because structural declarations in most languages start at the beginning of a line with a keyword (`function`, `class`, `def`, `func`, `export`, `import`, etc.).
+
+## License
+
+MIT
+
+## For AI Agents
+
+See [`SKILL.md`](./SKILL.md) for agent-optimized instructions — chain of thought, gotchas, anti-patterns, and examples.

package/ggcode

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# ggcode — 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
+
+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 ;;
+      *) files+=("$1"); shift ;;
+    esac
+  done
+
+  if [[ ${#files[@]} -eq 0 ]]; then
+    echo "Usage: ggcode read <owner/repo> <path1> [path2] [--grep pattern] [--lines N-M]" >&2
+    exit 1
+  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 (supports full query syntax) ───
+search)
+  query="$*"
+  if [[ -z "$query" ]]; then
+    echo "Usage: ggcode search <query>" >&2
+    echo "Query syntax: 'term1 term2 repo:owner/repo' (AND), 'term1 OR term2 repo:owner/repo'" >&2
+    echo "Filters: path:src/ extension:tsx language:typescript" >&2
+    exit 1
+  fi
+  gh api /search/code --method GET -f q="$query" --jq '.items[] | "\(.repository.full_name) \(.path):\(.name)"'
+  ;;
+
+# ─── 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 ───
+help|*)
+  cat <<'EOF'
+ggcode — GitHub code exploration for agents and humans
+
+Commands:
+  ggcode explore <owner/repo> [path]     Branch + tree + README in 1 API call
+  ggcode read <owner/repo> <f1> [f2..]   Read 1-10 files in 1 API call
+  ggcode search <query>                   Code search (full syntax: AND, OR, path:, extension:, language:)
+  ggcode 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
+
+Examples:
+  ggcode explore plausible/analytics
+  ggcode read plausible/analytics mix.exs assets/js/dashboard/stats/bar.js
+  ggcode read plausible/analytics src/app.ts --grep "useState"
+  ggcode read plausible/analytics src/app.ts --lines 42-80
+  ggcode search "useState repo:plausible/analytics"
+  ggcode search "bar OR percentage repo:plausible/analytics"
+  ggcode tree plausible/analytics assets/js
+EOF
+  ;;
+
+esac

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@gkoreli/ghx",
+  "version": "0.1.0",
+  "description": "GitHub code exploration for agents and humans. Batch file reads, code maps, search — all via gh CLI.",
+  "bin": {
+    "ghx": "./ggcode"
+  },
+  "keywords": ["github", "cli", "code-exploration", "agent", "graphql", "code-map"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gkoreli/ggcode"
+  },
+  "files": ["ggcode", "README.md", "LICENSE"],
+  "os": ["darwin", "linux"],
+  "engines": {
+    "node": ">=16"
+  }
+}