Skip to content
/

OpenAgentsControl (OAC)

openagentscontrol · darrenhinde/OpenAgentsControl · ★ 4.2k · last commit 2026-03-25

Primitive shape 33 total
Commands 6 Skills 12 Subagents 14 Hooks 1
00

Summary

OpenAgentsControl (OAC) — Summary

OpenAgentsControl (OAC) is a plan-first, context-aware AI agent framework built on top of OpenCode CLI that teaches agents your coding patterns upfront and requires human approval before every execution. The system's central insight is "Minimal Viable Information" (MVI): instead of loading the whole codebase, a ContextScout subagent discovers and loads only the relevant pattern files before each code operation, cutting token overhead by up to 80%. OAC ships both an OpenCode-native agent pack (.opencode/agent/, .opencode/skill/) and a Claude Code plugin in plugins/claude-code/ with 7 specialized subagents, 12 skills, and 6 user commands. The approval-gate discipline is absolute: every bash/write/edit/task invocation requires explicit user approval before execution, making OAC the highest-guardrail option in the opencode ecosystem. Multi-language support spans TypeScript, Python, Go, Rust, C#, and more; model support is model-agnostic (Claude, GPT, Gemini, local).

Differs from seeds: closest to agent-os in that it organizes context as project-specific files loaded by agents at runtime, but OAC extends this with a mandatory 7-subagent pipeline (ContextScout, TaskManager, ContextManager, Coder, TestEngineer, CodeReviewer, ExternalScout) and a hard approval gate before every execution step — a control posture absent from agent-os. Unlike superpowers (which delegates via the Task tool) or claude-flow (which parallelizes), OAC is explicitly sequential with human-gated approval at each stage.

01

Overview

OpenAgentsControl (OAC) — Overview

Origin

OpenAgentsControl was created by Darren Hinde (@DarrenBuildsAI) and published under the MIT license. It is built on top of the OpenCode CLI (opencode.ai), an open-source AI coding framework, with OAC extending it with specialized agents, context management, and team workflows. A Claude Code plugin (BETA) was added later as an alternative installation path. Version 0.7.1 as of the last analysis.

Philosophy

OAC's central conviction is that AI coding agents fail not because of model quality but because they lack project context. Generic AI writes generic code; context-loaded AI writes code matching team patterns.

"AI agents that learn YOUR coding patterns and generate matching code every time."

Three architectural opinions are non-negotiable:

  1. MVI (Minimal Viable Information) — context files stay under 200 lines; lazy-loading means you only pay for what you actually need.
  2. Approval Gates are always required"Propose → Approve → Execute" is the only allowed execution model. No autonomous execution.
  3. Editable agents — all agent behavior is in markdown files you can directly edit. No compilation, no vendor lock-in.

Manifesto-Style Quotes

"Most AI agents are like hiring a developer who doesn't know your codebase. They write generic code. You spend hours rewriting, refactoring, and fixing inconsistencies. Tokens burned. Time wasted. No actual work done."

"OpenAgentsControl teaches agents your patterns upfront. They understand your coding standards, your architecture, your security requirements. They propose plans before implementing. They execute incrementally with validation."

"Full control over AI behavior. Edit markdown files directly — no compilation, no vendor lock-in. Change workflows, add constraints, customize for your team."

Positioning vs. Competitors

From README comparison table (verbatim):

Feature OAC Cursor/Copilot Aider Oh My OpenCode
Learn Your Patterns Built-in No No Manual setup
Approval Gates Always required Optional (default off) No No
Token Efficiency MVI (80% reduction) Full context Full context High usage
Team Standards Shared context files Per-user No team support Manual config

"Use OAC when you have established coding patterns, want code that ships without refactoring, need approval gates for quality control, care about token efficiency."

02

Architecture

OpenAgentsControl (OAC) — Architecture

Distribution

  • Primary: OpenCode plugin installed via install.sh or npm install -g @nextsystems/oac (oac binary)
  • Secondary: Claude Code plugin (BETA) via /plugin marketplace add darrenhinde/OpenAgentsControl then /plugin install oac
  • npm package: @nextsystems/oac version 0.7.1 — ships a bin/oac.js binary

Install (OpenCode path)

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer
opencode --agent OpenAgent

