Metadata-Version: 2.4
Name: forgeoptimizer
Version: 1.0.4
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 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:

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

```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 graph build` | Build a codebase graph (native or external) |
| `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
* `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 |

---

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