forgeoptimizer 1.0.0__tar.gz → 1.0.2__tar.gz

{forgeoptimizer-1.0.0 → forgeoptimizer-1.0.2}/.github/workflows/ci.yml

@@ -127,8 +127,6 @@ jobs:
           forge claude --help
           forge codex --help
           forge cursor --help
-          forge opencode --help
-          forge commandcode --help
 
 
   publish-testpypi:

{forgeoptimizer-1.0.0 → forgeoptimizer-1.0.2}/.gitignore

@@ -8,7 +8,7 @@ __pycache__/
 
 # Distribution / packaging
 build/
-graphify-out/
+forgegraph-out/
 dist/
 *.egg-info/
 *.egg
@@ -49,3 +49,16 @@ htmlcov/
 # Test artifacts (prevent CI failures)
 foo.py
 main.go
+
+# Forge local configurations & editor integration settings
+forgecli.toml
+.cursor/
+.mcp.json
+.agents/
+
+# Frontend build and dependencies
+**/node_modules/
+**/.next/
+**/out/
+**/dist/
+

forgeoptimizer-1.0.2/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 1.0.0 (2024-07-09)
+
+### Forge v1.0 — Initial Production Release
+
+Forge is a lightweight, high-performance AI optimization runtime that prepares repository-aware context before launching supported AI coding tools.
+
+### Features
+
+- **8 AI CLI Wrappers**: Unified launch for Claude Code, Codex CLI, Cursor CLI, Antigravity, Gemini CLI, Aider, OpenCode, and CommandCode through a single `launch_wrapper()` path.
+- **19-Stage Middleware Pipeline**: Telemetry → Auth → Policy → Cache → History → Token → Context → Conversation → Caveman → Ponytail → Repository → DepGraph → SymbolLookup → Graphify → SemanticRetrieval → Streaming → Resilience → Provider → ResponseOptimizer.
+- **Optimization Profiles**: Ponytail (prompt YAGNI rules), Caveman (output conciseness), and Output Optimization with `off/lite/full/ultra/wenyan` intensities.
+- **ForgeGraph Integration**: Knowledge graph generation for intelligent context retrieval with `forge graph build`.
+- **MCP Server**: Stdio Model Context Protocol server with 6 tools (`get_optimized_context`, `get_summary`, `get_dependency_graph`, `file_lookup`, `symbol_lookup`, `semantic_search`).
+- **Background Daemon**: Repository watcher with auto-refresh, chunking, and graph snapshot on port 16868.
+- **16 Provider Drivers**: OpenAI, Anthropic, Google Gemini, OpenRouter, Groq, Mistral, DeepSeek, GLM, Qwen, Kimi, Ollama, LM Studio, and more — with real HTTP implementations for the big three.
+- **Developer Diagnostics**: `forge inspect`, `forge stats`, `forge doctor`, `forge profile`, `forge explain`.
+- **Configuration**: TOML-based `forgecli.toml` with environment variable override for all settings.
+- **Packaging**: pip install, CI/CD across ubuntu/macos/windows, PyPI ready.
+
+### System
+
+- Python 3.12+ required
+- 463+ tests passing
+- 40% faster startup vs initial implementation (0.63s CLI import)
+- MIT License