Install (Claude Code plugin path)

/plugin marketplace add darrenhinde/OpenAgentsControl
/plugin install oac
/oac:setup --core

Directory Tree (.opencode/ primary)

.opencode/
  agent/
    core/
      openagent.md          # Primary universal agent
      opencoder.md          # Coder agent
    subagents/
      code/                 # build-agent, coder-agent, reviewer, test-engineer
      development/          # devops-specialist, frontend-specialist
      planning/             # adr-manager, architecture-analyzer, contract-manager, 
                            # prioritization-engine, story-mapper
      system-builder/       # agent-generator, command-creator, context-organizer, 
                            # domain-analyzer, workflow-designer
      utils/                # image-specialist
  skill/
    project-orchestration/  # 8-stage workflow + context handoff
    task-management/
  skills/
    context-manager/
    context7/
    smart-router-skill/
    task-management/
  context/                  # Project pattern files (user-added)
  scripts/
plugins/
  claude-code/              # Claude Code plugin
    agents/                 # 7 agents: code-reviewer, coder-agent, context-manager, 
                            # context-scout, external-scout, task-manager, test-engineer
    skills/                 # 12 skills: code-execution, code-review, context-discovery,
                            # context-setup, debugger, external-research, oac-approach,
                            # parallel-execution, task-breakdown, test-generation, 
                            # using-oac, verification-before-completion
    commands/               # 6 commands: brainstorm, debug, install-context, 
                            # oac-cleanup, oac-help, oac-status
    hooks/
    settings.json
bin/
  oac.js                    # CLI entry point

Required Runtime

  • Node.js >= 18.0.0
  • OpenCode CLI (primary path) OR Claude Code (plugin path)
  • Git (for worktree operations)

Target AI Tools

  • OpenCode CLI (primary)
  • Claude Code (BETA plugin)
  • Any model provider via OpenCode: Claude, GPT, Gemini, MiniMax, local models
03

Components

OpenAgentsControl (OAC) — Components

Claude Code Plugin Agents (7)

Name Purpose
task-manager.md Orchestrates workflow, breaks tasks into steps, manages delegation
context-scout.md Discovers and loads relevant context files; exempt from approval gate
context-manager.md Manages context file lifecycle, loading/unloading
coder-agent.md Implements code following loaded patterns
test-engineer.md Generates and runs tests against implementations
code-reviewer.md Reviews code for security, correctness, quality
external-scout.md Researches external libraries, APIs, and documentation

Claude Code Plugin Skills (12)

Name Purpose
using-oac Session start — requires invocation before any response
oac-approach Brainstorm before any build/create work
context-discovery Find patterns before implementing
context-setup Initialize context files for project
code-execution Execute code safely with validation
code-review Review code against loaded standards
debugger Structured debugging with hypothesis protocol
external-research Research external dependencies
parallel-execution Run multiple operations concurrently
task-breakdown Decompose large tasks into steps
test-generation Generate tests before or after implementation
verification-before-completion Gate before claiming task done

Claude Code Plugin Commands (6)

Name Purpose
brainstorm.md Structured brainstorm session
debug.md Debug session command
install-context.md Install context files from GitHub/URL/local
oac-cleanup.md Clean up session files
oac-help.md Show available skills and usage
oac-status.md Show current context and workflow state

OpenCode Skills (2 directories)

Name Purpose
project-orchestration 8-stage feature delivery + context handoff workflow
task-management Task tracking and delegation

OpenCode Subagents (14+)

Code: build-agent, coder-agent, reviewer, test-engineer
Development: devops-specialist, frontend-specialist
Planning: adr-manager, architecture-analyzer, contract-manager, prioritization-engine, story-mapper
System-builder: agent-generator, command-creator, context-organizer, domain-analyzer, workflow-designer
Utils: image-specialist

CLI Binary

oac — ships as bin/oac.js, entry point for the @nextsystems/oac npm package. Wraps OpenCode CLI with OAC-specific subcommands and context management.

Context System

Context files are markdown files (<200 lines, user-created) stored in .opencode/context/ with categories: core/standards/, core/workflows/, core/patterns/. ContextScout discovers and loads relevant files before each operation.

