|
|
@@ -1,12 +1,161 @@
|
|
|
+<div align="center">
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
# OpenAgents Control (OAC)
|
|
|
|
|
|
-Multi-agent orchestration and automation framework for AI-powered development workflows.
|
|
|
+### Control your AI patterns. Get repeatable results.
|
|
|
+
|
|
|
+**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
|
|
|
+
|
|
|
+
|
|
|
+[](https://github.com/darrenhinde/OpenAgentsControl/stargazers)
|
|
|
+[](https://x.com/DarrenBuildsAI)
|
|
|
+[](https://opensource.org/licenses/MIT)
|
|
|
+[](https://github.com/darrenhinde/OpenAgentsControl/commits/main)
|
|
|
+
|
|
|
+[🚀 Quick Start](#-quick-start) • [💻 Show Me Code](#-example-workflow) • [🗺️ Roadmap](https://github.com/darrenhinde/OpenAgentsControl/projects) • [💬 Community](https://nextsystems.ai)
|
|
|
+
|
|
|
+</div>
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+> **Built on [OpenCode](https://opencode.ai)** - 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:**
|
|
|
+```typescript
|
|
|
+// 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 | 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 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 →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
## 🚀 Quick Start
|
|
|
|
|
|
-### Claude Code (BETA - via Plugin Marketplace)
|
|
|
+**Prerequisites:** [OpenCode CLI](https://opencode.ai/docs) (free, open-source) • Bash 3.2+ • Git
|
|
|
+
|
|
|
+### Step 1: Install
|
|
|
|
|
|
-OpenAgents Control is now available as a Claude Code plugin!
|
|
|
+**One command:**
|
|
|
+
|
|
|
+```bash
|
|
|
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer
|
|
|
+```
|
|
|
+
|
|
|
+<sub>The installer will set up OpenCode CLI if you don't have it yet.</sub>
|
|
|
+
|
|
|
+**Or interactive:**
|
|
|
+```bash
|
|
|
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh -o install.sh
|
|
|
+bash install.sh
|
|
|
+```
|
|
|
+
|
|
|
+### Step 2: Start Building
|
|
|
+
|
|
|
+```bash
|
|
|
+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:**
|
|
|
|
|
|
@@ -33,10 +182,11 @@ Add a login endpoint
|
|
|
**Features:**
|
|
|
- ✅ 6-stage workflow with approval gates
|
|
|
- ✅ Context-aware code generation
|
|
|
-- ✅ Parallel task execution
|
|
|
-- ✅ External documentation fetching
|
|
|
-- ✅ Automatic cleanup management
|
|
|
-- ✅ 9 specialized skills + 6 custom subagents
|
|
|
+- ✅ 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](./plugins/claude-code/README.md) - Complete plugin documentation
|
|
|
@@ -47,46 +197,619 @@ Add a login endpoint
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 📚 About OpenAgents Control
|
|
|
+## 💡 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)
|
|
|
+
|
|
|
+```bash
|
|
|
+/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:**
|
|
|
+```bash
|
|
|
+# 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:
|
|
|
+```bash
|
|
|
+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
|
|
|
+
|
|
|
+```bash
|
|
|
+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
|
|
|
+
|
|
|
+```bash
|
|
|
+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
|
|
|
+
|
|
|
+```bash
|
|
|
+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
|
|
|
+
|
|
|
+```bash
|
|
|
+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
|
|
|
|
|
|
-OpenAgents Control is a comprehensive framework for orchestrating multiple AI agents to handle complex development workflows. It provides:
|
|
|
+### Model Configuration (Optional)
|
|
|
|
|
|
-- **Multi-agent orchestration** - Coordinate specialized agents for different tasks
|
|
|
-- **Context-aware execution** - Automatically discover and apply relevant coding standards
|
|
|
-- **Task breakdown** - Decompose complex features into atomic, verifiable subtasks
|
|
|
-- **Quality automation** - Built-in code review, testing, and documentation generation
|
|
|
-- **Flexible architecture** - Works with multiple AI coding tools (Claude Code, OpenCode, Cursor, Windsurf)
|
|
|
+**By default, all agents use your OpenCode default model.** Configure models per agent only if you want different agents to use different models.
|
|
|
|
|
|
-## 🏗️ Architecture
|
|
|
+**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
|
|
|
|
|
|
-OAC uses a **flattened delegation hierarchy** where:
|
|
|
-- **Skills** orchestrate the workflow and guide the main agent
|
|
|
-- **Subagents** execute specialized tasks in isolated contexts
|
|
|
-- **Context files** provide coding standards and patterns
|
|
|
-- **Approval gates** ensure user control over execution
|
|
|
+**How to configure:**
|
|
|
+
|
|
|
+Edit agent files directly:
|
|
|
+```bash
|
|
|
+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:
|
|
|
+```yaml
|
|
|
+---
|
|
|
+description: "Development specialist"
|
|
|
+model: anthropic/claude-sonnet-4-5 # Change this line
|
|
|
+---
|
|
|
+```
|
|
|
+
|
|
|
+Browse available models at [models.dev](https://models.dev/?search=open) or run `opencode models`.
|
|
|
+
|
|
|
+### Update Context as You Go
|
|
|
+
|
|
|
+Your project evolves. Your context should too.
|
|
|
+
|
|
|
+```bash
|
|
|
+/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.
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
-## 📖 Documentation
|
|
|
|
|
|
-- [Agents](./docs/agents/) - Custom agent documentation
|
|
|
-- [Evals](./evals/) - Evaluation framework and tests
|
|
|
-- [Planning](./docs/planning/) - Architecture and design documents
|
|
|
-- [Context System](./docs/context-system/) - Context organization and management
|
|
|
+
|
|
|
+## 🎯 Is This For You?
|
|
|
+
|
|
|
+### ✅ Use AOC 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 AOC 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, AOC 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, AOC 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. 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. But you'll get the most value after adding your patterns (10-15 minutes with `/add-context`).
|
|
|
+
|
|
|
+**Q: What models are supported?**
|
|
|
+A: Any model from any provider (Claude, GPT, Gemini, local models). No vendor lock-in.
|
|
|
+
|
|
|
+### For Teams
|
|
|
+
|
|
|
+**Q: How do I share context with my team?**
|
|
|
+A: Commit `.opencode/context/project/` to your repo. Team members automatically use same patterns.
|
|
|
+
|
|
|
+**Q: How do we ensure everyone follows the same standards?**
|
|
|
+A: Add team patterns to context once. All agents load them automatically. Consistent code across entire team.
|
|
|
+
|
|
|
+**Q: Can different projects have different patterns?**
|
|
|
+A: Yes! Use project-specific context (`.opencode/` in project root) to override global patterns.
|
|
|
+
|
|
|
+### Technical
|
|
|
+
|
|
|
+**Q: How does token efficiency work?**
|
|
|
+A: MVI principle: Only load what's needed, when it's needed. Context files <200 lines (scannable in 30s). ContextScout discovers relevant patterns. Lazy loading prevents context bloat. 80% of tasks use isolation context (minimal overhead).
|
|
|
+
|
|
|
+**Q: What's ContextScout?**
|
|
|
+A: Smart pattern discovery agent. Finds relevant context files before code generation. Ranks by priority. Prevents wasted work.
|
|
|
+
|
|
|
+**Q: Can I edit agent behavior?**
|
|
|
+A: Yes! Agents are markdown files. Edit them directly: `nano .opencode/agent/core/opencoder.md` (local) or `nano ~/.config/opencode/agent/core/opencoder.md` (global)
|
|
|
+
|
|
|
+**Q: How do approval gates work?**
|
|
|
+A: Agents ALWAYS request approval before execution (write/edit/bash). You review plans before implementation. No surprises.
|
|
|
+
|
|
|
+**Q: How do I update my context?**
|
|
|
+A: Run `/add-context --update` anytime your patterns change. Agents automatically use updated patterns.
|
|
|
+
|
|
|
+### Comparison
|
|
|
+
|
|
|
+**Q: How is this different from Cursor/Copilot?**
|
|
|
+A: AOC has editable agents (not baked-in), approval gates (not auto-execute), context system (YOUR patterns), and MVI token efficiency.
|
|
|
+
|
|
|
+**Q: How is this different from Aider?**
|
|
|
+A: AOC has team patterns, context system, approval workflow, and smart pattern discovery. Aider is file-based only.
|
|
|
+
|
|
|
+**Q: How does this compare to Oh My OpenCode?**
|
|
|
+A: Both are built on OpenCode. AOC focuses on **control & repeatability** (approval gates, pattern control, team standards). Oh My OpenCode focuses on **autonomy & speed** (parallel agents, auto-execution). [Read detailed comparison →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
|
|
|
+
|
|
|
+**Q: When should I NOT use AOC?**
|
|
|
+A: If you want fully autonomous execution without approval gates, or if you don't have established coding patterns yet.
|
|
|
+
|
|
|
+### Setup
|
|
|
+
|
|
|
+**Q: What bash version do I need?**
|
|
|
+A: Bash 3.2+ (macOS default works). Run `bash scripts/tests/test-compatibility.sh` to check.
|
|
|
+
|
|
|
+**Q: Do I need to install plugins/tools?**
|
|
|
+A: No, they're optional. Only install if you want Telegram notifications or Gemini AI features.
|
|
|
+
|
|
|
+**Q: Where should I install - globally or per-project?**
|
|
|
+A: Local (`.opencode/` in your project) is recommended — patterns are committed to git and shared with your team. Global (`~/.config/opencode/`) is good for personal defaults across all projects. The installer asks you to choose. See [OpenCode Config Docs](https://opencode.ai/docs/config/) for how configs merge.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🗺️ Roadmap & What's Coming
|
|
|
+
|
|
|
+**This is only the beginning!** We're actively developing new features and improvements every day.
|
|
|
+
|
|
|
+### 🚀 See What's Coming Next
|
|
|
+
|
|
|
+Check out our [**Project Board**](https://github.com/darrenhinde/OpenAgentsControl/projects) to see:
|
|
|
+- 🔨 **In Progress** - Features being built right now
|
|
|
+- 📋 **Planned** - What's coming soon
|
|
|
+- 💡 **Ideas** - Future enhancements under consideration
|
|
|
+- ✅ **Recently Shipped** - Latest improvements
|
|
|
+
|
|
|
+### 🎯 Current Focus Areas
|
|
|
+
|
|
|
+- **Plugin System** - npm-based plugin architecture for easy distribution
|
|
|
+- **Performance Improvements** - Faster agent execution and context loading
|
|
|
+- **Enhanced Context Discovery** - Smarter pattern recognition
|
|
|
+- **Multi-language Support** - Better Python, Go, Rust support
|
|
|
+- **Team Collaboration** - Shared context and team workflows
|
|
|
+- **Documentation** - More examples, tutorials, and guides
|
|
|
+
|
|
|
+### 💬 Have Ideas?
|
|
|
+
|
|
|
+We'd love to hear from you!
|
|
|
+- 💡 [**Submit Feature Requests**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=enhancement)
|
|
|
+- 🐛 [**Report Bugs**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=bug)
|
|
|
+- 💬 [**Join Discussions**](https://github.com/darrenhinde/OpenAgentsControl/discussions)
|
|
|
+
|
|
|
+**Star the repo** ⭐ to stay updated with new releases!
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
## 🤝 Contributing
|
|
|
|
|
|
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
|
|
|
+We welcome contributions!
|
|
|
+
|
|
|
+1. Follow the established naming conventions and coding standards
|
|
|
+2. Write comprehensive tests for new features
|
|
|
+3. Update documentation for any changes
|
|
|
+4. Ensure security best practices are followed
|
|
|
+
|
|
|
+See: [Contributing Guide](docs/contributing/CONTRIBUTING.md) • [Code of Conduct](docs/contributing/CODE_OF_CONDUCT.md)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 💬 Community & Support
|
|
|
+
|
|
|
+<div align="center">
|
|
|
+
|
|
|
+**Join the community and stay updated with the latest AI development workflows!**
|
|
|
|
|
|
-## 📄 License
|
|
|
+[](https://youtube.com/@DarrenBuildsAI)
|
|
|
+[](https://nextsystems.ai)
|
|
|
+[](https://x.com/DarrenBuildsAI)
|
|
|
+[](https://buymeacoffee.com/darrenhinde)
|
|
|
|
|
|
-MIT License - see [LICENSE](./LICENSE) for details.
|
|
|
+**📺 Tutorials & Demos** • **💬 Join Waitlist** • **🐦 Latest Updates** • **☕ Support Development**
|
|
|
+
|
|
|
+*Your support helps keep this project free and open-source!*
|
|
|
+
|
|
|
+</div>
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
-## 🆘 Support
|
|
|
+## License
|
|
|
|
|
|
-- **Issues**: [GitHub Issues](https://github.com/darrenhinde/OpenAgentsControl/issues)
|
|
|
-- **Discussions**: [GitHub Discussions](https://github.com/darrenhinde/OpenAgentsControl/discussions)
|
|
|
+This project is licensed under the MIT License.
|
|
|
|
|
|
---
|
|
|
|
|
|
-**Version**: 1.0.0-beta
|
|
|
-**Status**: Active Development
|
|
|
-**Last Updated**: 2026-02-16
|
|
|
+**Made with ❤️ by developers, for developers. Star the repo if this saves you refactoring time!**
|
darrenhinde