Forge

module

v0.9.0 Latest Latest Go to latest Published: Mar 20, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Robin831/Forge

Links

Open Source Insights

README ¶

The Forge

An autonomous AI orchestrator that coordinates multiple Claude Code agents working across FHI repositories. The Forge monitors beads (issues), spawns AI workers in isolated git worktrees, reviews their output, and manages the full lifecycle from implementation through PR creation.

Naming

The Forge uses a blacksmith metaphor throughout:

Component	Role
Hearth	Daemon process + TUI dashboard
Smith	Implementation worker (Claude Code session)
Warden	Review agent (validates Smith output, learns rules)
Temper	Build/lint/test verification (Go, .NET, Node)
Bellows	PR monitor (CI failures, review comments, merge conflicts)
Schematic	Pre-analysis worker (decomposes complex beads)
Crucible	Epic orchestrator (parent-child beads on feature branches)
Depcheck	Multi-language dependency update scanner (Go, .NET, Node)
Anvil	Repository workspace
Heat	Work batch / session

Architecture

┌──────────────────────────────────────────────────────┐
│  Hearth (daemon)                                     │
│  ┌─────────┐  ┌──────────┐  ┌───────────┐           │
│  │ Poller  │  │ WorkerPool│  │ Bellows   │           │
│  │(bd ready)│  │(Smiths)  │  │(PR watch) │           │
│  └─────────┘  └──────────┘  └───────────┘           │
│  ┌──────────┐ ┌──────────┐  ┌───────────┐           │
│  │ Depcheck │ │ Crucible │  │ Watchdog  │           │
│  │(dep scan)│ │(epics)   │  │(stale det)│           │
│  └──────────┘ └──────────┘  └───────────┘           │
│        │            │              │                 │
│        ▼            ▼              ▼                 │
│  ┌──────────────────────────────────────┐            │
│  │    SQLite state.db  │  Cost Tracker  │            │
│  └──────────────────────────────────────┘            │
│        │                                             │
│        ▼                                             │
│  ┌──────────────────────────────────────┐            │
│  │     Named Pipe / Unix Socket IPC     │            │
│  └──────────────────────────────────────┘            │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────┐
│  TUI (Hearth)                        │
│  Queue    │         │ Live Activity  │
│  Crucibles│ Workers │ Events         │
│  R.Merge  │         │                │
│  Attn     │         │                │
└──────────────────────────────────────┘

Quick Start

# Build
go build -o forge ./cmd/forge

# Check installation health
forge doctor

# Configure anvils (repositories to orchestrate)
forge anvil add heimdall C:\source\fhigit\Heimdall
forge anvil add metadata C:\source\fhigit\Fhi.Metadata

# Start the daemon
forge up

# Open TUI dashboard
forge hearth

# Check status
forge status

# View work history and events
forge history
forge history events

Configuration

Create forge.yaml in the working directory or ~/.forge/config.yaml:

anvils:
  heimdall:
    path: C:\source\fhigit\Heimdall
    max_smiths: 2
    auto_dispatch: all  # all | tagged | priority | off
  metadata:
    path: C:\source\fhigit\Fhi.Metadata
    max_smiths: 2
    auto_dispatch: tagged
    auto_dispatch_tag: 'forge-auto'
  legacy-repo:
    path: C:\source\fhigit\Legacy
    auto_dispatch: priority
    auto_dispatch_min_priority: 1  # Only P0 and P1

settings:
  poll_interval: 5m
  smith_timeout: 30m
  max_total_smiths: 3
  max_pipeline_iterations: 5   # Smith-Warden cycles in the pipeline loop (default 5)
  max_review_attempts: 2
  max_ci_fix_attempts: 5       # CI fix cycles per PR (default 5)
  max_review_fix_attempts: 5   # Review fix cycles per PR (default 5)
  max_rebase_attempts: 3       # Conflict rebase attempts per PR (default 3)
  daily_cost_limit: 50.00      # USD per day; 0 = no limit
  copilot_daily_request_limit: 300  # 300 for Pro, 1500 for Pro+; 0 = no limit
  bellows_interval: 2m         # PR monitor poll interval
  merge_strategy: squash       # squash | merge | rebase
  providers:
    - claude
    - gemini
  smith_providers:             # Optional: separate chain for Smith/Warden
    - claude/claude-opus-4-6
  schematic_enabled: false     # Pre-analysis for complex beads
  schematic_word_threshold: 100
  crucible_enabled: false      # Epic orchestration for parent-child beads
  depcheck_interval: 168h      # Dependency scan interval (0 to disable)
  vulncheck_enabled: true      # Vulnerability scanning with govulncheck
  vulncheck_interval: 24h     # Vuln scan interval (0 to disable)
  auto_learn_rules: false      # Learn Warden rules from Copilot review comments
  stale_interval: 5m           # Stale worker detection (0 to disable)
  claude_flags:
    - --dangerously-skip-permissions
    - --max-turns
    - "50"