Hooks (Claude Code plugin)

hooks/session-start.sh — session initialization script. The plugins/claude-code/settings.json sets model to opusplan.

05

Prompts

OpenAgentsControl (OAC) — Prompts

Prompt 1: OpenAgent System Prompt (openagent.md)

Technique: Role + Permission Manifest + Critical Context Requirement + Absolute Rules

Verbatim excerpt from .opencode/agent/core/openagent.md:

---
name: OpenAgent
description: "Universal agent for answering queries, executing tasks, and coordinating workflows across any domain"
mode: primary
temperature: 0.2
permission:
  bash:
    "*": "ask"
    "rm -rf *": "ask"
    "rm -rf /*": "deny"
    "sudo *": "deny"
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
---
Always use ContextScout for discovery of new tasks or context files.
ContextScout is exempt from the approval gate rule. ContextScout is your secret weapon for quality, use it where possible.

<critical_context_requirement>
PURPOSE: Context files contain project-specific standards that ensure consistency, 
quality, and alignment with established patterns. Without loading context first, 
you will create code/docs/tests that don't match the project's conventions.

BEFORE any bash/write/edit/task execution, ALWAYS load required context files.
AUTO-STOP if you find yourself executing without context loaded.

Required context files:
- Code tasks → .opencode/context/core/standards/code-quality.md
- Docs tasks → .opencode/context/core/standards/documentation.md  
- Tests tasks → .opencode/context/core/standards/test-coverage.md
</critical_context_requirement>

<critical_rules priority="absolute" enforcement="strict">
  <rule id="approval_gate" scope="all_execution">
    Request approval before ANY execution (bash, write, edit, task).
  </rule>
  <rule id="stop_on_failure" scope="validation">
    STOP on test fail/errors - NEVER auto-fix
  </rule>
  <rule id="report_first" scope="error_handling">
    On fail: REPORT→PROPOSE FIX→REQUEST APPROVAL→FIX (never auto-fix)
  </rule>
</critical_rules>

Analysis: Uses XML-structured rules with priority/enforcement attributes, temperature-set at 0.2 for determinism, and filesystem permission manifests embedded in agent frontmatter.

Prompt 2: using-oac Skill (meta-skill for skill loading)

Technique: Self-referential meta-skill forcing mandatory skill invocation via decision graph

Verbatim excerpt from plugins/claude-code/skills/using-oac/SKILL.md:

<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance an OAC skill might apply to what you are doing, 
you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.
</EXTREMELY-IMPORTANT>

## The Rule

**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance 
a skill might apply means that you should invoke the skill to check.

Analysis: Uses capital emphasis and explicit impossibility-of-escape framing ("cannot rationalize your way out") to override LLM tendencies to skip tool calls. Includes a DOT-format decision graph as inline documentation.

Prompt 3: Code Review Skill

Technique: Severity-tiered checklist with explicit color coding and structured output format

Code-reviewer returns structured findings:
### 🔴 CRITICAL (Must Fix)
1. **SQL Injection Risk** — src/db/query.ts:42
   - Problem: Unparameterized query with user input
   - Fix: db.query('SELECT * FROM users WHERE id = ?', [userId])

### 🟠 HIGH (Correctness)
2. **Missing Error Handling** — src/auth/service.ts:28
   - Problem: Async function without try/catch

Analysis: Structured output template constrains model output format; severity indicators (CRITICAL/HIGH/MEDIUM) enable downstream filtering.

09

Uniqueness

OpenAgentsControl (OAC) — Uniqueness & Positioning

Differs From Seeds

Closest seed is agent-os — both organize project context as files loaded by agents at runtime. The architectural delta: OAC enforces a hard approval gate before every execution step (bash/write/edit/task), treats ContextScout as a mandatory pre-execution step, and ships a hierarchical 7-subagent pipeline (Claude Code plugin) vs. agent-os's flatter instruction-file approach. Compared to superpowers (Task-tool delegation) and bmad-method (persona pipeline), OAC's distinguishing opinion is that approval gates must be unconditional, not optional — the README explicitly says "Approval Gates: Always required" vs. "Optional (default off)" for Cursor/Copilot. Unlike claude-flow (parallel execution), OAC is deliberately sequential.

