darrenhinde/OpenAgentsControl

---

Built on OpenCode - An open-source AI coding framework. OAC extends OpenCode with specialized agents, context management, and team workflows.

---

The Problem

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.

Example:

// What AI gives you (generic)
export async function POST(request: Request) {
  const data = await request.json();
  return Response.json({ success: true });
}

// What you actually need (your patterns)
export async function POST(request: Request) {
  const body = await request.json();
  const validated = UserSchema.parse(body);  // Your Zod validation
  const result = await db.users.create(validated);  // Your Drizzle ORM
  return Response.json(result, { status: 201 });  // Your response format
}

The Solution

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.

The result: Production-ready code that ships without heavy rework.

What Makes OAC Different

🎯 Context-Aware (Your Secret Weapon) Agents load YOUR patterns before generating code. Code matches your project from the start. No refactoring needed.

📝 Editable Agents (Not Baked-In Plugins) Full control over agent behavior. Edit markdown files directly—no compilation, no vendor lock-in. Change workflows, add constraints, customize for your team.

✋ Approval Gates (Human-Guided AI) Agents ALWAYS request approval before execution. Propose → Approve → Execute. You stay in control. No "oh no, what did the AI just do?" moments.

⚡ Token Efficient (MVI Principle) Minimal Viable Information design. Only load what's needed, when it's needed. Context files <200 lines, lazy loading, faster responses.

👥 Team-Ready (Repeatable Patterns) Store YOUR coding patterns once. Entire team uses same standards. Commit context to repo. New developers inherit team patterns automatically.

🔄 Model Agnostic Use any AI model (Claude, GPT, Gemini, local). No vendor lock-in.

Full-stack development: OAC handles both frontend and backend work. The agents coordinate to build complete features from UI to database.

---

🆚 Quick Comparison

| Feature | OpenAgentsControl | Cursor/Copilot | Aider | Oh My OpenCode | |---------|-------------------|----------------|-------|----------------| | Learn Your Patterns | ✅ Built-in context system | ❌ No pattern learning | ❌ No pattern learning | ⚠️ Manual setup | | Approval Gates | ✅ Always required | ⚠️ Optional (default off) | ❌ Auto-executes | ❌ Fully autonomous | | Token Efficiency | ✅ MVI principle (80% reduction) | ❌ Full context loaded | ❌ Full context loaded | ❌ High token usage | | Team Standards | ✅ Shared context files | ❌ Per-user settings | ❌ No team support | ⚠️ Manual config per user | | Edit Agent Behavior | ✅ Markdown files you edit | ❌ Proprietary/baked-in | ⚠️ Limited prompts | ✅ Config files | | Model Choice | ✅ Any model, any provider | ⚠️ Limited options | ⚠️ OpenAI/Claude only | ✅ Multiple models | | Execution Speed | ⚠️ Sequential with approval | Fast | Fast | ✅ Parallel agents | | Error Recovery | ✅ Human-guided validation | ⚠️ Auto-retry (can loop) | ⚠️ Auto-retry | ✅ Self-correcting | | Best For | Production code, teams | Quick prototypes | Solo developers | Power users, complex projects |

Use OAC when:

• ✅ You have established coding patterns
• ✅ You want code that ships without refactoring
• ✅ You need approval gates for quality control
• ✅ You care about token efficiency and costs

Use others when:

• Cursor/Copilot: Quick prototypes, don't care about patterns
• Aider: Simple file edits, no team coordination
• Oh My OpenCode: Need autonomous execution with parallel agents (speed over control)

Full comparison: Read detailed analysis →

---

🚀 Quick Start

Prerequisites: OpenCode CLI (free, open-source) • Bash 3.2+ • Git

Step 1: Install

One command:

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

_{The installer will set up OpenCode CLI if you don't have it yet.}

Or interactive:

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh -o install.sh
bash install.sh

Keep Updated

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/update.sh | bash

Use --install-dir PATH if you installed to a custom location (e.g. ~/.config/opencode).

Step 2: Start Building

opencode --agent OpenAgent
"Create a user authentication system"

Step 3: Approve & Ship

What happens: 1. Agent analyzes your request 2. Proposes a plan (you approve) 3. Executes step-by-step with validation 4. Delegates to specialists when needed 5. Ships production-ready code

That's it. Works immediately with your default model. No configuration required.

---

Alternative: Claude Code Plugin (BETA)

Prefer Claude Code? OpenAgents Control is also available as a Claude Code plugin!

Installation:

1. Register the marketplace:

/plugin marketplace add darrenhinde/OpenAgentsControl

2. Install the plugin:

/plugin install oac

3. Download context files:

/oac:setup --core

4. Start building:

Add a login endpoint

Features:

• ✅ 6-stage workflow with approval gates
• ✅ Context-aware code generation
• ✅ 7 specialized subagents (task-manager, context-scout, context-manager, coder-agent, test-engineer, code-reviewer, external-scout)
• ✅ 9 workflow skills + 6 user commands
• ✅ Flexible context discovery (.oac config, .claude/context, context, .opencode/context)
• ✅ Add context from GitHub, worktrees, local files, or URLs
• ✅ Easy feature planning with /oac:plan

Documentation:

• Plugin README - Complete plugin documentation
• First-Time Setup - Step-by-step guide
• Quick Start - Quick reference

Status: BETA - Actively tested and ready for early adopters

---

💡 The Context System: Your Secret Weapon

The problem with AI code: It doesn't match your patterns. You spend hours refactoring.

The OAC solution: Teach your patterns once. Agents load them automatically. Code matches from the start.

How It Works

Your Request
    ↓
ContextScout discovers relevant patterns
    ↓
Agent loads YOUR standards
    ↓
Code generated using YOUR patterns
    ↓
Ships without refactoring ✅

Add Your Patterns (10-15 Minutes)

/add-context

Answer 6 simple questions: 1. What's your tech stack? (Next.js + TypeScript + PostgreSQL + Tailwind) 2. Show an API endpoint example (paste your code) 3. Show a component example (paste your code) 4. What naming conventions? (kebab-case, PascalCase, camelCase) 5. Any code standards? (TypeScript strict, Zod validation, etc.) 6. Any security requirements? (validate input, parameterized queries, etc.)

Result: Agents now generate code matching your exact patterns. No refactoring needed.

The MVI Advantage: Token Efficiency

MVI (Minimal Viable Information) = Only load what's needed, when it's needed.

Traditional approach:

• Loads entire codebase context
• Large token overhead per request
• Slow responses, high costs

OAC approach:

• Loads only relevant patterns
• Context files <200 lines (quick to load)
• Lazy loading (agents load what they need)
• 80% of tasks use isolation context (minimal overhead)

Real benefits:

• Efficiency: Lower token usage vs loading entire codebase
• Speed: Faster responses with smaller context
• Quality: Code matches your patterns (no refactoring)

For Teams: Repeatable Patterns

The team problem: Every developer writes code differently. Inconsistent patterns. Hard to maintain.

The OAC solution: Store team patterns in .opencode/context/project/. Commit to repo. Everyone uses same standards.

Example workflow:

# Team lead adds patterns once
/add-context
Answers questions with team standards

Commit to repo
git add .opencode/context/
git commit -m "Add team coding standards"
git push
All team members now use same patterns automatically
New developers inherit standards on day 1

Result: Consistent code across entire team. No style debates. No refactoring PRs.

---

📖 How It Works

The Core Idea

Most AI tools: Generic code → You refactor OpenAgentsControl: Your patterns → AI generates matching code

The Workflow

1. Add Your Context (one time)
   ↓
2. ContextScout discovers relevant patterns
   ↓
3. Agent loads YOUR standards
   ↓
4. Agent proposes plan (using your patterns)
   ↓
5. You approve
   ↓
6. Agent implements (matches your project)
   ↓
7. Code ships (no refactoring needed)

Key Benefits

🎯 Context-Aware ContextScout discovers relevant patterns. Agents load YOUR standards before generating code. Code matches your project from the start.

🔁 Repeatable Same patterns → Same results. Configure once, use forever. Perfect for teams.

⚡ Token Efficient (80% Reduction) MVI principle: Only load what's needed. 8,000 tokens → 750 tokens. Massive cost savings.

✋ Human-Guided Agents propose plans, you approve before execution. Quality gates prevent mistakes. No auto-execution surprises.

📝 Transparent & Editable Agents are markdown files you can edit. Change workflows, add constraints, customize behavior. No vendor lock-in.

What Makes This Special

1. ContextScout - Smart Pattern Discovery Before generating code, ContextScout discovers relevant patterns from your context files. Ranks by priority (Critical → High → Medium). Prevents wasted work.

2. Editable Agents - Full Control Unlike Cursor/Copilot where behavior is baked into plugins, OAC agents are markdown files. Edit them directly:

nano .opencode/agent/core/opencoder.md  # local project install
Or: nano ~/.config/opencode/agent/core/opencoder.md  # global install
Add project rules, change workflows, customize behavior

3. ExternalScout - Live Documentation 🆕 Working with external libraries? ExternalScout fetches current documentation:

• Gets live docs from official sources (npm, GitHub, docs sites)
• No outdated training data - always current
• Automatically triggered when agents detect external dependencies
• Supports frameworks, APIs, libraries, and more

4. Approval Gates - No Surprises Agents ALWAYS request approval before:

• Writing/editing files
• Running bash commands
• Delegating to subagents
• Making any changes

You stay in control. Review plans before execution.

5. MVI Principle - Token Efficiency Files designed for quick loading:

• Concepts: <100 lines
• Guides: <150 lines
• Examples: <80 lines

Result: Lower token usage vs loading entire codebase.

6. Team Patterns - Repeatable Results Store patterns in .opencode/context/project/. Commit to repo. Entire team uses same standards. New developers inherit patterns automatically.

---

🎯 Which Agent Should I Use?

OpenAgent (Start Here)

Best for: Learning the system, general tasks, quick implementations

opencode --agent OpenAgent
"Create a user authentication system"            # Building features
"How do I implement authentication in Next.js?"  # Questions
"Create a README for this project"               # Documentation
"Explain the architecture of this codebase"      # Analysis

What it does:

• Loads your patterns via ContextScout
• Proposes plan (you approve)
• Executes with validation
• Delegates to specialists when needed

Perfect for: First-time users, simple features, learning the workflow

OpenCoder (Production Development)

Best for: Complex features, multi-file refactoring, production systems

opencode --agent OpenCoder
"Create a user authentication system"                 # Full-stack features
"Refactor this codebase to use dependency injection"  # Multi-file refactoring
"Add real-time notifications with WebSockets"         # Complex implementations

What it does:

• Discover: ContextScout finds relevant patterns
• Propose: Detailed implementation plan
• Approve: You review and approve
• Execute: Incremental implementation with validation
• Validate: Tests, type checking, code review
• Ship: Production-ready code

Perfect for: Production code, complex features, team development

SystemBuilder (Custom AI Systems)

Best for: Building complete custom AI systems tailored to your domain

opencode --agent SystemBuilder
"Create a customer support AI system"

Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.

Perfect for: Creating domain-specific AI systems

---

🛠️ What's Included

🤖 Main Agents

• OpenAgent - General tasks, questions, learning (start here)
• OpenCoder - Production development, complex features
• SystemBuilder - Generate custom AI systems

🔧 Specialized Subagents (Auto-delegated)

• ContextScout - Smart pattern discovery (your secret weapon)
• TaskManager - Breaks complex features into atomic subtasks
• CoderAgent - Focused code implementations
• TestEngineer - Test authoring and TDD
• CodeReviewer - Code review and security analysis
• BuildAgent - Type checking and build validation
• DocWriter - Documentation generation
• ExternalScout - Fetches live docs for external libraries (no outdated training data) NEW!
• Plus category specialists: frontend, devops, copywriter, technical-writer, data-analyst

⚡ Productivity Commands

• /add-context - Interactive wizard to add your patterns
• /commit - Smart git commits with conventional format
• /test - Testing workflows
• /optimize - Code optimization
• /context - Context management
• And 7+ more productivity commands

📚 Context System (MVI Principle)

Your coding standards automatically loaded by agents:

• Code quality - Your patterns, security, standards
• UI/design - Design system, component patterns
• Task management - Workflow definitions
• External libraries - Integration guides (18+ libraries supported)
• Project-specific - Your team's patterns

Key features:

• 80% token reduction via MVI
• Smart discovery via ContextScout
• Lazy loading (only what's needed)
• Team-ready (commit to repo)
• Version controlled (track changes)

How Context Resolution Works

ContextScout discovers context files using a local-first approach:

1. Check local: .opencode/context/core/navigation.md
   ↓ Found? → Use local for everything. Done.
   ↓ Not found?
2. Check global: ~/.config/opencode/context/core/navigation.md
   ↓ Found? → Use global for core/ files only.
   ↓ Not found? → Proceed without core context.

Key rules:

• Local always wins — if you installed locally, global is never checked
• Global fallback is only for core/ (standards, workflows, guides) — universal files that are the same across projects
• Project intelligence is always local — your tech stack, patterns, and naming conventions live in .opencode/context/project-intelligence/ and are never loaded from global
• One-time check — ContextScout resolves the core location once at startup (max 2 glob checks), not per-file

Common setups:

| Setup | Core files from | Project intelligence from | |-------|----------------|--------------------------| | Local install (bash install.sh developer) | .opencode/context/core/ | .opencode/context/project-intelligence/ | | Global install + /add-context | ~/.config/opencode/context/core/ | .opencode/context/project-intelligence/ | | Both local and global | .opencode/context/core/ (local wins) | .opencode/context/project-intelligence/ |

---

💻 Example Workflow

opencode --agent OpenCoder
"Create a user dashboard with authentication and profile settings"

What happens:

1. Discover (~1-2 min) - ContextScout finds relevant patterns

• Your tech stack (Next.js + TypeScript + PostgreSQL)
• Your API pattern (Zod validation, error handling)
• Your component pattern (functional, TypeScript, Tailwind)
• Your naming conventions (kebab-case files, PascalCase components)

2. Propose (~2-3 min) - Agent creates detailed implementation plan

## Proposed Implementation

Components:
user-dashboard.tsx (main page)
profile-settings.tsx (settings component)
auth-guard.tsx (authentication wrapper)

API Endpoints:
/api/user/profile (GET, POST)
/api/auth/session (GET)

Database:
users table (Drizzle schema)
sessions table (Drizzle schema)

All code will follow YOUR patterns from context.

Approve? [y/n]

3. Approve - You review and approve the plan (human-guided)

4. Execute (~10-15 min) - Incremental implementation with validation

• Implements one component at a time
• Uses YOUR patterns for every file
• Validates after each step (type check, lint)
• This is the longest step - generating quality code takes time

5. Validate (~2-3 min) - Tests, type checking, code review

• Delegates to TestEngineer for tests
• Delegates to CodeReviewer for security check
• Ensures production quality

6. Ship - Production-ready code

• Code matches your project exactly
• No refactoring needed
• Ready to commit and deploy

Total time: ~15-25 minutes for a complete feature (guided, with approval gates)

💡 Pro Tips

After finishing a feature:

• Run /add-context --update to add new patterns you discovered
• Update your context with new libraries, conventions, or standards
• Keep your patterns fresh as your project evolves

Working with external libraries?

• ExternalScout automatically fetches current documentation
• No more outdated training data - gets live docs from official sources
• Works with npm packages, APIs, frameworks, and more

---

⚙️ Advanced Configuration

Model Configuration (Optional)

By default, all agents use your OpenCode default model. Configure models per agent only if you want different agents to use different models.

When to configure:

• You want faster agents to use cheaper models (e.g., Haiku/Flash)
• You want complex agents to use smarter models (e.g., Opus/GPT-5)
• You want to test different models for different tasks

How to configure:

Edit agent files directly:

nano .opencode/agent/core/opencoder.md  # local project install
Or: nano ~/.config/opencode/agent/core/opencoder.md  # global install

Change the model in the frontmatter:

---
description: "Development specialist"
model: anthropic/claude-sonnet-4-5  # Change this line
---

Browse available models at models.dev or run opencode models.

Update Context as You Go

Your project evolves. Your context should too.

/add-context --update

What gets updated:

• Tech stack, patterns, standards
• Version incremented (1.0 → 1.1)
• Updated date refreshed

Example updates:

• Add new library (Stripe, Twilio, etc.)
• Change patterns (new API format, component structure)
• Migrate tech stack (Prisma → Drizzle)
• Update security requirements

Agents automatically use updated patterns.

---

🎯 Is This For You?

✅ Use OAC if you:

• Build production code that ships without heavy rework
• Work in a team with established coding standards
• Want control over agent behavior (not black-box plugins)
• Care about token efficiency and cost savings
• Need approval gates for quality assurance
• Want repeatable, consistent results
• Use multiple AI models (no vendor lock-in)

⚠️ Skip OAC if you:

• Want fully autonomous execution without approval gates
• Prefer "just do it" mode over human-guided workflows
• Don't have established coding patterns yet
• Need multi-agent parallelization (use Oh My OpenCode instead)
• Want plug-and-play with zero configuration

🤔 Not Sure?

Try this test: 1. Ask your current AI tool to generate an API endpoint 2. Count how many minutes you spend refactoring it to match your patterns 3. If you're spending time on refactoring, OAC will save you that time

Or ask yourself:

• Do you have coding standards your team follows?
• Do you spend time refactoring AI-generated code?
• Do you want AI to follow YOUR patterns, not generic ones?

If you answered "yes" to any of these, OAC is for you.

---

🚀 Advanced Features

Frontend Design Workflow

The OpenFrontendSpecialist follows a structured 4-stage design workflow: 1. Layout - ASCII wireframe, responsive structure planning 2. Theme - Design system selection, OKLCH colors, typography 3. Animation - Micro-interactions, timing, accessibility 4. Implementation - Single HTML file, semantic markup

Task Management & Breakdown

The TaskManager breaks complex features into atomic, verifiable subtasks with smart agent suggestions and parallel execution support.

System Builder

Build complete custom AI systems tailored to your domain in minutes. Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.

---

❓ FAQ

Getting Started

Q: Does this work on Windows? A: Yes! Use Git Bash (recommended) or WSL.

Q: What languages are supported? A: Agents are language-agnostic and adapt based on your project files. Primarily tested with TypeScript/Node.js. C# / .NET is now supported with dedicated context files. Python, Go, Rust, and other languages are supported but less battle-tested. The context system works with any language.

Q: Do I need to add context? A: No, but it's highly recommended. Without context, agents write generic code. With context, they write YOUR code.

Q: Can I use this without customization? A: Yes, it works out of the box. B