forge

Forge

   

Turn Claude Code into a structured delivery loop: plan the work, run modules in parallel, validate deeply, retry intelligently, and carry forward what worked.

Why Forge

Single-agent Claude Code drifts past ~5 steps. The failure mode isn't code quality — it's silent state corruption: parallel workers branching from stale HEAD, modules quietly clobbering each other's changes, "DONE" status that hides broken integration. Forge externalizes the plan → execute → validate loop so the same task that would silently break at 7 steps cleanly delivers at 30.

Core mechanic:

• DAG plans, not linear chains — workers run in parallel where dependencies allow
• Worktree isolation + auto-WIP commits between tiers — every tier writes to disk before the next branches off (this exists because we shipped memem v0.10.0 once with this exact failure: 20 min of recovery work)
• Per-module verify commands & acceptance criteria — defined at plan time so workers can't quietly lower the bar
• Multi-lens review — a separate reviewer agent + 3× self-consistency catches cross-module bugs single-module reviewers miss
• Structured failure ledger — failure modes captured as JSONL, recalled by pattern ID in the next plan

Track record: shipped memem v1.7 → v1.8.3 (7 releases) in a single day, including a 9-file anti-recursion safety fix and a persistent slice daemon — with human in the loop only at yes/modify/abort gates.

Install

Copy-paste:

claude plugin marketplace add TT-Wang/forge
claude plugin install forge@tt-wang-plugins

First start may take a few seconds because Forge bootstraps its MCP server dependencies automatically.

After install:

1. restart Claude Code if it was already open
2. open any repo you want to work in
3. run /forge <objective>

Example:

/forge add audit logging for admin actions

The Pitch

Forge is for the point where plain prompting stops being enough.

If the task touches several files, needs coordination between modules, or needs proof that it actually works, Forge gives Claude Code a workflow instead of just another prompt:

• break the work into modules
• run what can be parallelized
• validate each module hard
• retry failures with debugger context
• remember what worked for the next task

You still use Claude Code. Forge just adds structure around the hard parts.

What You Get

• Structured planning: breaks a feature into modules with dependencies and verification commands
• Parallel execution: runs independent modules at the same time in isolated worktrees
• Deep validation: checks files, commands, syntax, and cross-module API contracts
• Intelligent retry: tracks attempts, detects stagnation, and escalates to a debugger agent
• Session resumability: picks up incomplete work instead of starting from scratch
• Cross-session memory: remembers conventions, failure patterns, and test commands
• Status visibility: exposes progress in Claude output and a terminal status line

Why Not Just Use Claude Code Directly?

For many tasks, you should.

| Task shape | Plain Claude Code | Forge | |---|---|---| | One small edit | Better | Overkill | | Quick investigation | Better | Overkill | | Multi-file feature | Manual coordination required | Strong fit | | Parallelizable work | You manage it yourself | Built in | | Deep validation | You remember to run it | Part of the workflow | | Retry after failure | Manual retry and debugging | Tracked, guided, resumable | | Reusing patterns across sessions | Ad hoc | Built in memory |

Forge is not trying to replace normal usage. It is for the tasks where orchestration matters.

Quick Start

60-second setup

1. Install Forge with the two commands above
2. Restart Claude Code
3. Open your project
4. Paste one objective:

/forge add JWT auth with refresh tokens

1. Approve the generated plan

Run

/forge build an audit log for admin actions

Check Progress

/forge-status

Re-check One Module

/forge-validate m2

A Typical Session

/forge add JWT auth with refresh tokens

[forge] Phase 1: Planning...
[forge] Proposed Plan: 4 modules, 2 parallel groups
[forge] Proceed with this plan? (yes / modify / abort)

[forge] Phase 2: Executing m1...
[forge] Phase 2: Executing m2, m3 in parallel...
[forge] ✓ m2: DONE — validated, score 1.0
[forge] ✗ m3: FAILED — retrying with debugger
[forge] ✓ m3: DONE — validated after retry

[forge] ## Forge Complete
[forge] 4/4 modules completed

That is the experience Forge is aiming for: less manual steering, more visible progress, and fewer silent failures.

What To Expect On First Run

• Forge will create a local .forge/ directory in your project
• the MCP server may spend a few seconds installing its Node dependencies
• your first real interaction is the plan review step
• nothing executes until you explicitly approve the plan

Current Project Structure

forge/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .claude/
│   ├── settings.json
│   └── settings.local.json
├── agents/
│   ├── planner.md
│   ├── worker.md
│   ├── reviewer.md
│   └── debugger.md
├── skills/
│   ├── forge/
│   │   └── SKILL.md
│   ├── forge-status/
│   │   └── SKILL.md
│   └── forge-validate/
│       └── SKILL.md
├── forge-mcp-server/
│   ├── index.mjs
│   ├── start.sh
│   ├── package.json
│   └── tests/
├── statusline/
│   └── forge-status.sh
├── docs/
│   ├── architecture.md
│   ├── mcp-tools.md
│   └── launch/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CLAUDE.md
└── README.md

At runtime, Forge also creates a local .forge/ directory in the working project to store plans, logs, memory, retry history, and resumable state.

The Main Pieces

Agents

Forge ships with four focused agents:

• planner: explores the codebase and proposes the module plan
• worker: implements one module in an isolated worktree
• reviewer: checks correctness, security, and contract mismatches
• debugger: investigates failed modules and drives retry

Skills

The user-facing commands are:

• /forge: full orchestrator workflow
• /forge-status: current plan, module progress, and learned patterns
• /forge-validate: re-run validation for one module

MCP Server

The bundled MCP server provides the shared runtime capabilities Forge needs:

• validate
• validate_plan
• memory_recall
• memory_save
• iteration_state
• forge_logs
• session_state

These tools let multiple agents coordinate without relying on loose conversational memory.

Status Line

Forge can render live progress in your terminal:

[forge] ████░░░░░░ 2/5 | VALIDATE | refresh endpoint | 3m19s | ~2m30s left

To use it:

claude statusline set "bash /path/to/forge/statusline/forge-status.sh"

What Lives In Your Project

Forge keeps its runtime state in a local .forge/ directory inside the working project. That includes:

• execution plans
• retry history
• learned patterns
• structured logs
• resumable session state

This keeps the workflow inspectable instead of hiding everything behind opaque agent state.

Documentation

• Architecture — orchestrator, agents, MCP server, and state flow
• MCP tools reference — input/output schemas and examples for all 7 tools
• Changelog — release notes
• Contributing — dev setup, tests, linting, and PR process
• Security — vulnerability reporting and security scope

Manual Installation

If you do not want to install from the Claude Code marketplace, you can wire Forge manually:

git clone https://github.com/TT-Wang/forge.git /tmp/forge
mkdir -p .claude/agents .claude/skills
cp /tmp/forge/agents/*.md .claude/agents/
cp -r /tmp/forge/skills/* .claude/skills/
cp -r /tmp/forge/forge-mcp-server ./forge-mcp-server/
cd forge-mcp-server && npm install && cd ..

Then wire the MCP server using the reference config in .claude/settings.json.

Development

git clone https://github.com/TT-Wang/forge.git
cd forge/forge-mcp-server
npm install
npm test

Works Great With

• memem — persistent cross-session memory for Claude Code. Forge handles planning and execution; memem helps carry useful patterns across runs.
• Vibereader — curated tech news while Claude works

License

MIT — see LICENSE