OpenCode Forger: Autonomous Development Engine

OpenCode Forger is an elite Rust-based CLI orchestration tool designed to automate the "Vibe Loop" for OpenCode. It transforms high-level product specifications into production-ready codebases by managing an iterative cycle of implementation, verification, and refinement.

Built for high-velocity engineering, Forger uses a stateful architecture powered by SQLite, a modular template system for lean AI context handling, and parallel execution via Git worktrees to implement complex features concurrently.

🚀 Installation

Forger is designed to integrate seamlessly into your development environment. Use the following methods to get started:

Build from Source (Recommended)

Clone the repository and build the optimized release binary:

git clone https://github.com/nocturnlabs/opencode-forger.git
cd opencode-forger
make build
# Binary located at ./target/release/opencode-forger

Quick Setup Utility

Use the included init.sh script to automate dependency checks and build:

./init.sh

Global Installation

To make Forger available system-wide:

make install
# Installs to ~/.cargo/bin/

🚦 Getting Started

1. Interactive Scaffolding (Quick Start)

The easiest way to start a new project is through the Interactive TUI. It guides you through defining your project type, tech stack, and core features.

opencode-forger init --interactive

2. Autonomous Mode (Advanced)

Once a project is scaffolded, use the vibe command to start the autonomous development loop.

opencode-forger vibe --developer

!NOTE The --developer flag enables detailed debug logging to opencode-debug.log while maintaining a clean status display in your terminal.

🧠 Core Features

The Vibe Loop

The "Vibe Loop" is the heart of Forger. It is a 5-phase state machine that governs autonomous progress:

1. Phase 1: Auto-Init: Scaffolds the initial structure if the project is empty.
2. Phase 2: Auto-Context: Establishes product and technical context in .conductor/.
3. Phase 3/4: Auto-Continue: Executes implementation tasks based on prioritized features.
4. Phase 5: Check & Plan: Verifies outcomes and calculates the next failing feature to implement.

Dual-Model Architecture

To maximize reasoning quality while minimizing costs, Forger separates "Thinking" from "Doing":

• Reasoning Model: (e.g., opencode/big-pickle) Architects plans, reviews code, and manages the project structure.
• Coding Subagent: (e.g., opencode/grok-code) A specialized agent (@coder) that executes implementation steps exactly as planned.

Parallel Execution

Forger can run multiple features concurrently by leveraging Git Worktrees.

• Coordinator: Manages a pool of workers.
• Merge Strategy: Each feature is implemented on a separate branch and merged via rebase_and_merge upon passing verification.
• Use --parallel N to specify the number of workers (default is auto-detected).

SQLite Persistence

Forget JSON-based state tracking. Forger uses a robust SQLite database (.forger/progress.db) to store:

• Features: Descriptions, steps, passing status, and verification history.
• Sessions: Detailed logs and token stats for every AI interaction.
• Knowledge Base: Persistent facts (e.g., API ports, database paths) that agents recall across sessions.

📋 Specification & Format Reference

Project Specification (app_spec.md)

The app_spec.md is the "source of truth" for your project. Forger parses this file to generate the initial feature_list.json and database entries.

# [Project Name]
## Tech Stack
- Frontend: [e.g. Next.js]
- Backend: [e.g. Supabase]

## Database Schema
[SQL or Mermaid diagram]

## Features
- [ ] Feature 1: Description...
- [ ] Feature 2: Description...

Template System: Progressive Discovery

Forger uses a modular template system at templates/ to keep AI context windows lean.

• Core: Identity and Security rules included in every prompt.
• Modules: Domain-specific expertise (e.g., rust.md, javascript.md) injected only when needed.
• Commands: Command-specific logic (auto-init, auto-continue).

🔒 Security & Configuration

Configuration (forger.toml)

Configure Forger's behavior globally or per-project. This file is typically located at .forger/config.toml within your project root.

Security Constraints

Forger protects your system via a Security Allowlist (scripts/security-allowlist.json) and blocked patterns:

!IMPORTANT By default, Forger blocks dangerous patterns like rm -rf /, sudo, and chmod 777. All shell commands are logged and checked against the allowlist if enforce_allowlist is enabled. If a command is blocked, the agent will attempt to find an alternative secure approach.

⌨️ CLI Reference

vibe

Start the autonomous loop. This is the primary command for production development.

• --limit <N>: Run only N iterations.
• --parallel <N>: Enable parallel execution (uses git worktrees).
• --single-model: Disable the dual-model split (not recommended for complex tasks).

Example Output:

[18:30:12] INFO  Initializing Vibe Loop...
[18:30:13] INFO  Current Progress: 12/45 Features Passing [▓▓░░░░░░░░░░░░░░] 26%
[18:30:15] INFO  Action: auto-continue (Feature: #13 - User Login)
[18:30:20] EXEC  Running OpenCode session (Model: opencode/grok-code)...
[18:31:45] PASS  Feature #13 Verified! (Auto-committing to git...)
[18:31:47] INFO  Sleeping for 5s...

db

Manage the SQLite persistence layer. Crucial for resetting state or inspecting progress.

• db stats: Show project completion metrics.
• db next-feature: Identify the next target for implementation.
• db knowledge set <key> <value>: Manually inject persistent knowledge.
• db query "SELECT * FROM features WHERE category='style'": Run manual SQL queries.

Example: db stats Output

+----------------------+-------+
| Metric               | Value |
+----------------------+-------+
| Total Features       | 45    |
| Passing Features     | 12    |
| Failing Features     | 33    |
| Completion           | 26.7% |
| Total Sessions       | 8     |
| Total Cost (Est)     | $0.42 |
+----------------------+-------+

templates

Explore and use scaffolding templates.

• templates list: Show available project types.
• templates use web-app --output ./my-new-app: Instantly scaffold a project.

example

Access a wealth of knowledge on different topics:

• example security: Show security policy templates.
• example db: View feature schema and SQL query tips.
• example workflow: Breakdown of the Vibe Loop phases.

Example: example workflow Output

VIBE LOOP WORKFLOW:
1. INIT     -> Scaffold structure (if empty)
2. CONTEXT  -> Establish .conductor/ context
3. CONTINUE -> Implement prioritized feature
4. VERIFY   -> Run verification steps
5. RETRY    -> Generate alternative approach (if stalled)
6. MERGE    -> Commit and rebase (if parallel)

© 2026 NocturnLabs. Advanced Agentic Coding for the Era of Autonomous Software.