|
|
@@ -1,771 +0,0 @@
|
|
|
-<div align="center">
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-# OpenAgents Control (OAC)
|
|
|
-
|
|
|
-### 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
|
|
|
-
|
|
|
-**Prerequisites:** [OpenCode CLI](https://opencode.ai/docs) (free, open-source) • Bash 3.2+ • Git
|
|
|
-
|
|
|
-### Step 1: Install
|
|
|
-
|
|
|
-**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.
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 💡 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
|
|
|
-
|
|
|
-### 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:
|
|
|
-```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.
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-## 🎯 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
|
|
|
-
|
|
|
-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!**
|
|
|
-
|
|
|
-[](https://youtube.com/@DarrenBuildsAI)
|
|
|
-[](https://nextsystems.ai)
|
|
|
-[](https://x.com/DarrenBuildsAI)
|
|
|
-[](https://buymeacoffee.com/darrenhinde)
|
|
|
-
|
|
|
-**📺 Tutorials & Demos** • **💬 Join Waitlist** • **🐦 Latest Updates** • **☕ Support Development**
|
|
|
-
|
|
|
-*Your support helps keep this project free and open-source!*
|
|
|
-
|
|
|
-</div>
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## License
|
|
|
-
|
|
|
-This project is licensed under the MIT License.
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-**Made with ❤️ by developers, for developers. Star the repo if this saves you refactoring time!**
|
darrenhinde