Distinctive Opinion

"Editable Agents (Not Baked-In Plugins): Full control over agent behavior. Edit markdown files directly — no compilation, no vendor lock-in."

The MVI principle (only load what's needed) is the second major opinion: token efficiency matters for team adoption.

Positioning

OAC targets teams with established coding patterns who need repeatability over speed. It explicitly positions against:

  • Aider ("No pattern learning, auto-executes")
  • Oh My OpenCode ("Fully autonomous, high token usage")
  • Self as: "Production code, teams" vs. others as "quick prototypes, solo developers"

Observable Failure Modes

  1. Context discovery miss: If ContextScout fails to identify the right context files, code is generated without relevant patterns — silently producing generic code that defeats OAC's purpose.
  2. Approval gate fatigue: Teams requiring approval for every bash and write operation may find the overhead too high for fast iteration.
  3. Context rot: User-authored context files can become stale if not maintained. No automatic learning mechanism updates them from sessions.
  4. OpenCode dependency: OAC's primary path hard-depends on OpenCode CLI, which is less widely deployed than Claude Code.
  5. Claude Code plugin is BETA: The Claude Code integration is explicitly flagged as BETA, meaning the more accessible deployment path carries stability caveats.

Cross-References

  • Explicitly compares against "Oh My OpenCode" in README comparison table
  • Built on OpenCode CLI (opencode.ai)
  • Model-agnostic claim positions it against vendor-locked tools
04

Workflow

OpenAgentsControl (OAC) — Workflow

OpenCode 8-Stage Feature Delivery Workflow

From project-orchestration skill:

Stage Name Artifact
1 Context Handoff — Create Context index in .tmp/
2 Story Mapping User stories document
3 Architecture Analysis Architecture context JSON
4 Contract Management Interface contracts
5 Planning Implementation plan
6 Implementation (Coder) Code changes
7 Test Engineering Tests
8 Code Review Review report

Claude Code Plugin Workflow (6-Stage)

From README:

  1. Context Discovery — ContextScout finds relevant pattern files
  2. Context Loading — Load standards, workflows, patterns
  3. Planning — Agent proposes a plan
  4. Human Approval (gate) — User reviews and approves plan
  5. Execution — Agent executes step-by-step with validation
  6. Validation — TestEngineer + CodeReviewer validate output

Approval Gates

OAC is unusually strict: every bash/write/edit/task invocation requires explicit human approval (Read/list/glob/grep operations are exempt). This is a hard rule in the OpenAgent system prompt:

"Request approval before ANY execution (bash, write, edit, task). Read/list ops don't require approval."

Additional gates:

  • Plan approval before execution
  • Test failure → stop, report, propose fix, request approval, then fix (never auto-fix)
  • Session cleanup confirmation before deleting files

Context Handoff Workflow (Lightweight)

For automation between agents:

bash .opencode/skill/project-orchestration/router.sh create auth-system
bash .opencode/skill/project-orchestration/router.sh get-context auth-system StoryMapper
bash .opencode/skill/project-orchestration/router.sh add-output auth-system ArchitectureAnalyzer contexts.json

Phase-to-Artifact Map

Phase Artifact
Context Discovery .opencode/context/<category>/<file>.md loaded
Story Mapping .tmp/<feature>/stories.md
Architecture .tmp/<feature>/architecture/contexts.json
Implementation Code changes in working directory
Tests Test files
Review Review report (inline or file)
06

Memory Context

OpenAgentsControl (OAC) — Memory & Context

State Storage

OAC's memory model is file-based and project-local:

  • Context files.opencode/context/core/standards/, .opencode/context/core/workflows/, .opencode/context/core/patterns/ — user-created markdown files (<200 lines) encoding coding patterns, standards, and workflows
  • Temporary session state.tmp/<feature>/ — planning session context, agent outputs, architecture contexts stored during a feature workflow
  • Context manifest.context-manifest.json — tracks which context files exist and their categories
  • OAC config.oac.json — project-level OAC configuration

MVI (Minimal Viable Information) Principle

OAC explicitly rejects loading the whole codebase. Instead, ContextScout performs lazy discovery:

  1. Reads .context-manifest.json to know what context exists
  2. Identifies which context files are relevant to the current task
  3. Loads only those files (each <200 lines)
  4. This is claimed to reduce token overhead by ~80% vs full-context approaches

Context Handoff Between Agents

The project-orchestration skill implements two handoff modes:

  • Context Handoff (lightweight): Minimal JSON blobs passed between agents via router.sh commands
  • Session Context (human-readable): Full narrative stored in .tmp/ for debugging

Persistence

  • Context files are project-committed (stored in repo, shared with team)
  • Temporary session state is ephemeral (.tmp/ excluded from git)
  • No cross-session learning or corpus compounding (unlike AgentOps)

Compaction

No explicit context window compaction mechanism. MVI principle prevents context bloat by design — context files are capped at 200 lines.

Cross-Session Handoff

None built-in. Context files persist because they are committed to the repo, but there is no automatic learning or corpus update from sessions.

07

Orchestration

OpenAgentsControl (OAC) — Orchestration

Multi-Agent Pattern

Pattern: Hierarchical (orchestrator + specialists)

The TaskManager agent orchestrates delegation to 7 specialized subagents. The OpenAgent is the universal entry point. For the OpenCode path, 14+ subagents span code, development, planning, system-builder, and utils categories.

Subagent Definition Format

Both paths use persona-md format: markdown files with YAML frontmatter specifying name, description, mode, temperature, and permission settings. No code classes.

Spawn Mechanism

In OpenCode: native OpenCode agent delegation.
In Claude Code: the Claude Code Task tool (task-tool-spawn).

Execution Mode

Sequential with approval gates — OAC is explicitly sequential, not parallel. Each stage waits for human approval before proceeding. The README notes this as a tradeoff: "Execution Speed: Sequential with approval" vs. "Oh My OpenCode: Parallel agents."

Isolation Mechanism

None documented beyond standard agent session isolation. No git worktrees or containers.

Multi-Model

No — the Claude Code plugin sets model: "opusplan" in settings.json. OpenCode path is model-agnostic via provider config but uses a single model per session. No role-to-model routing.

Orchestration Flow

User Request
  ↓
OpenAgent (or TaskManager in Claude Code plugin)
  ↓
ContextScout discovers relevant context files
  ↓
Agent loads context (lazy, MVI)
  ↓
Plan proposed → Human approves (gate)
  ↓
Execute → delegate to specialist subagent
  ↓
Validate (TestEngineer + CodeReviewer)
  ↓
Report to user

Consensus Mechanism

None. Single-agent per delegation path.

Crash Recovery

Not documented. Session state in .tmp/ is ephemeral.

Context Compaction

None built-in. MVI prevents bloat by design (files <200 lines).

08

Ui Cli Surface

OpenAgentsControl (OAC) — UI / CLI Surface

CLI Binary

  • Name: oac
  • Package: @nextsystems/oac
  • Entry point: bin/oac.js
  • Is thin wrapper: Yes — wraps OpenCode CLI with OAC-specific setup and context management
  • Install: npm install -g @nextsystems/oac or via install.sh

OAC CLI subcommands (from packages/cli/):

  • Context management: add context, discover, manage
  • Setup: --core flag for downloading base context files

Local UI

None. OAC runs entirely through terminal interaction with OpenCode CLI or Claude Code chat interface.

IDE Integration

  • OpenCode CLI (primary): terminal-based
  • Claude Code (BETA plugin): Claude Code IDE integration via plugin system

Observability

No dedicated observability surface. Context loading is announced inline ("I'm using the context-scout to find relevant patterns").

Agent Commands (Claude Code plugin)

The 6 slash commands provide contextual operations:

  • /oac:brainstorm — structured brainstorm
  • /oac:debug — debug session
  • /oac:install-context — add context from GitHub/URL/local
  • /oac:oac-cleanup — cleanup session files
  • /oac:oac-help — show skills
  • /oac:oac-status — show current state

Settings

Claude Code plugin settings.json sets model: "opusplan" — uses Claude's extended thinking mode for planning operations.

Integrations

  • GitHub (via OpenCode GitHub integration)
  • Any MCP server via OpenCode's MCP support
  • Context can be sourced from GitHub repos, local files, or URLs via /install-context

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…