forge

Forge

A browser-automation team for Claude Code. Forge spawns a small mesh of agents that drive a real browser, capture reusable snippets, and (on request) compose verified Playwright specs from the work.

The default mode just does the thing you asked for. Spec mode is opt-in for when a flow is worth pinning into CI. If the team gets genuinely stuck, it escalates back to you with what it tried and what blocked it rather than spinning.

Requirements

• Node.js — any recent version (tested on 24).
• playwright-cli — brew install playwright-cli. Forge wraps it.

Supported on macOS, Linux, and Windows.

Quick start

1. Install the plugin (one time per machine):

   claude plugin marketplace add vivecuervo7/forge
   claude plugin install forge@vivecuervo7
   

2. Enable experimental agent teams in ~/.claude/settings.json, then restart Claude Code:

   { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
   

3. Scaffold your project from inside it:

   /forge init
   

   This creates forge/ with a hints/ directory, a fallback Playwright config, and a self-documenting .gitignore.

4. Drive a task. For an unauthenticated site, the bare scaffold is enough:

   /forge <describe what you want done>
   

   That launches a fresh chromium and goes. For sites with auth or other project-specific behaviour, author hint files in forge/hints/ (see forge/hints/README.md for guidance). All five hints are optional and additive: write only what you need.

   Want to see forge run end-to-end before adopting it? Try the samples — three project-shaped directories with hints already authored and prompt-by-prompt walkthroughs against public test sites. 5–15 minutes per walkthrough.

Commands

Core workflow

Command	What it does
/forge init	Scaffolds the forge/ directory convention into the current project. Idempotent — the starting point for any new project.
/forge <task>	Drive mode. Driver + snippet-author. Does the task end-to-end, accretes reusable snippets from novel work. The everyday command.
/forge spec <task>	Spec mode. Adds spec-writer + spec-verifier. Composes a self-contained .spec.ts and confirms it passes from a cold start. Also fires on natural-language signals — "create a spec for AE-1775", "write a spec that…", "capture as a spec".

Teach mode

Command	What it does
/forge teach <topic>	User pilots forge turn-by-turn, signals snippet boundaries explicitly, and weaves project-specific gotchas (fallbacks, retries, conditional branches) into snippet bodies. The deliberate library-building channel — useful when the app has quirks the agent can't be expected to discover. Also fires on "teach forge how to …" / "let me show forge how to …" phrasings.

Re-running and shipping

Command	What it does
/forge run <spec|last|latest>	Re-runs a verified spec via the standalone runner. No team spawned.
/forge export <spec-name>	Exports a composed spec to a self-contained inlined form, suitable for shipping into another test suite.

Add record as <label> to a run invocation to capture a video at forge/videos/<spec>-<label>.webm. /forge run last spec, record as before → fix the bug → /forge run last spec, record as after produces paired evidence for a PR.

See it in action

Try a sample before adopting forge for your own project. Each sample is a project-shaped directory — committed hints, scaffolded config, real-forge-output seed snippets — plus a prompt-by-prompt walkthrough you run yourself.

Sample	What you'll see
samples/shop/	Authentication, multi-account hint pattern, full spec-mode pipeline with verifier iteration, and two browsers running in parallel under different accounts
samples/internet/	Variant-arg parameterisation — one snippet covers a family of probe pages
samples/widgets/	Compositional decomposition — fill + read snippets compose into larger flows

Start with shop if your work involves any authenticated app — that walkthrough exercises the most surface area. Each sample's README has the exact commands; budget 5–15 minutes per walkthrough.

Why not codegen, playwright-cli, or hand-writing?

• Codegen records one flow into one .spec.ts. Forge accretes snippets across drives and bakes project knowledge into reusable hints.
• playwright-cli is the stateless command interface forge wraps. Forge adds the agent team, snippet library, hints, and spec pipeline on top.
• Hand-writing is the maximum-control option. Forge trades some control for automated selector / decomposition / gotcha work, with cold-start verification on the output.

Architecture