Vibe Forge

A multi-agent development orchestration system for terminal-native vibe coding.

What Is This?

Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents, each with distinct personalities and specializations, work together to build software. You talk to a Planning Hub that coordinates the team, then spawn workers into separate terminal tabs to execute in parallel.

                         YOU
                          |
                    /forge plan
                          |
              +-----------+-----------+
              |     PLANNING HUB     |
              |  Oracle  Architect   |
              |  Aegis   Pixel       |
              |  Ember   Crucible    |
              +-----------+-----------+
                          |
            /forge spawn <agent>
                          |
         +--------+-------+-------+--------+
         |        |       |       |        |
       Anvil   Furnace Crucible Temper  Scribe
        FE       BE      QA    Review   Docs

Install

npx vibe-forge init

This sets up Vibe Forge in your project: detects your platform, configures your terminal, creates project context files, and installs the /forge slash command into Claude Code.

Prerequisites: Claude Code CLI, Node.js 18+, Git

Quick Start

# Start the Planning Hub (multi-expert planning session)
/forge

# Or jump straight to planning a feature
/forge plan user authentication

# Spawn a worker agent in a new terminal tab
/forge spawn anvil

# Check what's happening
/forge status

# See all commands
/forge help

Agents

Planning Hub (Your Terminal)

When you run /forge, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:

| Voice | Icon | Speaks When | |-------|------|-------------| | Forge Master | :fire: | Tasks, assignments, workflow, coordination | | Architect | :classical_building: | Architecture, patterns, tech decisions | | Aegis | :shield: | Auth, security, vulnerabilities | | Ember | :gear: | DevOps, CI/CD, deployment | | Pixel | :art: | UX, user flows, accessibility | | Oracle | :bar_chart: | Requirements, scope, priorities | | Crucible | :test_tube: | Edge cases, test strategy, quality | | Loki | :performing_arts: | Challenges assumptions, lateral thinking |

Worker Agents (Separate Terminals)

Spawn these into new terminal tabs to execute tasks:

| Agent | Aliases | Role | |-------|---------|------| | anvil | frontend, ui, fe | Frontend Developer | | furnace | backend, api, be | Backend Developer | | crucible | test, qa | Tester / QA | | scribe | docs, documentation | Documentation | | herald | release, deploy | Release Manager | | ember | devops, infra | DevOps Engineer |

Review Agents

| Agent | Aliases | Role | |-------|---------|------| | temper | review, cr | Code Reviewer (compliance + correctness) | | crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |

Specialists

| Agent | Aliases | Role | |-------|---------|------| | architect | arch, sage | System Architect | | aegis | security, sec | Security Specialist | | pixel | ux, ui-design | UX Designer | | oracle | product, po | Product Owner | | loki | brainstorm, contrarian | Assumption Challenger |

Red Team

| Agent | Aliases | Role | |-------|---------|------| | slag | redteam, pentest | Red Team Lead | | flux | infra-sec, chaos | Infrastructure Security |

How It Works

Planning Mode

When you describe a goal, the Hub enters a 4-phase planning flow:

1. Discovery - Oracle asks clarifying questions about users, goals, constraints
2. Decomposition - Architect breaks the goal into epics with success metrics
3. Tasking - Forge Master creates stories and tasks, assigns to agents
4. Commit - Epic and task files written to disk, ready for workers

Task System

Tasks flow through folders on disk. No database required.

pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
                                            |
                                     needs-changes/ (back to worker)

Workers pick up tasks from pending/ on startup. Temper reviews completed work. The daemon routes tasks automatically.

Daemon

An optional background daemon monitors the forge:

./bin/forge.sh daemon start    # Start background monitoring
./bin/forge.sh daemon status   # Check what's happening
./bin/forge.sh daemon stop     # Stop the daemon

The daemon provides:

• Task routing between folders
• Agent status tracking
• Token budget warnings for long-running agents
• Dependency resolution (respects blocked_by in task files)
• Attention notifications when agents need help

Dashboard

A web dashboard at http://localhost:2800 shows:

• Task counts and status
• Agent activity feed
• Issue detection
• Real-time updates via WebSocket

Per-Project Customization

Add agent-specific rules for your project in context/agent-overrides/:

<!-- context/agent-overrides/anvil.md -->
- Use Tailwind CSS, no custom CSS files
- All components in src/components/ with PascalCase
- Use shadcn/ui for base components

These rules are injected into the agent's system prompt at spawn time.

Project Structure

your-project/
  _vibe-forge/
    agents/           # Agent personalities (16 agents)
    bin/              # CLI, daemon, dashboard, spawn scripts
    config/           # agents.json, task templates
    context/          # Project context, agent overrides
    specs/            # Epics and stories
    tasks/            # Task lifecycle folders
    docs/             # Security, architecture, agent docs

Commands Reference

| Command | Description | |---------|-------------| | /forge | Start the Planning Hub | | /forge plan <feature> | Plan a feature with the full team | | /forge status | Show status dashboard | | /forge spawn <agent> | Spawn worker in new terminal | | /forge task [desc] | Create a new task | | /forge redteam [scope] | Launch red team engagement | | /forge help | Show all commands |

Security

Vibe Forge uses a defense-in-depth permission model:

1. Allowlist (.claude/settings.json) - Pre-approves safe operations
2. Heimdall (pre-tool hook) - Enforces forge policies (branch protection, naming)
3. Claude Code prompts - Anything not allowlisted still requires approval

See docs/security.md for the full security model.

License

MIT