Metadata-Version: 2.4
Name: forgeoptimizer
Version: 1.3.0
Summary: Forge — AI optimization runtime for Claude Code, Codex, Cursor, Antigravity
Project-URL: Homepage, https://github.com/mdshzb04/Forge
Project-URL: Repository, https://github.com/mdshzb04/Forge
Project-URL: Documentation, https://github.com/mdshzb04/Forge#readme
Project-URL: Issues, https://github.com/mdshzb04/Forge/issues
Author: Forge Authors
License: MIT
Keywords: ai,claude,cli,codex,cursor,developer-tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: click>=8.1.7
Requires-Dist: cryptography>=42.0.5
Requires-Dist: fastapi>=0.100.0
Requires-Dist: gitpython>=3.1.42
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.2.0
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: tree-sitter-languages>=1.10.0
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.20.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# Forge

<p align="center">
  <a href="https://github.com/mdshzb04/Forge/actions/workflows/ci.yml">
    <img src="https://github.com/mdshzb04/Forge/actions/workflows/ci.yml/badge.svg" alt="CI Status">
  </a>
  <a href="https://pypi.org/project/forgeoptimizer/">
    <img src="https://img.shields.io/pypi/v/forgeoptimizer.svg" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/forgeoptimizer/">
    <img src="https://img.shields.io/pypi/pyversions/forgeoptimizer.svg" alt="Supported Python Versions">
  </a>
  <a href="https://github.com/mdshzb04/Forge/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/mdshzb04/Forge.svg" alt="License: MIT">
  </a>
  <a href="https://github.com/astral-sh/ruff">
    <img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code Style: Ruff">
  </a>
</p>

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:

| Layer | What it does |
| --- | --- |
| **PromptForge (Minimal Build Mode)** | Implementation-style / YAGNI rules that prune speculative work |
| **ResponseForge (Concise Mode)** | Concise response-style rules |
| **Semantic ranking + AST prune** | Query-aware file ranking and symbol-level pruning |
| **Compression + cache** | Token compression and fingerprint-based reuse |

### 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.

| Module | Purpose |
| --- | --- |
| **Prompt classifier** | Labels requests as `simple` / `edit` / `multi_feature` / `complex` before LLM work |
| **Tiered model routing** | Maps classifier output to configurable light/standard/heavy models |
| **System-prompt-first assembly** | Keeps shared system instructions first so prefix KV cache can hit |
| **Feature decomposition** | Splits multi-feature asks into independently validated units |
| **Validate–regenerate loop** | Re-runs a failing unit instead of forwarding broken output |
| **Selective context preload** | Full context on small repos; request-referenced + key files on large ones |

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

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

```bash
uv tool install forgeoptimizer
```

The CLI entrypoint is `forge`.

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

```bash
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

| Command | Description |
| -------- | ----------- |
| `forge claude` | Launch Claude Code with optimized context |
| `forge codex` | Launch Codex CLI with optimized context |
| `forge cursor` | Launch Cursor CLI with optimized context |
| `forge antigravity` | Launch Antigravity CLI with optimized context |
| `forge commit` | Generate a Conventional Commit message from staged changes |
| `forge mcp` | Start the stdio MCP server |
| `forge start` | Start the background daemon |
| `forge config` | Configure optimization profiles |
| `forge status` | Show repository, daemon, and optimization status |
| `forge doctor` | Verify installation and dependencies |
| `forge inspect` | Display active pipeline and optimization stages |
| `forge stats` | Show cache metrics and pipeline performance |
| `forge profile` | View or set optimization profiles |
| `forge explain` | Explain pipeline stages, concepts, or topics |
| `forge --version` | Show version |

Use `--refresh` to bypass the cache on any wrapper command:
```bash
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

| Variable | Purpose |
| -------- | -------- |
| `FORGE_CONTEXT` | Optimized pre-launch context text |
| `FORGE_CONTEXT_FILE` | Path to the cached context file |
| `FORGE_REPO_ROOT` | Detected repository root |

---

## Token-reduction benchmark

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

```bash
# 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):

```bash
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

```bash
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](LICENSE)