notifications:
  enabled: false
  teams:
    webhook_url: https://outlook.webhook.office.com/webhookb2/...
    events:                    # Empty = all events
      - pr_created
      - bead_failed
      - daily_cost
  webhooks:                    # Generic JSON webhook targets (optional)
    - name: my-dashboard
      url: https://example.com/api/webhooks/forge
      events: [pr_created, worker_done, release]

See docs/configuration.md for the full reference.

Auto-Dispatch Modes

Mode	Description
`all`	(Default) Dispatch all ready beads found in the anvil.
`tagged`	Only dispatch beads where one of the bead's tags exactly matches `auto_dispatch_tag` (case-insensitive).
`priority`	Only dispatch beads with priority <= `auto_dispatch_min_priority`.
`off`	Never auto-dispatch; beads must be started manually via `forge queue run`.

Worker Pipeline

bd ready → Claim bead → Create worktree → [Schematic (optional pre-analysis)]
    → Smith (Claude) → Temper (build/test) → Warden (review)
    → PR creation → bd close → Bellows (monitor PR, CI fix, review fix, rebase)

Each step is tracked in SQLite state.db with full event logging and cost tracking.

Crucible (Epic Orchestration)

When a ready bead has children (blocks other beads), the Crucible takes over:

Detect parent bead → Create feature branch (feature/<parent-id>)
    → Topological sort children → For each child: pipeline → PR → merge to feature branch
    → Final PR (feature branch → main) → Bellows monitors → Close parent on merge

Enable with crucible_enabled: true in forge.yaml.

Dependency Scanning

The depcheck monitor periodically scans anvils for outdated dependencies across multiple ecosystems:

Go: go list -m -u all
Node: npm/yarn outdated detection
.NET: NuGet package update detection

Patch and minor updates produce auto-dispatch beads; major version bumps produce "needs attention" beads for manual review. Configure via depcheck_interval (default: weekly) and depcheck_timeout. Set depcheck_interval: 0 to disable.

Vulnerability Scanning

The daemon runs govulncheck on Go anvils on a configurable schedule (default: daily). Discovered vulnerabilities automatically create prioritized beads. Run manually with forge scan. Configure via vulncheck_interval and vulncheck_enabled.

Warden Rule Learning

The Warden can learn review rules from GitHub Copilot comments on merged PRs. Learned rules are stored per-anvil in .forge/warden-rules.yaml and applied during future reviews. Enable with auto_learn_rules: true, or manage manually:

forge warden learn --anvil heimdall    # Learn from recent PR comments
forge warden list --anvil heimdall     # List learned rules
forge warden forget <rule-id> --anvil heimdall  # Remove a rule

Cost Tracking

Token usage and USD cost estimates are tracked per-bead and per-day. Set daily_cost_limit to automatically pause auto-dispatch when the daily budget is exceeded. View current costs via forge status.

Notifications

Forge supports two webhook notification styles:

MS Teams — Rich Adaptive Cards for key events (PR created, bead failed, daily cost, worker done, bead decomposed). Configure under notifications.teams.
Generic webhooks — Simple JSON payloads sent to any HTTP endpoint. Each target can filter events independently. Configure under notifications.webhooks[].

See the notifications section of forge.yaml and docs/configuration.md for the full reference.

Requirements

Go 1.26+
bd (beads) — issue tracker
claude — Claude Code CLI
gh — GitHub CLI (authenticated)
git — with worktree support

Run forge doctor to verify all dependencies are installed and configured correctly.

Project Structure

