Creation Layer of Cortex

Describe it.
Forge builds it.

Natural language to working tool in one command. Forge generates code, writes tests, iterates until they pass, and installs directly into your workflow. Self-evolving tools, zero friction.

Get Started See The Pipeline
?!
Describe
→
Q
Clarify
→
S
Spec
→
{}
Generate
→
T
Test
→
✓
Install
forge — zsh
$ forge create "convert CSV files to JSON with column filtering"

Forge Analyzing description...
Forge Detected: file input (CSV), structured output (JSON), transform pattern
Forge Generating clarification questions...

Q1: Should it handle multiple CSV files or single file?
Q2: What column filtering syntax? (names, indices, regex?)
Q3: Output to stdout or write to .json file?

$ forge answer --session abc123 "single file, column names, write to file"

Forge Generating code + tests...
Forge Tests: 8/10 passed (2 edge case failures)
Forge Auto-fixing... iteration 1/5
Forge Tests: 10/10 passed

Forge ✓ csv_to_json installed to ~/.local/bin/csv_to_json
Forge ✓ Ready to use: csv_to_json data.csv --columns name,email -o output.json
6
Pipeline Stages
3
Output Types
5x
Auto-Iterate
7
MCP Tools
3
Install Targets
The Pipeline

From description to deployed tool

Six stages, fully automated. Describe what you need in plain English. Forge handles everything else — including fixing its own mistakes.

Stage 01
?!

Describe

Start with a natural language description. "Convert CSV to JSON with column filtering." That's all Forge needs to begin.

Stage 02
Q

Clarify

Forge analyzes your description, detects patterns (file I/O, network, transforms), and generates targeted questions to eliminate ambiguity.

Stage 03
S

Generate Spec

A structured ToolSpec is built: name, params, return type, dependencies, core logic, error handling, and usage examples. The blueprint.

Stage 04
{}

Generate Code + Tests

Jinja2 templates produce production-quality code with type hints, docstrings, and error handling. Tests are generated in parallel.

Stage 05
↻

Test + Iterate

Tests run in an isolated tmpdir. If failures occur, Forge auto-analyzes errors and regenerates — up to 5 iterations until all tests pass.

Stage 06
✓

Install

One command installs your tool to MCP (for Claude Code), CLI (for terminal), or local storage. Immediately usable. Zero config.

Session Lifecycle

Tracked through every state

Every Forge session moves through a deterministic state machine. You always know exactly where your tool is in the pipeline.

CREATED
→
CLARIFYING
→
READY
→
GENERATING
→
TESTING
→
ITERATING
→
SUCCEEDED
/
FAILED
→
INSTALLED
Output Types

Three templates. Any target.

Forge generates production-ready code in three formats. Each template includes proper error handling, type hints, docstrings, and is immediately executable.

Python Module

Function + CLI

Type-hinted function with if __name__ runner

"""CSV to JSON converter with column filtering."""
import csv
import json
from pathlib import Path

def csv_to_json(
    input_path: str,
    columns: list[str] | None = None,
    output_path: str | None = None,
) -> list[dict]:
    """Convert CSV to JSON."""
    with open(input_path) as f:
        reader = csv.DictReader(f)
        rows = [dict(r) for r in reader]
    ...

if __name__ == "__main__":
    csv_to_json(sys.argv[1])
CLI Tool

Click-based CLI

Full argument parsing, help text, error handling

#!/usr/bin/env python3
"""CSV to JSON CLI tool."""
import click

@click.command()
@click.argument("input_file")
@click.option(
    "--columns", "-c",
    help="Comma-separated column names",
)
@click.option(
    "--output", "-o",
    help="Output file path",
)
def main(input_file, columns, output):
    """Convert CSV to JSON."""
    try:
        result = csv_to_json(...)
        click.echo("Done")
    except Exception as e:
        click.echo(e, err=True)
MCP Tool

FastMCP Server

Single-tool server, ready for Claude Code

"""MCP server for csv_to_json."""
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("csv-to-json")

@mcp.tool()
def csv_to_json(
    input_path: str,
    columns: list[str] | None = None,
    output_path: str | None = None,
) -> str:
    """Convert CSV to filtered JSON.

    Args:
        input_path: Path to CSV
        columns: Filter columns
    """
    ...

mcp.run()
Intelligent Clarification

