📦 ContextForge

Compile Any Repository Into Task-Aware Context Packs

"Your agent scans 400 files. It only needs 11."

---

What Is ContextForge?

You ask your coding agent to "fix the OAuth refresh bug." It reads 400 files, burns 50K tokens, and still misses the one file that matters.

ContextForge compiles your repo into a minimal context pack — the exact files needed for a specific task, with evidence for why each was included.

Result: 14K tokens instead of 120K. The agent finds the bug in 3 files instead of searching 400.

Install

pip install contextforge

Quick Start

# 1. Index your repo
contextforge index ./my-project

# 2. Create a context pack for a specific task
contextforge pack "Fix the OAuth refresh token bug" --recipe bugfix --output pack.md

# 3. Search for symbols
contextforge search "authenticate"

# 4. See codebase stats
contextforge stats ./my-project

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Your Repo   │────>│  Code Index  │────>│  Context Pack │
│  (any lang)  │     │  (symbols,   │     │  (minimal,   │
│              │     │  imports,    │     │  task-aware, │
│              │     │  deps)       │     │  token-budget)│
└──────────────┘     └──────────────┘     └──────────────┘

Commands

contextforge index <repo>          Index a codebase
  --incremental                    Only re-index changed files

contextforge pack <task>           Create a context pack
  --recipe bugfix|pr_review|refactor|docs|security|onboarding
  --max-tokens 16000               Token budget
  --target file.py                 Force-include specific files
  --output pack.md                 Output file
  --format markdown|json|text      Output format

contextforge search <query>        Search for symbols
contextforge related <file>        Show related files
contextforge stats <repo>          Show codebase statistics

Pack Recipes

Recipe	What It Includes
bugfix	Buggy file, related code, tests
pr_review	Changed files, tests, docs
refactor	Target file, all related code, tests
docs	Source code, existing docs, README
security	Auth, crypto, config, input handling
onboarding	README, entry points, key modules

Example

# Index the repo
contextforge index ./my-project
# Indexed 247 files, 1,834 symbols
# Languages: python (180), typescript (45), go (22)

# Create a pack for fixing a bug
contextforge pack "Fix null pointer in authenticate() when token expires" \
    --recipe bugfix \
    --max-tokens 8000 \
    --output context.md

# Output:
# Pack created: 11 files selected
# Compression: 4.5% of repo
# Tokens: 6,234/8,000
#
# Files:
#   auth.py (python) — 1,204 tokens — relevance: 9.2
#     Reason: Target file; Matching symbols: authenticate, verify_token
#   test_auth.py (python) — 456 tokens — relevance: 7.5
#     Reason: Test file; Keywords in path: auth
#   middleware.py (python) — 890 tokens — relevance: 5.1
#     Reason: Related to auth.py; Imported by 8 files
#   ...

Evidence-Based Selection

Every file in the pack comes with evidence:

{
  "file": "auth.py",
  "reason": "Target file; Matching symbols: authenticate, verify_token",
  "score": 9.2,
  "matched_symbols": ["authenticate", "verify_token"],
  "matched_keywords": ["auth", "token", "login"]
}

No black box. You always know why each file was included.

Multi-Language Support

ContextForge indexes Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Ruby, PHP — any language with a tree-sitter grammar. Falls back to regex for unsupported languages.

Built By

ContextForge is built by EmbrOS — the AI Builder Operating System. Apache-2.0.

⭐ Star this repo if your agent reads too many files

🐦 Twitter • 💬 Discord • 🌐 embros.xyz

---

🐦 Follow on X: @probert_mihai