Skip to content

Instantly share code, notes, and snippets.

@loftwah

loftwah/grabitsh.md

Created September 3, 2025 14:18
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save loftwah/4561fb4aa884936ee299a117031a3b9f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save loftwah/4561fb4aa884936ee299a117031a3b9f to your computer and use it in GitHub Desktop.
Download ZIP
grabitsh-plan
Raw
grabitsh.md

grabit – Repo Index & Q/A Tool (2025 Plan)

Overview

grabit is a self-contained Go binary that:

  • Indexes a local folder or shallow-cloned GitHub repo
  • Chunks source files into manageable blocks
  • Embeds those blocks using OpenAI embeddings
  • Stores an on-disk index (.grabit/)
  • Lets you run semantic search or ask natural language questions against the repo
  • Answers are powered by OpenAI’s Responses API with Retrieval-Augmented Generation (RAG)

This gives you a local “chat with your codebase” workflow that’s portable, fast, and easy to run.

Requirements

  • Go 1.22+
  • git (only if using --repo mode for shallow clone)
  • Environment variable:
    • OPENAI_API_KEY (required)

Optional:

  • GITHUB_TOKEN (higher API rate limits if you extend for GitHub API usage)

Default Models (2025)

  • Responses / Q&A:
    • gpt-4o (balanced), or
    • o3-mini (stronger reasoning, higher cost)
  • Embeddings:
    • text-embedding-3-large (best recall, 3072-dim)
    • text-embedding-3-small (cheaper, 1536-dim, optional)

CLI Commands

grabit index --path .          # Index current repo
grabit index --repo https://github.com/org/repo
grabit search "rate limiter"   # Semantic search
grabit ask "How does auth work?"  # Ask with RAG
grabit map                     # Show file types & index stats

Pipeline

1. File Discovery

  • Walk repo
  • Include extensions: .go, .rb, .py, .ts, .js, .java, .c, .cpp, .rs, .sql, .yaml, .json, etc.
  • Exclude dirs: .git, node_modules, dist, build, venv, etc.
  • Skip >5MB files

2. Chunking

  • ~700 bytes per chunk
  • ~120 byte overlap
  • Tracks file + line ranges for citations

3. Embedding

  • Use text-embedding-3-large
  • Batch API calls (default 64 per batch)
  • Save vectors alongside text chunks

4. Storage

  • .grabit/index.jsonl → newline JSON (chunks + vectors)
  • .grabit/meta.json → model + repo metadata

5. Retrieval

  • Query → embed → cosine similarity over chunks
  • Top-K (default 12) returned

6. Prompt Assembly

  • Include selected chunks in context:

    • FILE: path LINES: start-end
    • Snippet text

  • Guard against max token budget

  • Instruction: “Answer strictly from context; if not present, say so”

7. Answer

  • Responses API (/v1/responses)
  • Model = gpt-4o (default, overridable via --model)

Roadmap / Enhancements

  • Parallel embedding worker pool
  • Smarter chunking (AST-based for Go/Ruby)
  • Hybrid retrieval (keyword + embedding)
  • SQLite w/ sqlite-vec for faster search
  • Citations in answers (file + line refs)
  • Streaming responses for better UX
  • RAG eval harness (measure groundedness)

Usage Pattern

  1. User installs binary

  2. Exports API key:

    export OPENAI_API_KEY=sk-...

  3. Runs grabit index --path .

  4. Runs grabit ask "Where are rate limits enforced?"

  5. Gets answer + context citations

Notes

  • Designed to be portable: single binary, no extra DB
  • OpenAI key is the only dependency
  • Extensible: can later plug into FAISS, pgvector, or SQLite
  • Works offline after indexing except for OpenAI calls
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment