OpenAgents Control (OAC)

Control your AI patterns. Get repeatable results. Zero refactoring.

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

🎯 Pattern Control - Define your patterns once, AI uses them forever
✋ Approval Gates - Review and approve before execution
🔁 Repeatable Results - Same patterns = Same quality code
📝 Editable Agents - Full control over AI behavior
👥 Team-Ready - Everyone uses the same patterns

Multi-language: TypeScript • Python • Go • Rust • Any language
Model Agnostic:* Claude • GPT • Gemini • Local models

🚀 Quick Start • 💻 Show Me Code • 🗺️ Roadmap • 💬 Community

---

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 AOC 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: AOC handles both frontend and backend work. The agents coordinate to build complete features from UI to database.

---

🆚 Quick Comparison

Feature	OpenAgentsControl	Cursor/Copilot	Aider
Learn Your Patterns	✅ Built-in	❌ No	❌ No
Approval Gates	✅ Always	❌ Auto-executes	⚠️ Optional
Token Efficiency	✅ MVI principle	❌ Standard	❌ Standard
Team Standards	✅ Built-in	❌ Per-user	❌ No
Edit Agent Behavior	✅ Markdown files	❌ Baked-in	⚠️ Limited
Model Choice	✅ Any model	❌ Vendor locked	⚠️ OpenAI only

Use AOC 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

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.

---

💡 The Context System: Your Secret Weapon

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

The AOC 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

AOC 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 AOC 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, AOC agents are markdown files. Edit them directly:

nano ~/.opencode/agent/core/opencoder.md
# 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, secu