Asks the right questions

Forge doesn't guess. It analyzes your description, detects patterns in what you said, and generates targeted questions across 5 categories to build an unambiguous spec.

Your description

"Build a tool that scrapes product prices from a URL and saves them to a CSV file"

Network detected — keywords: URL, scrape
Output format detected — keywords: CSV, save
Dependencies inferred — requests, beautifulsoup4
Generated Questions
INPUT
Single URL or multiple URLs? Should it follow pagination?
OUTPUT
Which fields to extract? (name, price, currency, URL?)
BEHAVIOR
Should it handle JavaScript-rendered pages or static HTML only?
DEPS
Need rate limiting or request delays between pages?
EDGE CASE
How to handle missing prices or unavailable products?
Auto-Iteration

Self-healing test loop

When tests fail, Forge doesn't give up. It analyzes the failures, regenerates the broken code, and retries — up to 5 times. Most tools pass by iteration 2.

Generate Code + Tests

Code and tests produced from ToolSpec

Run Tests (isolated tmpdir)

Tests execute in clean temporary directory

FAIL (iteration < 5)

Analyze Failures

Parse errors, identify root cause

↺ Fix & retry
PASS

All Tests Passed

Ready to install

Install to Target

MCP / CLI / Local

Installation Targets

Install once. Use everywhere.

Three targets for three workflows. Forge handles all the wiring — file placement, permissions, config updates. Your tool is ready to use the moment it's installed.

M

MCP Server

Installs as a FastMCP tool server for Claude Code. Auto-updates ~/.mcp.json with the new server entry.

~/.claude/mcp-tools/forge/{name}.py
$

CLI Binary

Installs as an executable CLI tool with shebang line. Added to your PATH. Run it like any other command.

~/.local/bin/{name}
~

Local Storage

Default target. Saves to Forge's tool library. Browse, re-test, or promote to MCP/CLI later.

~/.forge/tools/{name}/
CLI Reference

Six commands. Complete control.

The Forge CLI is built with Click. Every command has help text, sensible defaults, and works exactly as you'd expect.

forge create <desc>
Create a new tool from a natural language description. Starts the full pipeline: clarify, generate, test, install.
--type mcp|cli|python --no-clarify --install mcp|cli|local
forge list
Display a rich table of all tools in your Forge library. Shows name, type, status, and creation date.
forge show <name>
Display the source code of a generated tool with syntax highlighting.
forge test <name>
Re-run the test suite for an existing tool. Useful after manual edits or dependency updates.
forge uninstall <name>
Remove a tool from its install target. Cleans up files, PATH entries, and MCP config.
forge serve
Start the Forge MCP server. Exposes all 7 tools for use by Claude Code or other MCP clients.
MCP Server

7 tools for programmatic access

The Forge MCP server exposes the full pipeline as individual tools. Claude Code (or any MCP client) can create, iterate, and install tools programmatically.

forge_create
(description: str, output_type: str) → Session

Start a new Forge session. Analyzes description, generates clarification questions. Returns session ID and questions.

forge_answer
(session_id: str, answers: dict) → ToolSpec

Provide answers to clarification questions. Forge builds the ToolSpec and transitions to READY state.

forge_generate
(session_id: str) → TestResult

Generate code and tests from the ToolSpec. Runs tests automatically. Returns results with pass/fail status.

forge_iterate
(session_id: str, feedback: str) → TestResult

Auto-fix failing tests. Analyzes errors, regenerates code, retries. Up to 5 iterations.

forge_install
(session_id: str, target: str) → InstallResult

Install a passing tool to MCP, CLI, or local storage. Handles all file placement and config updates.

forge_status
(session_id: str) → SessionState

Get the current state of a Forge session: state, code preview, test results, iteration count.

forge_list
() → list[ToolSummary]

List all tools in the Forge library with name, type, status, and install location.

API Reference

ForgeEngine internals

The core orchestration class. ForgeEngine coordinates clarifier, generator, tester, and installer. Use it programmatically for custom integrations.

class ForgeEngine

forge/engine.py
async create_session(description: str, output_type: str) → Session

Initialize a new session from a natural language description. Runs clarifier to generate questions.

async answer_questions(session_id: str, answers: dict[str, str]) → ToolSpec

Process answers to clarification questions and build a complete ToolSpec.