Forge/
├── cmd/forge/            # CLI entry point (Cobra commands)
│   └── main.go
├── internal/
│   ├── bellows/          # PR monitoring (CI fix, review fix, rebase)
│   ├── changelog/        # Changelog fragment parsing & assembly
│   ├── cifix/            # CI failure fix worker
│   ├── config/           # Viper-based configuration
│   ├── cost/             # Token usage & USD cost tracking
│   ├── crucible/         # Parent-child bead orchestration (epic branches)
│   ├── daemon/           # Main background process, poll loop, IPC server
│   ├── depcheck/         # Multi-language dependency update scanner
│   ├── executil/         # Platform-specific process execution
│   ├── vcs/              # VCS provider interface & GitHub implementation
│   ├── hearth/           # Bubbletea TUI dashboard
│   ├── hotreload/        # fsnotify config watcher
│   ├── ipc/              # Named pipe / Unix socket protocol
│   ├── lifecycle/        # Worker lifecycle management
│   ├── notify/           # MS Teams webhook notifications
│   ├── pipeline/         # Smith → Temper → Warden orchestration
│   ├── poller/           # bd ready integration & Crucible detection
│   ├── prompt/           # Smith prompt builder
│   ├── provider/         # AI provider fallback chain
│   ├── rebase/           # Conflict rebase handling
│   ├── retry/            # Exponential backoff & retry logic
│   ├── reviewfix/        # Review comment fix worker
│   ├── schematic/        # Pre-analysis worker (decompose complex beads)
│   ├── shutdown/         # Graceful shutdown & orphan cleanup
│   ├── smith/            # Claude Code worker spawning & lifecycle
│   ├── state/            # SQLite state management (WAL mode)
│   ├── temper/           # Build/lint/test verification (Go, .NET, Node)
│   ├── vulncheck/        # Vulnerability scanning (govulncheck)
│   ├── warden/           # Code review agent & rule learning
│   ├── watchdog/         # Stale worker detection
│   ├── worker/           # Worker process abstraction
│   └── worktree/         # Git worktree creation/removal
├── docs/                 # Reference documentation
├── changelog.d/          # Changelog fragments (per-bead)
├── forge.yaml            # Configuration (user-created)
├── go.mod
├── go.sum
├── AGENTS.md
├── README.md
└── LICENSE

License

