DEV Community

Aishik Yadav
Aishik Yadav

Posted on

ContextForge: Resurrecting Codebase Blueprints to Slash LLM Token Waste by 90%

#devchallenge #hf26challenge #ai #opensource

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 4 — Ghost in the Machine.

👻 The "Ghost in the Machine": When Codebases Haunt the Context Window

Every modern developer working with AI has faced this dilemma:

You want an LLM (Claude 3.5, GPT-4o, Gemini, or a local open-weight model) to fix a bug, review system architecture, or implement a new feature across your codebase.

You have two choices, and both are broken:

  1. Dump the entire codebase into the prompt: You burn through 60,000 to 150,000 tokens in one shot. The model drowns in low-level loop bodies, internal array manipulations, and boilerplate. You hit context limits, pay high token bills, and face the "lost in the middle" problem where models miss critical details hidden in massive dumps.
  2. Manually cherry-pick a few snippets: The model loses the big picture. It hallucinates missing types, invents imaginary function signatures, and violates conventions established elsewhere in your project.

In honor of Hacktoberfest Week 4: "Ghost in the Machine", I wanted to summon the true spirit of a codebase without all the heavy, noisy flesh.

Meet ContextForge ⚡ — an open-source CLI and interactive local web dashboard that strips away implementation clutter, extracts structural AST signatures and type blueprints across multiple languages, budgets tokens against your target model, and formats token-efficient prompt packs that slash token consumption by 70% to 90%.

⚡ What ContextForge Does

ContextForge bridges the gap between raw codebases and LLM context windows through three core engines:

1. Multi-Language AST Signature Extractor

Instead of feeding an AI 500 lines of implementation logic for a service file, ContextForge parses the code and extracts its structural skeleton:

  • TypeScript / JavaScript: Exported interfaces, type aliases, classes, method signatures, parameter types, return types, enums, and JSDoc comments.
  • Python: Classes, methods, functions, type hints, and docstrings.
  • Go: Structs, interfaces, function signatures, and method receivers.
  • Rust: Structs, enums, traits, impl blocks, and pub fn signatures.
  • Java / C#: Classes, interfaces, and public/protected method signatures.

This gives the AI a complete, 100% accurate mental model of your system's contracts and interfaces without reading thousands of lines of internal loops.

2. Intelligent Dynamic Token Budgeting

Different models have different context windows and cost profiles. ContextForge includes built-in presets:

  • Claude 3.5 Sonnet (200k context / 64k recommended budget)
  • GPT-4o (128k context / 32k recommended budget)
  • Gemini 1.5 Pro / Flash (1M context / 128k recommended budget)
  • Llama 3 / Gemma 2 Local (8k context / 4k budget)
  • DeepSeek Coder (64k context / 24k budget)

If your codebase exceeds your chosen budget, ContextForge dynamically downsamples non-critical files to AST blueprints while keeping your core entrypoints in full code.

3. Task-Driven Prompt Templates

Context packs aren't just raw code—they are structured prompts with specialized system directives:

  • 🐛 Bug Investigation & Root Cause: Directs the model to check race conditions, null safety, and boundary states.
  • ✨ Feature Implementation Blueprint: Instructs the model to outline touched files and follow existing patterns.
  • 🏗️ Architecture & Data Flow Review: Maps domain entities, lifecycles, and scaling bottlenecks.
  • 🔒 Security & Vulnerability Audit: Audits auth boundaries, input validation, and secret exposure.
  • 🧪 Test Suite Generation: Drafts unit and integration tests covering happy paths and edge cases.

📊 The Math: 91.6% Token Reduction in Practice

Here is a real test running ContextForge against itself:

Metric Raw Full Codebase ContextForge Signatures Mode Savings
Files Scanned 18 files 18 files Complete Coverage
AST Signatures Extracted — 73 signatures Full Architecture
Estimated Tokens 64,700 tokens 5,400 tokens 91.6% reduction
Fit in Local 8k Context? ❌ No (Blows limit 8x) ✅ Yes (Only 67% of 8k) Instant local inference

