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 native graph generation.
• Behavior Optimization — Configurable implementation guidance (Ponytail YAGNI rules) and response style optimization (Caveman 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 Ponytail (YAGNI) and Caveman (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.

Advanced Graph

The native builder works out of the box with no extra setup. For the advanced graph (Leiden clustering and LLM-powered analysis), Forge will automatically detect and install the external graphify tool and its required provider dependencies when you run the build command.

You only need to configure your API key and run the command:

# 1. Provide an API key for your provider
export ANTHROPIC_API_KEY="your-key-here"

# 2. Build the graph (Forge automatically manages the graphify installation)
forge graph build

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
• 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

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