Repo Context Packager

• 

  Automated test suite (10/10 passing) verifying scanner logic, ranker tie-breakers, and whole-file token budget enforcement.

• 

  Execution output demonstrating task-aware keyword matching, whole-file token budgeting, and explicit selection reasons.

Inspiration

When working with AI coding assistants on complex codebases, dumping entire repositories wastes valuable token budgets, exceeds context windows, and dilutes AI accuracy with boilerplate noise. Existing tools often require cloud uploads or complex integrations. We wanted a lightweight, zero-dependency local CLI that instantly packages only the code that matters for a specific task.

What It Does

Repo Context Packager is a local TypeScript CLI that scans codebases, ranks task-relevant files using explainable heuristics, and packs optimal context windows for LLM coding workflows.

• Task & Git-Aware Scanning: Automatically reads local files while detecting Git changes and modified neighbor files.
• Explainable Scoring: Ranks files based on task keyword matches, structural entry points, and recent changes, attaching explicit inclusion reasons to each file.
• Whole-File Token Budgeting: Enforces a strict ~4 chars/token budget, including complete files up to a --max-tokens limit and generating a clean omission report for dropped files.
• Flexible Export: Generates structured Markdown (.context-pack.md) or clean JSON (.context-pack.json) ready for direct LLM prompting or pipeline automation.

How We Built It

• Tech Stack: Built with TypeScript, Node.js native modules, and Git CLI integration.
• Architecture: Designed around a clean modular pipeline:
  1. src/cli.ts: Argument parsing, validation, and execution flow.
  2. src/scanner.ts: Directory traversal and .gitignore filtering.
  3. src/ranker.ts: Heuristic scoring and tie-breaker logic.
  4. src/packager.ts: Whole-file token budgeting and omission reporting.
  5. src/formatters.ts: Markdown and JSON rendering.
• Testing & Rigor: Validated with a robust unit test suite (10/10 tests passing) and real-world terminal smoke tests.

Challenges We Faced

Balancing token efficiency with code integrity was a primary challenge. Rather than truncating source files mid-function—which corrupts syntax and confuses LLMs—we designed a whole-file inclusion strategy with a hard token budget cap and explicit omission reporting. We also refined our ranking heuristics to ensure task keywords properly override structural boilerplate files.

What We Learned

Turning concrete user observations during terminal tests into observable acceptance rules and focused regression tests significantly accelerated our development velocity and guaranteed robust edge-case handling (such as handling extremely low token caps or missing target directories).

Built With

• ai
• cli
• git
• github-copilot
• llm
• node.js
• typescript