# opencode-forgecode
**The all-in-one OpenCode plugin for autonomous development workflows.**
Iterative loops · Multi-agent orchestration · Code graph · Sandboxed execution · Smart harness
[](https://www.npmjs.com/package/opencode-forgecode) [](LICENSE) []()
---
## What is this?
`opencode-forgecode` is a single plugin for [OpenCode](https://opencode.ai) that gives your AI agents the ability to plan, execute, review, and iterate — autonomously. It combines two systems into one cohesive runtime:
| | |
| --- | --- |
| **Forge** | Iterative development loops with git worktree isolation, session-scoped plans, code-graph indexing, Docker/Firejail/Bubblewrap sandboxing, background tasks, and a TUI sidebar |
| **Harness** | Summary-frame compaction, output truncation, doom-loop detection, pending-todo reminders, undo snapshots, and the multi-agent system (9 specialized agents) |
Both systems share the same plugin entrypoint — no conflicts over hooks, no duplicate compaction, no fighting for `tool.execute.*`.
---
## Quick Start
### 1. Install
```bash
npm add opencode-forgecode
```
### 2. Configure OpenCode
**`opencode.json`:**
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-forgecode@latest"],
"compaction": { "auto": true, "prune": true },
"agent": {
"forge": { "model": "anthropic/claude-opus-4.7" },
"muse": { "model": "openai/gpt-5.4" },
"sage": { "model": "openai/gpt-5.4-mini" }
}
}
```
### 3. Enable TUI sidebar (optional)
**`~/.config/opencode/tui.json`:**
```json
{
"$schema": "https://opencode.ai/tui.json",
"plugin": ["opencode-forgecode@latest"]
}
```
### 4. Done
On first run the plugin auto-creates `~/.config/opencode/forge-config.jsonc` with sensible defaults. Run `oc-forgecode doctor` to verify everything is wired correctly.
---
## Agents
The plugin ships **9 specialized agents**, all registered automatically on load:
### Core Trinity
| Agent | Role | Mode | Description |
| --- | --- | --- | --- |
| **forge** | Coder | primary | Graph-first code discovery, read/write/bash access, harness-aware. The workhorse. |
| **muse** | Planner | primary | Strategic planning with KV-backed plan store. All file edits denied. Two-step approval flow before any execution. |
| **sage** | Reviewer | subagent | Dual-mode: code review on diffs/PRs or deep research on architecture. Read-only, temp 0.0. |
### Extended Agents
| Agent | Role | Description |
| -------------- | --------------- | ----------------------------------------------------------------------- |
| **explore** | Explorer | Parallel codebase discovery — optimized for broad, open-ended questions |
| **oracle** | Q&A | Short, precise answers to specific codebase questions |
| **librarian** | Researcher | Information retrieval using read-only tools |
| **prometheus** | Generator | Scaffolding, boilerplate, migrations, templates |
| **metis** | Meta-agent | Analyzes context and recommends which agent to use next |
| **caveman** | Efficiency mode | Cuts ~75% output tokens while keeping technical substance |
Agents can call each other via `bg_spawn` (Sisyphus-style delegation) or the `tool_supported` agent-as-tool pattern.
---
## Tools
### 📝 Plan & Review
| Tool | Description |
| --------------- | ---------------------------------------------------------------------------------- |
| `plan-write` | Store a plan skeleton (auto-keyed to `plan:{sessionID}`, 7-day TTL, 8 KB soft cap) |
| `plan-append` | Append a section to the stored plan (for incremental, timeout-safe writes) |
| `plan-edit` | Find-and-replace within the stored plan (supports `replace_all` / `occurrence`) |
| `plan-read` | Retrieve plan with pagination and pattern search |
| `plan-execute` | Launch plan execution as a new forge session |
| `review-write` | Store review findings (file, line, severity, description) |
| `review-read` | Query findings by file path or regex |
| `review-delete` | Remove a finding by file and line |
### 🔁 Loops
| Tool | Description |
| ------------- | ---------------------------------------------------------------------- |
| `loop` | Run an iterative dev loop. `worktree: true` for git worktree isolation |
| `loop-status` | List active loops or get details by name. `restart` to resume |
| `loop-cancel` | Cancel a running loop |
### 🕸️ Code Graph
| Tool | Description |
| --- | --- |
| `graph-status` | Check indexing status or trigger a re-scan |
| `graph-query` | File-level: `top_files`, `file_deps`, `file_dependents`, `cochanges`, `blast_radius`, `packages`, `file_symbols` |
| `graph-symbols` | Symbol-level: `find`, `search`, `signature`, `callers`, `callees`, `blast_radius`, `call_cycles` |
| `graph-analyze` | Quality: `unused_exports`, `duplication`, `near_duplicates` |
### 🔧 Editing & Undo
| Tool | Description |
| ------------- | ---------------------------------------------------------------------- |
| `patch` | Hash-anchored `LINE#HASH` replacements — resilient to concurrent edits |
| `multi_patch` | Atomic multi-replacement on a single file (tempfile + rename) |
| `fs_undo` | Restore from automatic pre-edit snapshots |
### 🧠 Code Intelligence
| Tool | Description |
| ------------------ | ------------------------------------------------------------- |
| `lsp_diagnostics` | Fetch diagnostics from language servers |
| `lsp_hover` | Get type info and docs for a symbol |
| `lsp_references` | Find all references to a symbol |
| `lsp_definition` | Jump to definition |
| `lsp_code_actions` | Get available code actions |
| `lsp_rename` | Rename a symbol across the project |
| `ast_search` | Structural code search via `ast-grep` patterns |
| `ast_rewrite` | Structural code rewrites via `ast-grep` |
| `sem_search` | Semantic search with embeddings (OpenAI / fastembed / Voyage) |
| `code-stats` | Language / LOC summary via `tokei` → `scc` → `rg` fallback |
### ⚡ Background Tasks
| Tool | Description |
| ----------- | -------------------------------------- |
| `bg_spawn` | Launch an agent as a background task |
| `bg_status` | Check status of background tasks |
| `bg_wait` | Wait for a background task to complete |
| `bg_cancel` | Cancel a running background task |
---
## Slash Commands
| Command | Description | Agent |
| -------------- | ------------------------------------ | ----- |
| `/review` | Run a code review on current changes | sage |
| `/loop` | Start an iterative development loop | forge |
| `/loop-status` | Check status of all active loops | forge |
| `/loop-cancel` | Cancel the active loop | forge |
---
## CLI
```bash
oc-forgecode