Features How it works Architecture Roadmap GitHub
Open Source · MIT Licensed

Stop guessing
which files matter.

ContextForge scans your repository, scores every file by relevance to your task, and outputs a token-efficient context bundle. One command. No API keys. Runs locally.

Coming Soon Star on GitHub
contextforge
$   Scanning repository… 847 files indexed Ranking files by relevance…   ✓ src/middleware/auth.ts score: 0.97 2.1k tokens ✓ src/middleware/rateLimiter.ts score: 0.91 1.4k tokens ✓ src/config/limits.ts score: 0.83 0.6k tokens ✓ src/types/auth.d.ts score: 0.78 0.8k tokens ✗ src/ui/components/** score: 0.02 skipped   Compressing to fit 50k token budget…   ⚡ Context ready — 4,900 tokens (saved 83%) → Copied to clipboard

Roadmap

Shipping fast. Staying focused.

Four phases over one month. Community feedback shapes every milestone.

Phase 1

Core

August 1 - August 8
  • Repo scanner with gitignore
  • Keyword relevance scoring
  • Token budget enforcement
  • Output to stdout / clipboard / file
Phase 2

Intelligence

August 9 - August 16
  • Import graph analysis
  • Git-aware context
  • AST-aware compression
  • Interactive terminal UI
Phase 3

Extensibility

August 17 - August 24
  • Profile system
  • Plugin architecture
  • Multi-language AST
  • Config file support
Phase 4

Polish

August 25 - September 1
  • VitePress docs site
  • VS Code extension
  • GitHub Actions integration
  • v1.0.0 release

The problem

Every AI coding session starts with the same friction.

You need AI help with a task. So you start copying files. One by one. Guessing which ones are relevant. Hoping you stay within the token limit.

01

Manual file hunting

Digging through your repo, guessing which files matter, copy-pasting them one by one into your prompt.

02

Wasted tokens

Sending irrelevant code that blows past limits, costing money and degrading your AI assistant's response quality.

03

No standardization

Every developer builds context differently. No shared process for how teams structure context for AI tools.

The solution

One command. Done.

Describe your task in plain English. ContextForge indexes your repo, scores every file, compresses to fit your token budget, and outputs a ready-to-use context bundle.

Your Task

Plain English description

Index

Scan repo & build graph

Rank

Score files by relevance

Compress

AST-aware trimming

Output

Clipboard, file, or pipe

How it works

Three commands to try it out.

No accounts. No API keys. No cloud. Everything runs on your machine.

1

Install globally

Install the beta version to start building locally.

install
$ npm install -g contextforge@beta added 47 packages in 3.2s
2

Index your repo

Scans your codebase, builds a dependency graph, and caches the index.

init
$ cf init && cf scan ✓ Created .contextforge/ ✓ Indexed 847 files ✓ Built dependency graph (1,203 edges) ✓ Cached to .contextforge/cache.json
3

Build context

Describe your task. Get a token-optimized bundle, ready to paste.

build
$ cf build "fix the login bug" --copy ✓ 6 files selected (4,200 tokens) ⚡ Copied to clipboard

Core features

Everything you need. Nothing you don't.

Built for developers who use AI assistants daily.

Relevance Engine

Ranks every file using keyword matching, import graph proximity, git recency, and file type heuristics.

Token Budget

Auto-compresses context with AST-aware trimming. Strips comments, extracts signatures, or summarizes — always within your limit.

Output Modes

Print to stdout, copy to clipboard, save to file, output as JSON, or pipe to another command.

Interactive Mode

Preview included files, toggle them on or off, and watch the token counter update in real time.

Git-Aware

Build context from your current diff, staged files, or a specific commit hash.

Plugin System

Extend with custom relevance scorers, output formatters, and file parsers.

CLI examples

Built for the terminal.

Composable commands for any workflow.

basic usage
# Build context and copy to clipboard $ cf build "fix the cart calculation bug" --copy ✓ src/cart/calculations.ts score: 0.95 1.8k tokens ✓ src/cart/types.ts score: 0.87 0.4k tokens ✓ src/cart/hooks/useCart.ts score: 0.82 1.1k tokens ⚡ Context ready — 3,300 tokens → Copied to clipboard # Save context to a file $ cf build "refactor payment module" --out context.md ⚡ Context ready — 8,100 tokens → Saved to context.md
token budget
# Set a model preset with custom budget $ cf build "add rate limiting" --model claude-sonnet --budget 50000 Model: claude-sonnet (200k max) Budget: 50,000 tokens ✓ src/middleware/auth.ts full 2.1k tokens ✓ src/middleware/rateLimit.ts full 1.4k tokens ✓ src/config/limits.ts trimmed 0.3k tokens ✓ src/types/auth.d.ts signatures 0.2k tokens ⚡ Context ready — 4,000 tokens (budget: 92% remaining)
git integration
# Context from current branch diff $ cf build "review my changes" --diff Comparing: feature/auth-refactor → main ✓ 4 files changed, 127 insertions(+), 43 deletions(-) ⚡ Context ready — 2,800 tokens # Context around a specific commit $ cf build "explain this commit" --commit a3f9c21 Commit: a3f9c21 "refactor auth middleware" ✓ 3 files in commit scope ⚡ Context ready — 1,900 tokens # Only staged files $ cf build "review before commit" --staged
interactive mode
$ cf build "add user search" --interactive Token budget: 50,000 Use ↑↓ to navigate, space to toggle, enter to confirm [✓] src/api/users.ts 2.1k tokens [✓] src/api/search.ts 1.6k tokens [✓] src/types/user.ts 0.4k tokens [ ] src/api/admin.ts 3.2k tokens [ ] src/utils/validators.ts 0.8k tokens Selected: 3 files · 4,100 tokens
profiles
# Save a reusable profile $ cf profile save backend --include "src/api/**" --exclude "src/ui/**" ✓ Profile "backend" saved # Use the profile $ cf build "add new endpoint" --profile backend Profile: backend Include: src/api/**, src/middleware/** Exclude: src/ui/** ✓ 8 files selected ⚡ Context ready — 6,400 tokens

Architecture

Built with proven tools. No unnecessary abstractions.

TypeScript from top to bottom. Every module is focused, testable, and replaceable.

  • Recursive scanner that respects .gitignore
  • In-memory dependency graph from imports
  • AST-aware compression via tree-sitter
  • Cached index for sub-second rebuilds
  • Plugin loader with sandboxed execution
project structure
contextforge/ ├── src/ │ ├── cli/ # Command definitions │ ├── scanner/ # Repo indexing │ ├── relevance/ # Scoring engine │ ├── compression/ # Token budget logic │ ├── output/ # Output formatters │ ├── interactive/ # Ink components │ ├── plugins/ # Plugin registry │ ├── git/ # Git integration │ └── utils/ # Shared utilities ├── tests/ ├── docs/ ├── .contextforge/ # Per-project config └── package.json

Tech stack

RuntimeNode.js 20+
LanguageTypeScript
CLI FrameworkCommander.js
Terminal UIInk
AST Parsingtree-sitter
Token Countingtiktoken
CachingLevelDB
TestingVitest

Open source

Open source. Forever free.

ContextForge is MIT licensed. No telemetry, no accounts, no data collection. Read the code, contribute features, or fork it for your own workflow.

View on GitHub Contributing Guide
.contextforge.config.json
{ "defaultModel": "claude-sonnet", "defaultBudget": 80000, "ignore": [ "node_modules", "dist", "*.test.ts" ], "profiles": { "backend": { "include": ["src/api/**"], "exclude": ["src/ui/**"] } } }

FAQ

Common questions.

No. ContextForge prepares context for you to use with any AI assistant — Claude, GPT-4, Gemini, or anything else. It never makes API calls. All processing runs locally.

No. Everything runs locally on your machine. No telemetry, no accounts, no cloud, no data collection. Your code never leaves your machine.

JavaScript, TypeScript, and Python are supported out of the box with full AST-aware compression. Go, Rust, and Java support is planned for Phase 3. Basic keyword relevance works with any text file.

It combines five signals: keyword matching, import graph proximity, git recency, file type weighting, and directory heuristics. Each signal contributes to a composite relevance score per file.

Yes. Commit .contextforge.config.json to your repository. Team members run cf scan after cloning, and everyone shares the same profiles, ignore rules, and settings.

Coming soon

Ready to build better context?

Install ContextForge and go from task to token-optimized context in seconds.

View on GitHub