forgeoptimizer-1.0.2/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to Forge
+
+Thank you for your interest in contributing to **Forge**! Forge is a lightweight, high-performance AI optimization runtime designed to prepare repository-aware context before launching supported AI coding tools.
+
+This document outlines the guidelines and best practices for contributing to the codebase.
+
+---
+
+## Code of Conduct
+
+We expect all contributors to adhere to standard respectful community interactions. Be kind, helpful, and professional in all communications.
+
+---
+
+## Getting Started
+
+### Prerequisites
+- **Python 3.12** or higher.
+- [uv](https://github.com/astral-sh/uv) (recommended) or `pip` + `venv`.
+
+### Local Development Setup
+
+1. **Fork and Clone the Repository**
+   ```bash
+   git clone https://github.com/mdshzb04/Forge.git
+   cd Forge
+   ```
+
+2. **Create and Activate a Virtual Environment**
+   Using `uv` (recommended):
+   ```bash
+   uv venv
+   source .venv/bin/activate
+   ```
+   Or using standard Python:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate
+   ```
+
+3. **Install Dependencies**
+   Install Forge in editable mode with development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+---
+
+## Development Workflow
+
+### Running Tests
+
+We use `pytest` for all unit and integration testing. Ensure your tests pass before submitting any pull requests.
+
+To run the full test suite:
+```bash
+pytest
+```
+
+To run a specific test file:
+```bash
+pytest tests/test_mcp_config.py
+```
+
+### Code Quality & Styling
+
+We use **Ruff** for linting, formatting, and import sorting.
+
+To check for style violations:
+```bash
+ruff check forgecli tests
+```
+
+To automatically fix violations and format code:
+```bash
+ruff check --fix forgecli tests
+ruff format forgecli tests
+```
+
+### Static Type Checking
+
+We use **mypy** for static type verification:
+```bash
+mypy forgecli
+```
+
+---
+
+## Code Architecture
+
+Forge consists of two main pillars:
+1. **`forgecli.runtime`**: Orchestrates runtime environments, command wrappers, daemon processing, and MCP standard input/output configurations.
+2. **`forgecli.optimizer`**: Contains token compression, Ponytail (YAGNI pruning rules), and Caveman (brevity prompts) components.
+
+Ensure any changes respect this separation of concerns.
+
+---
+
+## Pull Request Guidelines
+
+1. **Branch Naming**: Use descriptive branch names (e.g., `feature/optimize-caching`, `bugfix/fix-toml-regex`).
+2. **Commit Messages**: Write clear, descriptive commit messages in the imperative mood (e.g., `Fix TOML config regex to correctly match blocks`).
+3. **Add Tests**: If you are adding a new feature or fixing a bug, please write corresponding tests in the `tests/` directory.
+4. **Documentation**: Update the `README.md`, `docs/`, or docstrings if your changes modify any public-facing behaviors or flags.
+5. **CI Compliance**: Ensure the Github Actions CI build passes.
+
+Thank you for making Forge better for everyone! 🚀

forgeoptimizer-1.0.2/CREDITS.md

@@ -0,0 +1,19 @@
+# Acknowledgements & Credits
+
+Forge draws inspiration from, and implements custom versions of ideas from, several excellent open-source projects and concepts in the AI developer tooling ecosystem. We would like to thank their authors and communities:
+
+* **Graphify**
+  * **Contribution:** Inspired ideas around repository-aware knowledge graph generation and parsing to help AI engines navigate codebase structures.
+  * **License:** Licensed under the MIT License.
+
+* **Caveman** (by Julius Brussee)
+  * **Original Project:** [github.com/JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)
+  * **Contribution:** Inspired the concept of system-prompt communication compression and brevity constraints to reduce completion token sizes.
+  * **License:** Licensed under the MIT License.
+
+* **Ponytail**
+  * **Contribution:** Inspired the implementation of the pragmatic YAGNI ("You Ain't Gonna Need It") prompt ruleset for code simplification.
+  * **License:** Licensed under the MIT License.
+
+Forge adapts these open-source prompt optimization concepts into its own custom Python-based rulesets, combining them with original runtime infrastructure, background caching daemons, and IDE wrappers to provide a seamless context experience.
+

{forgeoptimizer-1.0.0 → forgeoptimizer-1.0.2}/Forge.toml

@@ -11,7 +11,7 @@ languages = ["python", "typescript"]
 [prompt_optimizer]
 backend = "ruleset"
 enabled = true
-intensity = "lite"
+intensity = "full"
 
 [providers]
 allowed = ["mock"]

forgeoptimizer-1.0.2/MIGRATION.md

@@ -0,0 +1,40 @@
+# Migration Guide
+
+## From Pre-1.0 to v1.0.0
+
+Forge v1.0.0 is the first production release. If you were using earlier development versions, the following changes apply:
+
+### CLI Changes
+
+All wrapper commands remain identical:
+```bash
+forge claude     # unchanged
+forge codex      # unchanged
+forge cursor     # unchanged
+forge antigravity # unchanged
+forge aider      # unchanged
+```
+
+**New wrappers added**:
+```bash
+forge opencode    # new
+forge commandcode # new
+```
+
+**New commands**: `forge stats`, `forge profile`, `forge explain`, `forge inspect`
+
+### Python API
+
+The following internal functions were renamed but backward-compatible aliases exist:
+
+- `build_merged_context(repack_context, restart_root)` — new unified entry point
+- `get_merged_context(repo_context)` — still available as deprecated alias
+- `build_behavior_instructions()` — still available as deprecated alias
+
+### Configuration
+
+No changes to `forgecli.toml` format. All existing configuration files work without modification.
+
+### Provider System
+
+No breaking changes. The same `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `GOOGLE_API_KEY` environment variables are used.

forgeoptimizer-1.0.2/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: forgeoptimizer
+Version: 1.0.2
+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`.
+
+---
+
+## 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)

forgeoptimizer-1.0.2/README.md

@@ -0,0 +1,149 @@
+# 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`.
+
+---
+
+## 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)

forgeoptimizer-1.0.2/RELEASE_NOTES.md

@@ -0,0 +1,52 @@
+# Forge v1.0.0 Release Notes
+
+## Overview
+
+Forge v1.0.0 is the first production release of the Forge AI optimization runtime. Forge prepares optimized repository-aware context for AI coding assistants, reducing token usage and improving response quality through prompt engineering, output optimization, and intelligent context retrieval.
+
+## What's New
+
+Forge provides a complete developer experience:
+
+```
+forge claude          # Launch Claude Code with optimized context
+forge codex           # Launch Codex CLI
+forge cursor          # Launch Cursor CLI  
+forge antigravity     # Launch Antigravity CLI
+forge aider           # Launch Aider with context injection
+forge opencode        # Launch OpenCode
+forge commandcode     # Launch CommandCode
+
+forge start           # Start the background daemon
+forge mcp             # Start the MCP server over stdio
+forge graph build     # Build a knowledge graph
+
+forge config          # Configure optimization profiles
+forge profile         # View/set profiles with rich output
+forge status          # Repository and daemon status
+forge stats           # Usage statistics
+forge doctor          # System diagnostics
+forge inspect         # Pipeline and providers
+forge explain         # Explain pipeline stages and concepts
+```
+
+## Key Capabilities
+
+- **19-stage middleware pipeline** processes every AI request through telemetry, auth, policy, caching, history compression, token planning, context optimization, conversation tracking, Ponytail prompt engineering, Caveman output compression, repository scanning, dependency analysis, symbol extraction, graph enrichment, semantic ranking, streaming, resilience, provider execution, and response optimization.
+- **7 AI CLI wrappers** unified through a single runtime path.
+- **16 providers** with real HTTP drivers for OpenAI, Anthropic, and Google Gemini.
+- **Knowledge graph** integration for intelligent file context injection.
+- **Optimization profiles** with 4-5 intensity levels per optimizer.
+
+## Installation
+
+```bash
+pip install forgeoptimizer
+# or
+uv tool install forgeoptimizer
+```
+
+## What's Next
+
+- Performance profiling and optimization of 19-stage pipeline under production load
+- Standalone binary packaging (PyInstaller/Nuitka)

forgeoptimizer-1.0.2/SECURITY.md

@@ -0,0 +1,42 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | ✅ Yes   |
+| < 1.0   | ❌ No    |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Forge, please do **not** open a public GitHub issue.
+
+Instead, email the maintainers directly. We will respond within 48 hours and work with you on a coordinated disclosure timeline.
+
+## Security Design
+
+### API Keys
+
+Forge stores API keys in two ways:
+1. **Environment variables** (recommended): `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, etc.
+2. **System keyring** (optional): Forge can store credentials in your OS keychain via the `keyring` library.
+
+Forge never writes API keys to log files, configuration files, or cache directories.
+
+### Subprocess Execution
+
+Wrapper commands (`forge claude`, `forge codex`, etc.) launch external CLI binaries via `subprocess.run()` with arguments passed as a list — never through `shell=True`. This prevents command injection.
+
+### Dependency Verification
+
+All dependencies are pinned and sourced from PyPI. We do not include vendored dependencies. The CI pipeline verifies package integrity through `twine check` before publishing.
+
+## Security Checks
+
+Run `forge doctor` to check your installation's security posture, including:
+- Which provider API keys are configured
+- Configuration file integrity
+
+## Disclosure Timeline
+
+We aim to fix confirmed vulnerabilities within 7 days and release a patch. Critical vulnerabilities may receive same-day patches.