Agent Forge - OpenCode Plugin

Modular block-based agent/subagent definition system for OpenCode

Create custom AI agents using simple Markdown files with optional, composable building blocks.

Installation

bun add @nasr-shaer/agent-forge

Or add to your .opencode/config.yaml:

plugin:
  - "@nasr-shaer/agent-forge"

Restart OpenCode after installation.

Quick Start

1. Create your first agent interactively

/forge forge-creator

The interactive creator will guide you through:

• Choosing a name and description
• Selecting which blocks to include
• Configuring each block
• Saving the agent to .opencode/agents/

2. Use your agent

/forge <your-agent-name>

3. List available agents

/forge

4. Reload agents (after creating new ones)

/forge --reload

Newly created agents are automatically discovered without restarting OpenCode!

Available Blocks

All blocks are optional and composable. Pick only what you need:

| Block | Purpose | |-------|---------| | Variables | Session-scoped key-value state | | Parameters | Typed inputs with hints, validation, and defaults | | Workflow | Numbered step-by-step execution plan | | Report | Output format and structure definition | | Delegation | Rules for delegating to other agents | | Examples | Code/usage examples | | Codebase Structure | File scanning paths and conventions | | Expertise | Role, domains, knowledge, tone | | Guards | Pre/post conditions, invariants, error handling | | Git Consideration | Commit style, branch strategy, rules |

Manual Agent Creation

Create a file in .opencode/agents/my-agent.md:

---
description: What this agent does
mode: primary
blocks:
  - expertise
  - workflow
  - parameters
---

## Expertise
role: Your agent's role
domains:
  - Domain 1
  - Domain 2
tone: Helpful and professional

## Workflow
1. Step one
2. Step two
3. Step three

## Parameters
- name: input_file
  type: string
  required: true
  hint: "Path to input file"

Then activate with /forge my-agent.

Features

• Hot Reload: New agents are immediately available - no OpenCode restart needed!
• Interactive Creation: Use forge-creator to build agents through a guided conversation
• Typed Parameters: Define inputs with type checking, validation, and hints
• Composable Blocks: Mix and match only the blocks you need
• Per-Agent Commands: Auto-generated shortcuts like /forge-my-agent
• Markdown-Based: Simple, readable, version-controllable agent definitions
• Session State: Variables and parameters scoped to each session
• OpenCode Native: Integrates seamlessly with OpenCode's plugin system

Architecture

The plugin works by:

1. Scanning .opencode/agents/ and agents/ for .md files at startup
2. Parsing frontmatter and block sections
3. Registering /forge command and per-agent shortcuts
4. Hot-reloading: Automatically discovering newly created agents via command interception
5. Injecting agent instructions into system prompt when activated
6. Managing session state for variables and parameters

Hot Reload Mechanism: The plugin uses OpenCode's tui.command.execute hook to intercept /forge commands and dynamically reload agents from the filesystem before looking them up in memory. This means agents created during your session are immediately available without restarting OpenCode.

Examples

Code Reviewer Agent

---
description: Reviews code changes for quality and best practices
mode: primary
blocks:
  - expertise
  - guards
  - workflow
  - git-consideration
---

## Expertise
role: Senior code reviewer
domains:
  - TypeScript
  - React
  - Testing
  
## Workflow
1. Review changed files
2. Check for anti-patterns
3. Suggest improvements
4. Verify tests exist

Documentation Agent

---
description: Generates documentation from code
mode: primary
blocks:
  - parameters
  - workflow
  - report
---

## Parameters
- name: target_dir
  type: string
  required: true
  hint: "Directory to document"
  
## Workflow
1. Scan files in target_dir
2. Extract docstrings and comments
3. Generate markdown docs
4. Save to docs/

## Report
format: markdown
structure:
  - Table of contents
  - API reference
  - Examples

Contributing

This plugin follows the architecture of subtask2.

License

Proprietary

Author

nasr.shaer [email protected]

Links

• npm: @nasr-shaer/agent-forge
• Documentation: Coming soon