docs: adapt README to the Architect fork; add fork installer
- README rewritten around the Controlling Architect concept (spec -> build -> report -> verify), the architect/builder agency and the channels; upstream README preserved as README.upstream.md - install.sh: fork-native installer adapted from Darren Hinde's OAC installer. Syncs the complete .opencode payload (no registry), supports local/global/custom, skip/overwrite/backup, --source/--token/--branch/--yes/--force/--dry-run
This commit is contained in:
parent
0764127e46
commit
5e84cf7af0
3 changed files with 1386 additions and 751 deletions
912
README.md
912
README.md
|
|
@ -1,823 +1,233 @@
|
|||
<div align="center">
|
||||
|
||||
|
||||
# OpenAgents Control — Architect Fork
|
||||
|
||||
# OpenAgents Control (OAC)
|
||||
### Spec it · Build it · Verify it · Repeat
|
||||
|
||||
### Control your AI patterns. Get repeatable results.
|
||||
A fork of **[OpenAgents Control (OAC)](https://github.com/darrenhinde/OpenAgentsControl)** by [Darren Hinde](https://github.com/darrenhinde)
|
||||
that puts a **Controlling Architect** at the top — an agent that plans, specifies and verifies, and directs the build agents.
|
||||
|
||||
**AI agents that learn YOUR coding patterns and generate matching code every time.**
|
||||
**Repository:** `git.lohmar.co.uk/cclohmar/NewOpenAgents`
|
||||
|
||||
🎯 **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)
|
||||
*Multi-language:* TypeScript · Python · Go · Rust · any language • *Model-agnostic:* Claude · GPT · Gemini · local models
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
> **Built on [OpenCode](https://opencode.ai)** - An open-source AI coding framework. OAC extends OpenCode with specialized agents, context management, and team workflows.
|
||||
> **Built on [OpenCode](https://opencode.ai).** OAC extends OpenCode with specialized agents, a context system and team workflows. **This fork** — maintained by Claus Lohmar — changes the *concept* at the top: instead of a single agent that both plans and builds, it installs a **Controlling Architect** that only specs and verifies, and one or more **build agents** that only build.
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
## The idea
|
||||
|
||||
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.
|
||||
Upstream OAC gives you a capable **OpenAgent** that plans, implements and coordinates, with approval gates between each step. This fork splits that role in two *deliberately*:
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// What AI gives you (generic)
|
||||
export async function POST(request: Request) {
|
||||
const data = await request.json();
|
||||
return Response.json({ success: true });
|
||||
}
|
||||
| | Role | Does | Never does |
|
||||
|---|------|------|-----------|
|
||||
| **🧠 The Architect** | *why* + *how* | reads the code, writes the specs, verifies the work, rules on design/scope/security | write the implementation |
|
||||
| **🔨 The Builders** | *do* | implement one spec at a time, run the tests, commit and report | decide what should be built |
|
||||
|
||||
// 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 Architect is the **single point of contact**. The builders never ask the human directly — they ask the Architect, who resolves everything that already has an answer and escalates only the decisions that are genuinely the human's.
|
||||
|
||||
The result is a loop with **one source of truth: the repository**. Chat is not the record — the repo is.
|
||||
|
||||
```
|
||||
🧠 Architect writes an instruction (I-nnn)
|
||||
│
|
||||
▼
|
||||
🔨 Builder implements a slice ──► commit + push
|
||||
│
|
||||
▼
|
||||
🔨 Builder reports (W-nnn)
|
||||
│
|
||||
▼
|
||||
🧠 Architect verifies independently ──► the next instruction (I-nnn)
|
||||
```
|
||||
|
||||
## The Solution
|
||||
## What this fork changes vs. upstream
|
||||
|
||||
**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.
|
||||
| | Upstream OAC | This fork |
|
||||
|---|---|---|
|
||||
| **Top-level agent** | `OpenAgent` (plans *and* builds) | **`OpenArchitect`** (specs, verifies, controls) |
|
||||
| **Build agents** | `OpenAgent` / `OpenCoder` | **build agents**, directed by the Architect, one slice at a time |
|
||||
| **Workflow** | Plan → approve → execute | **Spec → build → report → verify → next spec** |
|
||||
| **Source of truth** | the chat + approval gates | **the repository** — instructions, worklog, channels |
|
||||
| **Independence** | the agent self-checks | the **Architect** re-runs the evidence itself |
|
||||
| **Roles, not forks** | one agent fits all | one generic builder; its role (e.g. a second line) is named **in the task prompt** |
|
||||
|
||||
**The result:** Production-ready code that ships without heavy rework.
|
||||
The **context system, subagents, commands and skills** are inherited from upstream and work exactly as documented below — the fork adds the *controlling* tier on top.
|
||||
|
||||
### What Makes OAC Different
|
||||
## The two tiers
|
||||
|
||||
**🎯 Context-Aware (Your Secret Weapon)**
|
||||
Agents load YOUR patterns before generating code. Code matches your project from the start. No refactoring needed.
|
||||
### 🧠 Tier 1 — The Controlling Architect (`OpenArchitect`)
|
||||
|
||||
**📝 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.
|
||||
A `primary` agent. It **reads the code, the docs and the live data** and then:
|
||||
|
||||
**✋ 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.
|
||||
1. **Specifies the interfaces, not the outcome** — the routes, params, file names, table names. If the spec doesn't name it, the builder will invent it.
|
||||
2. **Writes one instruction at a time** into `docs/logs/INSTRUCTIONS.md`, addressed to a named builder.
|
||||
3. **Verifies every batch independently** — re-runs the build, the tests and the claim's own evidence. "It exists in the code" is never "it works".
|
||||
4. **Rules on the flags** the builders raise (security, schema, scope, contradictions) and records the ruling.
|
||||
5. **Is the human's single point of contact** — it escalates only the unavoidable gates.
|
||||
|
||||
**⚡ 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.
|
||||
> **The Architect's full rulebook is `ARCHITECTS.md`.** The GMS reference project keeps it at the repo root, next to its `AGENTS.md`; the agent definition itself is `agent/OpenArchitect.md`.
|
||||
|
||||
**👥 Team-Ready (Repeatable Patterns)**
|
||||
Store YOUR coding patterns once. Entire team uses same standards. Commit context to repo. New developers inherit team patterns automatically.
|
||||
### 🔨 Tier 2 — The Builders (`OpenAgent`)
|
||||
|
||||
**🔄 Model Agnostic**
|
||||
Use any AI model (Claude, GPT, Gemini, local). No vendor lock-in.
|
||||
The builders implement. They are **one generic agent** — the same persona, given a role for the run by the Architect's task prompt. On the reference project the main line is **Codi** and the second line is **Sam**.
|
||||
|
||||
**Full-stack development:** OAC handles both frontend and backend work. The agents coordinate to build complete features from UI to database.
|
||||
They read, in order: their persona → the history and current state (`docs/logs/WORKLOG.md`, `INSTRUCTIONS.md`, the hand-off) → the task prompt. Then they build, run the definition-of-done themselves, **commit and push before reporting**, and write exactly one `W-nnn` entry in the worklog.
|
||||
|
||||
---
|
||||
## The agency — how the two tiers talk
|
||||
|
||||
## 🆚 Quick Comparison
|
||||
Every hand-over is a file in the repo, not a message in a chat.
|
||||
|
||||
| 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 |
|
||||
| File | Writer | Purpose |
|
||||
|------|--------|---------|
|
||||
| `docs/logs/INSTRUCTIONS.md` | **Architect** | the **active task** (`I-nnn`) — only the newest is live |
|
||||
| `docs/logs/WORKLOG.md` | **Builders** | one report per instruction (`W-nnn`) |
|
||||
| `docs/logs/CHANNEL-*.md` | both | append-only discussion between the Architect and one builder |
|
||||
| `docs/logs/FOR-CLAUS.md` | **Architect** | the escalation queue — the human's decisions only |
|
||||
|
||||
**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
|
||||
The Architect **reads the repo, never the chat**, to verify a batch. That is why a builder must commit and push *before* it reports.
|
||||
|
||||
**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)
|
||||
## The agents
|
||||
|
||||
> **Full comparison:** [Read detailed analysis →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
|
||||
### Primary agents
|
||||
| Agent | File | Role |
|
||||
|-------|------|------|
|
||||
| **OpenArchitect** | `agent/OpenArchitect.md` | the Controlling Architect — specs, verifies, rules |
|
||||
| **OpenAgent** | `agent/core/openagent.md` | universal builder / coordinator |
|
||||
| **OpenCoder** | `agent/core/opencoder.md` | complex coding & multi-file refactoring |
|
||||
|
||||
---
|
||||
### Subagents (auto-delegated)
|
||||
| Subagent | Purpose |
|
||||
|----------|---------|
|
||||
| `openagent` | the **builder** persona — implements a slice per the Architect's spec |
|
||||
| `ContextScout` | discovers the project's own context files before work begins |
|
||||
| `ExternalScout` | fetches current, version-specific docs for external libraries |
|
||||
| `TaskManager` | breaks a feature into atomic, verifiable subtasks |
|
||||
| `CoderAgent` | executes coding subtasks in sequence |
|
||||
| `BuildAgent` | type-check and build validation |
|
||||
| `CodeReviewer` | code review, security and quality assurance |
|
||||
| `TestEngineer` | test authoring / TDD |
|
||||
| `DocWriter` | documentation authoring |
|
||||
| `ContextOrganizer` | organises and generates context files |
|
||||
| `OpenDevopsSpecialist` | CI/CD, infrastructure-as-code, deployment |
|
||||
| `OpenFrontendSpecialist` | design systems, themes, animation |
|
||||
|
||||
## 🚀 Quick Start
|
||||
## What's included
|
||||
|
||||
**Prerequisites:** [OpenCode CLI](https://opencode.ai/docs) (free, open-source) • Bash 3.2+ • Git
|
||||
```
|
||||
agent/ the agents & subagents (OpenArchitect, OpenAgent, OpenCoder, …)
|
||||
command/ slash commands (/commit, /test, /context, /optimize, …)
|
||||
context/ the context system — standards, workflows, UI, project templates
|
||||
skills/ loadable skills (Context7 docs lookup, task management)
|
||||
tool/ custom OpenCode tools (env loader)
|
||||
env.example template for the optional .env (Telegram/Gemini integrations)
|
||||
```
|
||||
|
||||
### Step 1: Install
|
||||
## Install
|
||||
|
||||
**One command:**
|
||||
This repository is **private**, so the installer needs access to it. The simplest path is to clone it once and run the installer from the clone — your existing git credentials are used, no token to paste.
|
||||
|
||||
### Recommended — clone, then install
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer
|
||||
git clone https://git.lohmar.co.uk/cclohmar/NewOpenAgents.git ~/.oac
|
||||
|
||||
~/.oac/install.sh # interactive: choose Local / Global / Custom
|
||||
~/.oac/install.sh --global # → ~/.config/opencode (every project)
|
||||
~/.oac/install.sh --local # → ./.opencode (this project)
|
||||
```
|
||||
|
||||
<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
|
||||
```
|
||||
|
||||
### Keep Updated
|
||||
### Bootstrap without a clone (private → pass a token)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/update.sh | bash
|
||||
export OAC_TOKEN=<a Forgejo token with repo:read>
|
||||
curl -fsSL "https://git.lohmar.co.uk/cclohmar/NewOpenAgents/raw/branch/main/install.sh?token=$OAC_TOKEN" \
|
||||
| bash -s -- --global --yes --token "$OAC_TOKEN"
|
||||
```
|
||||
|
||||
> Use `--install-dir PATH` if you installed to a custom location (e.g. `~/.config/opencode`).
|
||||
The installer offers **Local** (`.opencode/` in the current project), **Global** (`~/.config/opencode`) or a **Custom** path, and — when files already exist — lets you **skip**, **overwrite** or **back up & overwrite**. A `--source DIR` flag installs from a local copy; `--dry-run` shows the plan without changing anything.
|
||||
|
||||
### Step 2: Start Building
|
||||
### Options
|
||||
|
||||
| Flag | Meaning |
|
||||
|------|---------|
|
||||
| `--local` | install into `./.opencode` (default) |
|
||||
| `--global` | install into `~/.config/opencode` |
|
||||
| `--install-dir PATH` | install into an exact path |
|
||||
| `--source DIR` | install from a local clone instead of downloading |
|
||||
| `--branch REF` | branch/tag to install from (default `main`) |
|
||||
| `--yes` / `-y` | non-interactive; skip existing files |
|
||||
| `--force` | non-interactive; overwrite existing files |
|
||||
| `--dry-run` | show what would happen, change nothing |
|
||||
| `--help` | usage |
|
||||
|
||||
### Manual install
|
||||
|
||||
```bash
|
||||
opencode --agent OpenAgent
|
||||
> "Create a user authentication system"
|
||||
git clone https://git.lohmar.co.uk/cclohmar/NewOpenAgents.git /tmp/oac
|
||||
mkdir -p .opencode
|
||||
cp -R /tmp/oac/agent /tmp/oac/command /tmp/oac/context \
|
||||
/tmp/oac/skills /tmp/oac/tool /tmp/oac/env.example \
|
||||
/tmp/oac/package.json .opencode/
|
||||
```
|
||||
|
||||
### 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:
|
||||
```bash
|
||||
/plugin marketplace add darrenhinde/OpenAgentsControl
|
||||
```
|
||||
|
||||
2. Install the plugin:
|
||||
```bash
|
||||
/plugin install oac
|
||||
```
|
||||
|
||||
3. Download context files:
|
||||
```bash
|
||||
/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](./plugins/claude-code/README.md) - Complete plugin documentation
|
||||
- [First-Time Setup](./plugins/claude-code/FIRST-TIME-SETUP.md) - Step-by-step guide
|
||||
- [Quick Start](./plugins/claude-code/QUICK-START.md) - 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)
|
||||
Then start OpenCode and pick your agent:
|
||||
|
||||
```bash
|
||||
/add-context
|
||||
opencode # choose OpenArchitect for the controlling tier, OpenAgent to build
|
||||
```
|
||||
|
||||
**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.)
|
||||
## The context system — your patterns, loaded first
|
||||
|
||||
**Result:** Agents now generate code matching your exact patterns. No refactoring needed.
|
||||
*(Inherited from upstream OAC — the secret weapon stays.)*
|
||||
|
||||
### The MVI Advantage: Token Efficiency
|
||||
Most agents are like hiring a developer who doesn't know your codebase. They write generic code; you spend hours fixing it. **OAC loads YOUR patterns before it writes a line.** The Architect and the builders both read the same context files, so the whole agency agrees on the standards.
|
||||
|
||||
**MVI (Minimal Viable Information)** = Only load what's needed, when it's needed.
|
||||
- **Minimal Viable Information (MVI)** — context files stay small (<200 lines) and load lazily. Only what's needed, when it's needed.
|
||||
- **`ContextScout`** finds the project's own rules before any work; **`ExternalScout`** fetches the *current* docs for any external library.
|
||||
- **Team-ready** — commit your patterns to the repo and every agent (and every teammate) inherits them on day one.
|
||||
|
||||
**Traditional approach:**
|
||||
- Loads entire codebase context
|
||||
- Large token overhead per request
|
||||
- Slow responses, high costs
|
||||
Key files:
|
||||
|
||||
**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)
|
||||
| Context | Use |
|
||||
|---------|-----|
|
||||
| `context/core/standards/code-quality.md` | before writing code |
|
||||
| `context/core/standards/documentation.md` | before writing docs |
|
||||
| `context/core/standards/test-coverage.md` | before writing tests |
|
||||
| `context/core/workflows/code-review.md` | before reviewing |
|
||||
| `context/core/workflows/delegation.md` | before delegating to a subagent |
|
||||
| `context/project-intelligence/` | the living notes: domain, decisions, tech |
|
||||
|
||||
**Real benefits:**
|
||||
- **Efficiency:** Lower token usage vs loading entire codebase
|
||||
- **Speed:** Faster responses with smaller context
|
||||
- **Quality:** Code matches your patterns (no refactoring)
|
||||
## Commands
|
||||
|
||||
### For Teams: Repeatable Patterns
|
||||
| Command | What it does |
|
||||
|---------|--------------|
|
||||
| `/commit` | create a well-formatted conventional commit and push |
|
||||
| `/test` | run the full testing pipeline |
|
||||
| `/context` | harvest / extract / organise context |
|
||||
| `/add-context` | interactive wizard to add project patterns |
|
||||
| `/optimize` | analyse for performance & security issues |
|
||||
| `/clean` | format, sort imports, lint |
|
||||
| `/analyze-patterns` | find similar implementations in the codebase |
|
||||
| `/validate-repo` | check consistency across agents, docs and context |
|
||||
|
||||
**The team problem:** Every developer writes code differently. Inconsistent patterns. Hard to maintain.
|
||||
## Configuration
|
||||
|
||||
**The OAC 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, OAC 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
|
||||
Agents are plain Markdown — edit them directly, no build step:
|
||||
|
||||
```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
|
||||
nano .opencode/agent/OpenArchitect.md # the controlling tier
|
||||
nano .opencode/agent/subagents/openagent.md # the builder persona
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Loads your patterns via ContextScout
|
||||
- Proposes plan (you approve)
|
||||
- Executes with validation
|
||||
- Delegates to specialists when needed
|
||||
Model selection is optional and lives in your OpenCode config (`.opencode/opencode.json` or global). Nothing here is vendor-locked.
|
||||
|
||||
**Perfect for:** First-time users, simple features, learning the workflow
|
||||
## Attributions & license
|
||||
|
||||
### 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 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. 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: OAC 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: OAC 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. OAC 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 OAC?**
|
||||
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!**
|
||||
- **Upstream:** [OpenAgents Control](https://github.com/darrenhinde/OpenAgentsControl) by **Darren Hinde** — MIT. The context system, subagents, commands and skills come from there. The original upstream README is preserved as [`README.upstream.md`](README.upstream.md).
|
||||
- **This fork:** the **Controlling Architect** concept, the architect/builder agency, the channels and the GMS-flavoured rules — maintained by **Claus Lohmar**.
|
||||
- **License:** MIT.
|
||||
|
|
|
|||
823
README.upstream.md
Normal file
823
README.upstream.md
Normal file
|
|
@ -0,0 +1,823 @@
|
|||
<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 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 →](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
|
||||
```
|
||||
|
||||
### Keep Updated
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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:**
|
||||
|
||||
1. Register the marketplace:
|
||||
```bash
|
||||
/plugin marketplace add darrenhinde/OpenAgentsControl
|
||||
```
|
||||
|
||||
2. Install the plugin:
|
||||
```bash
|
||||
/plugin install oac
|
||||
```
|
||||
|
||||
3. Download context files:
|
||||
```bash
|
||||
/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](./plugins/claude-code/README.md) - Complete plugin documentation
|
||||
- [First-Time Setup](./plugins/claude-code/FIRST-TIME-SETUP.md) - Step-by-step guide
|
||||
- [Quick Start](./plugins/claude-code/QUICK-START.md) - 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)
|
||||
|
||||
```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
|
||||
|
||||
**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:**
|
||||
```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, OAC 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 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. 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: OAC 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: OAC 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. OAC 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 OAC?**
|
||||
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!**
|
||||
402
install.sh
Executable file
402
install.sh
Executable file
|
|
@ -0,0 +1,402 @@
|
|||
#!/usr/bin/env bash
|
||||
#
|
||||
# OpenAgents Control — Architect Fork · installer
|
||||
# ============================================================================
|
||||
# Installs the OAC Architect Fork — the agents, subagents, commands, context,
|
||||
# skills and tools — into a project's .opencode/ directory or the global
|
||||
# ~/.config/opencode/ directory.
|
||||
#
|
||||
# Adapted from Darren Hinde's OpenAgents Control installer (MIT).
|
||||
# upstream: https://github.com/darrenhinde/OpenAgentsControl
|
||||
# fork: https://git.lohmar.co.uk/cclohmar/NewOpenAgents
|
||||
#
|
||||
# Unlike upstream, this fork ships the COMPLETE .opencode payload at the repo
|
||||
# root (no registry.json), so the installer syncs the whole payload with
|
||||
# collision handling instead of resolving per-component from a registry.
|
||||
#
|
||||
# Usage:
|
||||
# ./install.sh # interactive: choose location
|
||||
# ./install.sh --local # into ./.opencode
|
||||
# ./install.sh --global # into ~/.config/opencode
|
||||
# ./install.sh --install-dir PATH # into an exact path
|
||||
# ./install.sh --source DIR # install from a local clone
|
||||
# ./install.sh --global --yes # non-interactive, skip existing files
|
||||
# ./install.sh --global --force # non-interactive, overwrite existing
|
||||
# ./install.sh --dry-run # show the plan, change nothing
|
||||
#
|
||||
# Environment:
|
||||
# OAC_TOKEN Forgejo token with repo:read (for a private remote fetch)
|
||||
# OPENCODE_BRANCH branch/tag to install from (default: main)
|
||||
# OPENCODE_INSTALL_DIR alternative to --install-dir
|
||||
# ============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Configuration
|
||||
# ---------------------------------------------------------------------------
|
||||
REPO_HOST="git.lohmar.co.uk"
|
||||
REPO_OWNER="cclohmar"
|
||||
REPO_NAME="NewOpenAgents"
|
||||
REPO_URL="https://${REPO_HOST}/${REPO_OWNER}/${REPO_NAME}"
|
||||
BRANCH="${OPENCODE_BRANCH:-main}"
|
||||
TOKEN="${OAC_TOKEN:-}"
|
||||
|
||||
# The payload that makes up an install (paths relative to the repo root)
|
||||
PAYLOAD_DIRS="agent command context skills tool"
|
||||
PAYLOAD_FILES="env.example package.json"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Colours (only when writing to a terminal)
|
||||
# ---------------------------------------------------------------------------
|
||||
if [ -t 1 ]; then
|
||||
RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'; CYAN='\033[0;36m'; MAGENTA='\033[0;35m'
|
||||
BOLD='\033[1m'; NC='\033[0m'
|
||||
else
|
||||
RED=''; GREEN=''; YELLOW=''; BLUE=''; CYAN=''; MAGENTA=''; BOLD=''; NC=''
|
||||
fi
|
||||
|
||||
info() { printf "${BLUE}ℹ${NC} %s\n" "$1"; }
|
||||
success() { printf "${GREEN}✓${NC} %s\n" "$1"; }
|
||||
warn() { printf "${YELLOW}⚠${NC} %s\n" "$1"; }
|
||||
error() { printf "${RED}✗${NC} %s\n" "$1" >&2; }
|
||||
step() { printf "\n${MAGENTA}${BOLD}▶${NC} %s\n\n" "$1"; }
|
||||
die() { error "$1"; exit 1; }
|
||||
|
||||
print_header() {
|
||||
printf "${CYAN}${BOLD}"
|
||||
cat <<'BANNER'
|
||||
╔════════════════════════════════════════════════════════════════╗
|
||||
║ ║
|
||||
║ OpenAgents Control — Architect Fork · Installer ║
|
||||
║ the Controlling Architect + the build agents ║
|
||||
║ ║
|
||||
╚════════════════════════════════════════════════════════════════╝
|
||||
BANNER
|
||||
printf "${NC}\n"
|
||||
}
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
OpenAgents Control — Architect Fork · installer
|
||||
|
||||
Installs the OAC Architect Fork into a project's .opencode/ or the global
|
||||
~/.config/opencode/ directory.
|
||||
|
||||
Usage:
|
||||
$(basename "$0") [OPTIONS]
|
||||
|
||||
Location:
|
||||
--local Install into ./.opencode (default)
|
||||
--global Install into ~/.config/opencode
|
||||
--install-dir PATH Install into an exact path
|
||||
(with no location flag, an interactive menu is shown)
|
||||
|
||||
Source:
|
||||
--source DIR Install from a local copy instead of downloading
|
||||
--branch REF Branch/tag to fetch (default: main)
|
||||
--token TOKEN Forgejo token with repo:read (private fetch)
|
||||
|
||||
Behaviour:
|
||||
-y, --yes Non-interactive; skip files that already exist
|
||||
--force Non-interactive; overwrite existing files
|
||||
--dry-run Show what would happen; change nothing
|
||||
-h, --help Show this help
|
||||
|
||||
Environment:
|
||||
OAC_TOKEN Token used for a private remote fetch
|
||||
OPENCODE_BRANCH Branch/tag to fetch
|
||||
OPENCODE_INSTALL_DIR Same as --install-dir
|
||||
|
||||
Examples:
|
||||
git clone ${REPO_URL}.git ~/.oac && ~/.oac/install.sh --global
|
||||
./install.sh --local
|
||||
./install.sh --install-dir ~/my-agents --dry-run
|
||||
EOF
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Arguments
|
||||
# ---------------------------------------------------------------------------
|
||||
INSTALL_DIR="${OPENCODE_INSTALL_DIR:-}"
|
||||
LOCATION=""
|
||||
ASSUME_YES=0
|
||||
FORCE=0
|
||||
DRY_RUN=0
|
||||
SOURCE=""
|
||||
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--local) LOCATION="local" ;;
|
||||
--global) LOCATION="global" ;;
|
||||
--install-dir) [ $# -ge 2 ] || die "--install-dir needs a path"; INSTALL_DIR="$2"; LOCATION="custom"; shift ;;
|
||||
--install-dir=*) INSTALL_DIR="${1#*=}"; LOCATION="custom" ;;
|
||||
--source) [ $# -ge 2 ] || die "--source needs a path"; SOURCE="$2"; shift ;;
|
||||
--source=*) SOURCE="${1#*=}" ;;
|
||||
--branch) [ $# -ge 2 ] || die "--branch needs a ref"; BRANCH="$2"; shift ;;
|
||||
--branch=*) BRANCH="${1#*=}" ;;
|
||||
--token) [ $# -ge 2 ] || die "--token needs a value"; TOKEN="$2"; shift ;;
|
||||
--token=*) TOKEN="${1#*=}" ;;
|
||||
-y|--yes) ASSUME_YES=1 ;;
|
||||
--force) ASSUME_YES=1; FORCE=1 ;;
|
||||
--dry-run) DRY_RUN=1 ;;
|
||||
-h|--help) usage; exit 0 ;;
|
||||
*) error "Unknown option: $1"; echo; usage; exit 1 ;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Dependencies
|
||||
# ---------------------------------------------------------------------------
|
||||
command -v tar >/dev/null 2>&1 || die "tar is required but not installed"
|
||||
if [ -z "$SOURCE" ] && [ -z "$TOKEN" ]; then
|
||||
command -v git >/dev/null 2>&1 || die "git is required (or pass --token and install curl)"
|
||||
fi
|
||||
if [ -n "$TOKEN" ]; then
|
||||
command -v curl >/dev/null 2>&1 || die "curl is required when using --token"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Resolve the source payload
|
||||
# ---------------------------------------------------------------------------
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd)"
|
||||
|
||||
TMP_DIR=""
|
||||
cleanup() { if [ -n "$TMP_DIR" ]; then rm -rf "$TMP_DIR" 2>/dev/null || true; fi; }
|
||||
trap cleanup EXIT INT TERM
|
||||
|
||||
resolve_source() {
|
||||
# 1) explicit --source
|
||||
if [ -n "$SOURCE" ]; then
|
||||
[ -d "$SOURCE/agent" ] || die "--source '$SOURCE' does not look like the OAC repo (no agent/ dir)"
|
||||
SOURCE="$(cd "$SOURCE" && pwd)"
|
||||
info "Using local source: $SOURCE"
|
||||
return
|
||||
fi
|
||||
|
||||
# 2) the script's own directory, when run from a clone
|
||||
if [ -d "$SCRIPT_DIR/agent" ] && [ -d "$SCRIPT_DIR/context" ]; then
|
||||
SOURCE="$SCRIPT_DIR"
|
||||
info "Using the clone this script lives in: $SOURCE"
|
||||
return
|
||||
fi
|
||||
|
||||
# 3) download
|
||||
TMP_DIR="$(mktemp -d 2>/dev/null || mktemp -d -t oac)"
|
||||
if [ -n "$TOKEN" ]; then
|
||||
step "Downloading the fork (branch: ${BRANCH})…"
|
||||
local archive="https://${REPO_HOST}/${REPO_OWNER}/${REPO_NAME}/archive/${BRANCH}.tar.gz"
|
||||
curl -fsSL -H "Authorization: token ${TOKEN}" "$archive" -o "$TMP_DIR/repo.tar.gz" \
|
||||
|| die "Download failed. Check --token / --branch."
|
||||
tar -xzf "$TMP_DIR/repo.tar.gz" -C "$TMP_DIR"
|
||||
SOURCE="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d -print -quit)"
|
||||
[ -n "$SOURCE" ] || die "Could not find the extracted payload"
|
||||
success "Downloaded."
|
||||
else
|
||||
step "Cloning the fork (branch: ${BRANCH})…"
|
||||
git clone --depth 1 --branch "$BRANCH" "$REPO_URL" "$TMP_DIR/repo" \
|
||||
|| die "Clone failed. For a private repo, configure git credentials or pass --token."
|
||||
SOURCE="$TMP_DIR/repo"
|
||||
success "Cloned."
|
||||
fi
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Resolve the install directory
|
||||
# ---------------------------------------------------------------------------
|
||||
global_path() { printf '%s/.config/opencode' "$HOME"; }
|
||||
|
||||
choose_location_interactive() {
|
||||
local gp; gp="$(global_path)"
|
||||
echo -e "${BOLD}Where should the fork be installed?${NC}\n"
|
||||
echo -e " ${GREEN}1)${NC} Local — ${CYAN}./.opencode${NC} (this project only)"
|
||||
echo -e " ${BLUE}2)${NC} Global — ${CYAN}${gp}${NC} (every project)"
|
||||
echo -e " ${MAGENTA}3)${NC} Custom — enter a path"
|
||||
echo -e " 4) Cancel"
|
||||
echo
|
||||
printf "Enter your choice [1-4]: "
|
||||
read -r choice
|
||||
case "$choice" in
|
||||
1) INSTALL_DIR="$(pwd)/.opencode" ;;
|
||||
2) INSTALL_DIR="$gp" ;;
|
||||
3) printf "Enter installation path: "; read -r custom
|
||||
[ -n "$custom" ] || die "No path entered"
|
||||
case "$custom" in "~"*) custom="${HOME}${custom#\~}" ;; esac
|
||||
INSTALL_DIR="$custom" ;;
|
||||
4) info "Cancelled."; exit 0 ;;
|
||||
*) die "Invalid choice" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
resolve_install_dir() {
|
||||
if [ -n "$INSTALL_DIR" ]; then
|
||||
return
|
||||
fi
|
||||
case "$LOCATION" in
|
||||
local) INSTALL_DIR="$(pwd)/.opencode" ;;
|
||||
global) INSTALL_DIR="$(global_path)" ;;
|
||||
custom) die "--install-dir requires a path" ;;
|
||||
*)
|
||||
if [ -t 0 ] && [ -t 1 ]; then
|
||||
choose_location_interactive
|
||||
else
|
||||
INSTALL_DIR="$(pwd)/.opencode"
|
||||
info "No location given — defaulting to ./.opencode"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Collision strategy
|
||||
# ---------------------------------------------------------------------------
|
||||
STRATEGY="overwrite" # skip | overwrite | backup
|
||||
|
||||
do_choose_strategy() {
|
||||
echo
|
||||
warn "Some items already exist in ${INSTALL_DIR}"
|
||||
echo
|
||||
echo -e "${BOLD}How should existing items be handled?${NC}\n"
|
||||
echo -e " ${GREEN}1)${NC} Skip — keep existing items, install only new ones"
|
||||
echo -e " ${YELLOW}2)${NC} Overwrite — replace existing items (your changes are lost)"
|
||||
echo -e " ${CYAN}3)${NC} Backup — back up existing items, then overwrite"
|
||||
echo -e " ${RED}4)${NC} Cancel"
|
||||
echo
|
||||
printf "Enter your choice [1-4]: "
|
||||
read -r choice
|
||||
case "$choice" in
|
||||
1) STRATEGY="skip" ;;
|
||||
2) printf "Type 'yes' to confirm overwrite: "; read -r c
|
||||
[ "$c" = "yes" ] || { info "Cancelled."; exit 0; }
|
||||
STRATEGY="overwrite" ;;
|
||||
3) STRATEGY="backup" ;;
|
||||
4) info "Cancelled."; exit 0 ;;
|
||||
*) die "Invalid choice" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Install
|
||||
# ---------------------------------------------------------------------------
|
||||
BACKUP_DIR=""
|
||||
|
||||
copy_entry() {
|
||||
local name="$1" kind="$2" src="$3" dest="$4"
|
||||
if [ -e "$dest" ]; then
|
||||
case "$STRATEGY" in
|
||||
skip)
|
||||
info "Skipped existing ${kind}: ${name}"
|
||||
return 0 ;;
|
||||
backup)
|
||||
local rel="${dest#${INSTALL_DIR}/}"
|
||||
mkdir -p "$BACKUP_DIR/$(dirname "$rel")"
|
||||
cp -R "$dest" "$BACKUP_DIR/$rel"
|
||||
;;
|
||||
esac
|
||||
[ "$DRY_RUN" = 1 ] || rm -rf "$dest"
|
||||
fi
|
||||
if [ "$DRY_RUN" = 1 ]; then
|
||||
info "[dry-run] would install ${kind}: ${name} -> ${dest}"
|
||||
else
|
||||
cp -R "$src" "$(dirname "$dest")/"
|
||||
success "Installed ${kind}: ${name}"
|
||||
fi
|
||||
}
|
||||
|
||||
perform_install() {
|
||||
local installed=0 skipped=0
|
||||
|
||||
# Scan for collisions to decide the strategy
|
||||
local have_collision=0 e
|
||||
for e in $PAYLOAD_DIRS $PAYLOAD_FILES; do
|
||||
if [ -e "$INSTALL_DIR/$e" ]; then have_collision=1; break; fi
|
||||
done
|
||||
|
||||
if [ "$have_collision" = 1 ]; then
|
||||
if [ "$FORCE" = 1 ]; then
|
||||
STRATEGY="overwrite"
|
||||
elif [ "$ASSUME_YES" = 1 ]; then
|
||||
STRATEGY="skip"
|
||||
info "Non-interactive: existing items will be skipped"
|
||||
elif [ -t 0 ] && [ -t 1 ]; then
|
||||
do_choose_strategy
|
||||
else
|
||||
STRATEGY="skip"
|
||||
info "Non-interactive: existing items will be skipped"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$STRATEGY" = "backup" ] && [ "$DRY_RUN" != 1 ]; then
|
||||
BACKUP_DIR="${INSTALL_DIR}.backup.$(date +%Y%m%d-%H%M%S)"
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
info "Backing up to ${BACKUP_DIR}"
|
||||
fi
|
||||
|
||||
if [ "$DRY_RUN" != 1 ]; then
|
||||
mkdir -p "$INSTALL_DIR"
|
||||
fi
|
||||
|
||||
local d f
|
||||
for d in $PAYLOAD_DIRS; do
|
||||
[ -d "$SOURCE/$d" ] || continue
|
||||
if [ -e "$INSTALL_DIR/$d" ] && [ "$STRATEGY" = "skip" ]; then
|
||||
info "Skipped existing directory: ${d}/"
|
||||
skipped=$((skipped + 1))
|
||||
continue
|
||||
fi
|
||||
copy_entry "$d/" "directory" "$SOURCE/$d" "$INSTALL_DIR/$d"
|
||||
installed=$((installed + 1))
|
||||
done
|
||||
for f in $PAYLOAD_FILES; do
|
||||
[ -f "$SOURCE/$f" ] || continue
|
||||
if [ -e "$INSTALL_DIR/$f" ] && [ "$STRATEGY" = "skip" ]; then
|
||||
info "Skipped existing file: ${f}"
|
||||
skipped=$((skipped + 1))
|
||||
continue
|
||||
fi
|
||||
copy_entry "$f" "file" "$SOURCE/$f" "$INSTALL_DIR/$f"
|
||||
installed=$((installed + 1))
|
||||
done
|
||||
|
||||
echo
|
||||
if [ "$DRY_RUN" = 1 ]; then
|
||||
warn "Dry run complete — nothing was changed."
|
||||
else
|
||||
success "Installation complete."
|
||||
echo -e " Destination: ${CYAN}${INSTALL_DIR}${NC}"
|
||||
[ "$skipped" -gt 0 ] && echo -e " Skipped: ${CYAN}${skipped}${NC}"
|
||||
[ -n "$BACKUP_DIR" ] && echo -e " Backup: ${CYAN}${BACKUP_DIR}${NC}"
|
||||
fi
|
||||
}
|
||||
|
||||
show_post_install() {
|
||||
step "Next steps"
|
||||
echo "1. Review what was installed in ${CYAN}${INSTALL_DIR}${NC}"
|
||||
if [ -f "$INSTALL_DIR/env.example" ]; then
|
||||
echo "2. (Optional) configure integrations: ${CYAN}cp ${INSTALL_DIR}/env.example .env${NC}"
|
||||
fi
|
||||
echo "3. Start OpenCode and pick an agent:"
|
||||
echo -e " ${CYAN}opencode${NC} → choose ${BOLD}OpenArchitect${NC} to spec/verify, ${BOLD}OpenAgent${NC} to build"
|
||||
echo
|
||||
info "Docs: ${REPO_URL}"
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Main
|
||||
# ---------------------------------------------------------------------------
|
||||
main() {
|
||||
print_header
|
||||
resolve_source
|
||||
resolve_install_dir
|
||||
|
||||
info "Source: ${SOURCE}"
|
||||
info "Destination: ${INSTALL_DIR}"
|
||||
[ "$DRY_RUN" = 1 ] && warn "Dry run — no changes will be written"
|
||||
|
||||
perform_install
|
||||
[ "$DRY_RUN" != 1 ] && show_post_install
|
||||
}
|
||||
|
||||
main
|
||||
Loading…
Reference in a new issue