SpecForge

🇺🇸 English

🇪🇸 Español
🇧🇷 Português
🇫🇷 Français
🇨🇳 中文
🇩🇪 Deutsch

🇺🇸 English

🇪🇸 Español
🇧🇷 Português
🇫🇷 Français
🇨🇳 中文
🇩🇪 Deutsch

Appearance

Getting Started ​

SpecForge is a plugin for your AI coding tool that helps you plan, track, and verify software features. Instead of repeating yourself in every chat, you create a spec (a short plan with a "done" checklist) and your AI follows it automatically.

It works with any programming language, any framework, and most AI tools.

Before you start ​

  • Node.js ≥ 22 — download at nodejs.org — this is needed to run SpecForge locally. No account required, your data stays on your machine.
  • Any of the AI tools listed below

Compatible AI Tools ​

SpecForge connects to AI tools that support the Model Context Protocol (MCP) — an open standard for AI plugins:

AI ToolHow to connect
Claude DesktopEdit config file (see steps below)
Claude CodeOne command: claude mcp add
ChatGPT DesktopEdit config file — requires Plus or Pro
CursorEdit ~/.cursor/mcp.json
WindsurfEdit ~/.codeium/windsurf/mcp_config.json
Gemini CLIEdit ~/.gemini/settings.json
Cline (VS Code)Cline settings → MCP Servers

Installation ​

The config block is the same for all tools — only the file location changes:

json
{
  "mcpServers": {
    "specforge": {
      "command": "npx",
      "args": ["-y", "specforge-mcp@latest"]
    }
  }
}

Claude Desktop ​

Step 1. Open Claude Desktop on your computer.

Step 2. Go to the Claude menu → Settings → Developer tab → click Edit Config.

This opens the config file in your text editor. If the file is empty, start with {}.

Step 3. Paste the config block above inside "mcpServers", save the file.

Step 4. Fully quit and reopen Claude Desktop.

Step 5. Open a new conversation — SpecForge appears in the tools panel (🔌).

Claude Code ​

bash
claude mcp add specforge -- npx -y specforge-mcp@latest

Restart Claude Code. SpecForge will be available in your next session. Claude Code docs →

ChatGPT Desktop ​

Open or create the config file at:

  • Mac: ~/Library/Application Support/ChatGPT/config.json
  • Windows: %APPDATA%\ChatGPT\config.json

Paste the config block inside "mcpServers", save, and restart ChatGPT. Requires ChatGPT Plus or Pro.

Cursor ​

Open or create ~/.cursor/mcp.json and paste the config block. Then restart Cursor. Cursor docs →

Windsurf ​

Open or create ~/.codeium/windsurf/mcp_config.json and paste the config block. Then restart Windsurf. Windsurf docs →

Gemini CLI ​

Open or create ~/.gemini/settings.json and paste the config block. Then restart Gemini CLI. Gemini CLI →

Cline (VS Code extension) ​

In VS Code with Cline installed: open Cline's sidebar → click MCP Servers → paste the config block. Cline →

Your First Project ​

Step 1 — Verify SpecForge is working ​

Open a new chat in your AI agent (Claude Desktop, Cursor, Windsurf, etc.) and type:

"List all specforge tools"

You should see a list of 59+ tools. If nothing appears, go back to the installation step — the agent may need a full restart.

Step 2 — Initialize your project ​

Tell your AI agent the path to your project folder:

"Initialize my project at /Users/yourname/projects/my-app with specforge"

Replace /Users/yourname/projects/my-app with the actual folder path of your project.

SpecForge scans the directory and auto-detects your language, framework, package manager, and architecture. It returns a projectId (e.g., proj_abc123) — save this, you'll use it next.

Step 3 — Create your first spec ​

Tell your AI what you want to build:

"Create a spec for adding user login with Google OAuth to project proj_abc123"

SpecForge creates a spec — a short document with a step-by-step plan and a checklist of what "done" really means. Everything is saved locally in your project folder.

Step 4 — Build guided by the spec ​

Continue chatting with your AI as normal. The spec is your agreement — the AI reads it, follows it, and checks its work against it automatically.

When you think it's done, verify:

"Validate spec SPEC-001 against the code at /Users/yourname/projects/my-app/src"

Step 5 — Catch when things drift ​

As your project grows, code can drift from the original plan (drift = when what was built no longer matches what was agreed). Keep specs in sync:

"Check if my implementation still matches SPEC-001"

SpecForge tells you exactly which items are done, which are missing, and what changed from the original plan.

Next Steps ​