Forge

Forge is a pre-launch context preparation tool for AI coding assistants. Before you run claude, codex, or cursor, Forge scans your repository, extracts symbols and dependencies, builds a structured summary, injects configurable behavior instructions, and passes the optimized context to the AI tool through environment variables and MCP tools.

Core Philosophy

[!IMPORTANT] Forge optimizes what it controls.

Forge focuses on three areas:

• Repository Intelligence — Symbol extraction, dependency analysis, file scanning, and semantic ranking.
• Behavior Optimization — Configurable implementation guidance (PromptForge YAGNI rules) and response style optimization (ResponseForge conciseness rules).
• Runtime Infrastructure — Zero-configuration wrappers, context caching, background daemon, and MCP server.

Forge prepares context before the AI session begins. It does not modify provider billing, quota accounting, model pricing, model inference, or the AI client's internal tool selection logic.

Architecture

Forge has a single unified context preparation path used by all wrappers:

1. Repository scan — Extracts files, symbols (classes/functions), and dependencies (imports/requires) using parallel regex-based parsers for Python, JS, TS, JSX, and TSX.
2. Semantic ranking — Ranks files by TF-IDF query relevance with dependency centrality scoring.
3. AST pruning — Uses tree-sitter to prune files to only relevant symbols, keeping context lean.
4. Behavior injection — Prepends intensity-gated PromptForge (YAGNI) and ResponseForge (conciseness) instructions.
5. Compression — Collapses whitespace, strips boilerplate, and removes redundant content.
6. Caching — Fingerprints repositories and caches context between launches.
7. Launch — Sets FORGE_CONTEXT env var and starts the AI CLI.

Already built-in (unchanged)

These core layers are the default Forge path and stay on unless you turn them off via profile/config:

Optional efficiency layers (new, disabled by default)

Additive cost-reduction modules live under forgecli/efficiency/ and activate only when you set [efficiency] enabled = true. They do not replace Minimal Build Mode / Concise Mode — they sit on top.

Example config (forgecli.toml / Forge.toml):

[efficiency]
enabled = true
classifier = true
tiered_routing = true
system_prompt_first = true
feature_decomposition = true
validate_regenerate = true
selective_context = true
selective_file_threshold = 400
max_features = 8
max_regenerate_attempts = 3

[efficiency.tiers]
light_model = "claude-haiku-4.5"
standard_model = "claude-sonnet-4.5"
heavy_model = "claude-opus-4.6"
simple_max_score = 0.35
edit_max_score = 0.65

Tier values may be bare model ids (claude-haiku-4.5) or provider:model (anthropic:claude-haiku-4.5).

Installation

uv tool install forgeoptimizer

The CLI entrypoint is forge.

To upgrade an existing installation to get the latest optimization fixes:

uv tool upgrade forgeoptimizer

Important Usage Guidelines

[!IMPORTANT] Always run commands inside your specific project directories.

Forge scans the files in your current working directory to build context.

• Do not run forge commands inside your home directory (~) or root (/), as this will cause Forge to scan all unrelated system/home directories and files, leading to long scans or freezes.
• Always cd into your specific project folder or Git repository before running commands like forge claude, forge cursor, or forge antigravity.

Interfaces

Forge provides two ways to connect with your AI coding tools:

1. Convenience Wrappers (forge claude, forge cursor, forge codex, forge antigravity) — Automatically prepare context, configure MCP, and launch the target AI CLI.
2. MCP Server (forge mcp) — Standard stdio JSON-RPC interface exposing 6 tools that AI clients can call during sessions.

Command Reference

Use --refresh to bypass the cache on any wrapper command:

forge claude --refresh

MCP Tools

Forge exposes 6 tools over MCP:

• get_optimized_context — Full optimized repository context with optional query filtering
• get_summary — Repository layout, file count, and size summary
• get_dependency_graph — Module/file import relationships (from repo scan)
• file_lookup — File contents by relative path
• symbol_lookup — Class/function definitions and locations
• semantic_search — Keyword search across codebase chunks

[!IMPORTANT] Forge exposes these tools, but whether they are called depends on the AI client's internal orchestration. Forge does not control tool selection.

Environment Variables

Token-reduction benchmark

Measure real input-token counts (tiktoken / Anthropic count API) for baseline vs Forge across Claude, Codex, Cursor, and Antigravity model mappings:

# Default: Forge small/medium/large scopes, all tasks + ablations
forge benchmark -o benchmark_results

# Faster smoke run
forge benchmark --quick -o /tmp/forge-bench

# Optional: measure completion tokens via provider APIs
ANTHROPIC_API_KEY=… OPENAI_API_KEY=… forge benchmark --live -o benchmark_results

Reports: token_benchmark.md (docs-ready), .json, and .csv. Negative reductions (Forge increased tokens) are listed explicitly.

Token-reduction fixes (measured)

• Session instruction cache — PromptForge/ResponseForge rules sent once per MCP/session (get_session_instructions + cached get_optimized_context).
• Hard max_tokens caps by classifier tier ([efficiency.tiers] max_tokens_simple|edit|…).
• Adaptive selective context — activates on file count or estimated token budget (default threshold 150 files / 6k tokens), not only at 400+.
• MCP primary context — initialize instructions + forge://context resource tell the agent Forge context replaces full-repo dump.

Live completion tokens (where Concise Mode / Minimal Build Mode should show wins):

export FEATHERLESS_API_KEY=…
forge benchmark --live --live-provider featherless --quick -o docs/benchmark_results
# optional model override:
forge benchmark --live --live-provider featherless --live-model meta-llama/Meta-Llama-3.1-8B-Instruct

Default Featherless model is mistralai/Mistral-7B-Instruct-v0.2 (override with --live-model / FEATHERLESS_MODEL). Anthropic / OpenAI remain supported via --live-provider anthropic|openai when those keys are funded.

Development

git clone https://github.com/mdshzb04/Forge
cd Forge
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check forgecli tests

License

MIT