async generate(session_id: str) → tuple[str, TestResult]

Generate code from ToolSpec using Jinja2 templates, then generate and run tests. Returns code and test results.

async iterate(session_id: str, feedback: str | None) → TestResult

Analyze test failures, regenerate code, and re-run tests. Tracks iteration count (max 5).

async install(session_id: str, target: str) → InstallResult

Install generated tool to the specified target (mcp, cli, local). Returns install path and status.

get_session(session_id: str) → Session

Retrieve a session by ID. Returns full session state including code, test results, and metadata.

list_tools() → list[ToolSummary]

List all persisted tools from storage (~/.forge/tools/).

Architecture

Module structure

Clean separation of concerns. Each module handles one stage of the pipeline. The templates/ directory holds Jinja2 templates for all output types.

engine.py
Core orchestration (ForgeEngine)
models.py
Pydantic data models
clarifier.py
Question generation for ambiguities
generator.py
Code generation + Jinja2 templates
tester.py
Test generation & isolated execution
installer.py
Install to MCP / CLI / local
storage.py
Persistence (~/.forge/tools/)
cli.py
Click CLI (6 commands)
mcp_server.py
FastMCP server (7 tools)
templates/
python_function, cli_tool, mcp_tool, test_tool
Data Models

Pydantic-powered type safety

Every object in the pipeline is a validated Pydantic model. Full type safety from description to deployment.

ToolSpec forge/models.py
name: str — Tool name (snake_case)
description: str — What the tool does
params: list[ToolParam] — Input parameters
return_type: str — Return type hint
dependencies: list[str] — pip packages needed
core_logic: str — Description of implementation
error_handling: str — Error handling strategy
examples: list[str] — Usage examples
Session forge/models.py
id: str — Unique session identifier
state: SessionState — Current pipeline stage
description: str — Original user description
questions: list[str] — Generated clarification questions
answers: dict[str, str] — User answers
spec: ToolSpec | None — Generated tool specification
code: str | None — Generated source code
test_results: TestResult | None — Latest test run
iterations: int — Auto-fix iteration count
TestResult
passed: int
total: int
failures: int
errors: list[str]
output: str
test_code: str
InstallResult
success: bool
install_path: str
target: str
message: str
Quick Start

One command. Working tool.

Install Forge, describe what you need, get a tested and installed tool. The whole process takes under a minute.

1 — Install Python 3.11+
pip install cortex-forge

# Or install with Cortex
pip install cortex-agent[forge]
2 — Create a tool (interactive)
forge create "convert markdown files to HTML with syntax highlighting"

Forge Analyzing description...
Forge Detected: file input (markdown), structured output (HTML)

Q1: Single file or batch directory processing?
Q2: Which syntax highlighter? (pygments, highlight.js, none?)
Q3: Include CSS in output or external stylesheet?

> single file, pygments, include CSS inline

Forge Generating code + tests...
Forge Tests: 8/8 passed
Forge ✓ md_to_html installed to ~/.local/bin/md_to_html
3 — Skip clarification (fast mode)
# --no-clarify skips questions and infers everything
forge create "count lines of code in a directory" --no-clarify --install cli

Forge Generating...
Forge Tests: 6/6 passed
Forge ✓ loc_counter installed to ~/.local/bin/loc_counter

loc_counter ./src --ext py,ts,rs
Python: 1,247 lines
TypeScript: 892 lines
Rust: 341 lines
Total: 2,480 lines
4 — Create an MCP tool for Claude Code
forge create "validate JSON schemas" --type mcp --install mcp

Forge ✓ json_validator installed as MCP server
Forge Updated ~/.mcp.json

# Now Claude Code can use it:
"Validate this JSON against the user schema"
Claude Code calls json_validator automatically
5 — Start the MCP server
# Expose all 7 Forge tools to Claude Code
forge serve

✓ Forge MCP server running on stdio
✓ 7 tools available: forge_create, forge_answer, forge_generate,
  forge_iterate, forge_install, forge_status, forge_list

# Claude Code can now build tools autonomously:
"I need a CSV parser. Let me use Forge to build one."
Technical Specs

Built on solid foundations

Python
>= 3.11
click
>= 8.1
pydantic
>= 2.0
jinja2
>= 3.1
mcp
>= 1.0
rich
>= 13.0