MIT — see LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
forge command
listprs command Temporary tool to list all open PRs with fix counters.	Temporary tool to list all open PRs with fix counters.
resetpr command Temporary tool to reset PR fix counters in state.db Usage: go run ./cmd/resetpr <pr_number> [pr_number ...]	Temporary tool to reset PR fix counters in state.db Usage: go run ./cmd/resetpr <pr_number> [pr_number ...]
internal
adventurer
autostart Package autostart generates and manages Windows Task Scheduler definitions for starting the Forge daemon automatically at user logon.	Package autostart generates and manages Windows Task Scheduler definitions for starting the Forge daemon automatically at user logon.
bellows Package bellows monitors open PRs for status changes, CI results, and reviews.	Package bellows monitors open PRs for status changes, CI results, and reviews.
changelog Package changelog handles changelog fragment parsing and assembly.	Package changelog handles changelog fragment parsing and assembly.
cifix Package cifix spawns a Smith worker to fix CI failures on a PR branch.	Package cifix spawns a Smith worker to fix CI failures on a PR branch.
config Package config handles loading and validating Forge configuration from forge.yaml files and environment variable overrides.	Package config handles loading and validating Forge configuration from forge.yaml files and environment variable overrides.
cost Package cost tracks token usage and estimated costs from Claude CLI output.	Package cost tracks token usage and estimated costs from Claude CLI output.
crucible Package crucible orchestrates parent beads with children on feature branches.	Package crucible orchestrates parent beads with children on feature branches.
daemon Package daemon implements The Forge's background daemon process.	Package daemon implements The Forge's background daemon process.
depcheck Package depcheck periodically checks registered anvils for outdated dependencies, starting with Go and designed to support additional ecosystems (.NET, npm) in the future.	Package depcheck periodically checks registered anvils for outdated dependencies, starting with Go and designed to support additional ecosystems (.NET, npm) in the future.
executil Package executil provides helpers for spawning subprocesses.	Package executil provides helpers for spawning subprocesses.
forge Package forge provides core types and constants for The Forge orchestrator.	Package forge provides core types and constants for The Forge orchestrator.
hearth Package hearth provides The Forge's TUI dashboard using Bubbletea.	Package hearth provides The Forge's TUI dashboard using Bubbletea.
hotreload Package hotreload watches forge.yaml for changes and applies safe updates to the running daemon without a restart.	Package hotreload watches forge.yaml for changes and applies safe updates to the running daemon without a restart.
ingot Package ingot provides the data model and persistence layer for Ingots.	Package ingot provides the data model and persistence layer for Ingots.
ipc Package ipc provides inter-process communication between the Forge daemon and CLI/TUI clients via platform-native mechanisms (named pipe on Windows, Unix domain socket on Linux/macOS).	Package ipc provides inter-process communication between the Forge daemon and CLI/TUI clients via platform-native mechanisms (named pipe on Windows, Unix domain socket on Linux/macOS).
lifecycle Package lifecycle manages the end-to-end PR lifecycle state machine.	Package lifecycle manages the end-to-end PR lifecycle state machine.
notify Package notify sends notifications to webhook endpoints.	Package notify sends notifications to webhook endpoints.
pipeline Package pipeline orchestrates the full Smith → Temper → Warden → feedback loop.	Package pipeline orchestrates the full Smith → Temper → Warden → feedback loop.
poller Package poller provides the BeadPoller which discovers ready work across registered anvils by invoking 'bd ready --json' in each anvil directory.	Package poller provides the BeadPoller which discovers ready work across registered anvils by invoking 'bd ready --json' in each anvil directory.
prompt Package prompt builds prompts for Smith (Claude Code) workers from bead metadata.	Package prompt builds prompts for Smith (Claude Code) workers from bead metadata.
provider Package provider defines the AI provider abstraction for Forge.	Package provider defines the AI provider abstraction for Forge.
questgiver
rebase Package rebase resolves merge conflicts by rebasing a PR branch onto main.	Package rebase resolves merge conflicts by rebasing a PR branch onto main.
retry Package retry implements exponential backoff retry logic for failed beads.	Package retry implements exponential backoff retry logic for failed beads.
reviewfix Package reviewfix spawns a Smith worker to address PR review comments.	Package reviewfix spawns a Smith worker to address PR review comments.
schematic Package schematic implements the pre-worker that analyses bead scope before Smith starts.	Package schematic implements the pre-worker that analyses bead scope before Smith starts.
shutdown Package shutdown manages graceful daemon shutdown and orphan prevention.	Package shutdown manages graceful daemon shutdown and orphan prevention.
smith Package smith manages Claude Code CLI process spawning for Smith workers.	Package smith manages Claude Code CLI process spawning for Smith workers.
state Package state manages the SQLite state database for The Forge.	Package state manages the SQLite state database for The Forge.
temper Package temper runs build, lint, and test verification in a worktree.	Package temper runs build, lint, and test verification in a worktree.
vcs Package vcs defines the VCS (Version Control System) provider interface that abstracts platform-specific operations (PR creation, merging, status checks, etc.) so Forge can work with GitHub, GitLab, Forgejo, Bitbucket, and Azure DevOps.	Package vcs defines the VCS (Version Control System) provider interface that abstracts platform-specific operations (PR creation, merging, status checks, etc.) so Forge can work with GitHub, GitLab, Forgejo, Bitbucket, and Azure DevOps.
vcs/github Package github implements the vcs.Provider interface for GitHub using the gh CLI.	Package github implements the vcs.Provider interface for GitHub using the gh CLI.
vulncheck Package vulncheck runs govulncheck on registered anvils and creates beads for discovered vulnerabilities.	Package vulncheck runs govulncheck on registered anvils and creates beads for discovered vulnerabilities.
warden Package warden implements the code review agent that reviews Smith's changes.	Package warden implements the code review agent that reviews Smith's changes.
watchdog Package watchdog provides timeout enforcement for Smith worker processes.	Package watchdog provides timeout enforcement for Smith worker processes.
worker Package worker implements the Worker lifecycle state machine (FSM).	Package worker implements the Worker lifecycle state machine (FSM).
worktree Package worktree manages git worktree creation and teardown for Smith workers.	Package worktree manages git worktree creation and teardown for Smith workers.