By stripping inner loops and keeping types, interfaces, and function signatures, an entire multi-module codebase comfortably fits inside a local Gemma 2 (8k) or Llama 3 context window!

🏗️ Architecture & How It Works

Here is the pipeline that runs when you invoke ContextForge:

[ Codebase Directory ]
          │
          ▼
┌────────────────────────┐
│  scanner/scanner.ts    │ ◄── Respects .gitignore, ignores binary & lockfiles, builds tree
└─────────┬──────────────┘
          │
          ▼
┌────────────────────────┐
│  parser/signature.ts   │ ◄── AST/Regex signature extraction (TS, Python, Go, Rust, Java)
└─────────┬──────────────┘
          │
          ▼
┌────────────────────────┐
│  packer/packer.ts      │ ◄── Allocates token budget, downsamples to signatures, applies template
└─────────┬──────────────┘
          │
     ┌────┴───────────────────────────┐
     ▼                                ▼
┌────────────────────────┐   ┌────────────────────────┐
│  cli.ts                │   │  server/server.ts      │
│  - Terminal summary    │   │  - Glassmorphic UI     │
│  - OS Clipboard (-c)   │   │  - Live token gauges   │
│  - Export Markdown (-o)│   │  - Signature drawer    │
│  - Stream via Ollama   │   │  - Local AI playground │
└────────────────────────┘   └────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

🎨 Two Ways to Use It

1. High-Speed Terminal CLI 

# Scan current repository and view metrics
contextforge .

# Generate a bug-hunt pack with a 32k token budget and copy directly to clipboard
contextforge . -t bug -b 32000 -c

# Export architectural blueprints to Markdown
contextforge . -t architecture -m signatures -o architecture-pack.md
Enter fullscreen mode Exit fullscreen mode

2. Glassmorphic Web Dashboard (--ui)

Run contextforge --ui to launch an interactive local workspace in your browser (http://localhost:4567):

  • Visual File Tree: Toggle individual files between Full, Blueprint / Signatures, or Exclude.
  • AST Signature Inspector: Click the ⚡ badge on any file to open a drawer and inspect parsed methods and types.
  • Dynamic Context Gauges: Live progress bar showing budget utilization against Claude, GPT-4o, and Gemma.
  • Local Ollama Studio: Send prompt packs directly to locally running open-weight models with real-time streaming output and tokens/sec metrics.

🔒 Why Open-Source AI Matters Here

When building developer tools that inspect codebases, privacy is non-negotiable:

  1. Zero Intellectual Property Leakage: Feeding company codebases or private repos into third-party cloud APIs poses proprietary risks. With ContextForge and local Ollama inference, not a single line of code ever leaves your laptop.
  2. Cost-Free Scalability: You can generate dozens of context packs and run local queries all day without worrying about API rate limits or surprise bills.
  3. Offline Reliability: Whether you are on an airplane, train, or disconnected from the internet, your local synthesizer and model keep working seamlessly.

🚀 Quickstart: Try It Yourself

1. Prerequisites

  • Node.js: v18.0.0 or higher (v20+ recommended)
  • (Optional) Ollama for local AI generation: 
  ollama pull gemma2:2b
  ollama serve
Enter fullscreen mode Exit fullscreen mode

2. Clone & Install 

git clone https://github.com/sleepyaishik69/contextforge.git
cd contextforge
npm install
npm run build
Enter fullscreen mode Exit fullscreen mode

3. Run It 

# Launch the Web Dashboard
npm run ui

# Or generate a prompt pack from terminal:
node dist/cli.js . -t bug -c
Enter fullscreen mode Exit fullscreen mode

🏆 Prize Category

This project is entered into:

  • Best Use of Gemma ($200 featured category): ContextForge is specifically designed to make complex codebases fit within compact open-weight models like Google's gemma2:2b. By condensing bloated code into high-density AST blueprints, Gemma can understand and reason about entire repositories that would otherwise exceed its context window!

📚 Related Community Reading

Top comments (0)