You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+110-9Lines changed: 110 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,14 +7,24 @@
7
7
<ahref="https://github.com/sponsors/jcarlosrodicio"><imgsrc="https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors&logoColor=white"alt="Sponsor on GitHub"></a>
8
8
</p>
9
9
10
-
A reproducible product-development workflow for OpenCode.
10
+
**An open-source multi-agent orchestration harness for OpenCode.**
11
11
12
-
Turn OpenCode into a structured team of specialized agents that can research, design, specify, implement, review, and validate software changes — without building every agent, command, skill, tool, and workflow convention from scratch.
12
+
OpenCode Agent Orchestration Kit (OAK) turns OpenCode into a structured
13
+
software-engineering team of specialized agents for research, design,
14
+
specification, implementation, review, and validation. It keeps OpenCode agent
15
+
orchestration local, inspectable, version-controlled, and reproducible.
13
16
14
-
Built for developers and small teams who want more structure than a single general-purpose coding agent, while keeping the setup local, inspectable, version-controlled, and adaptable.
17
+
Unlike systems designed primarily around large parallel worker pools, OAK
18
+
focuses on bounded engineering workflows with durable state, explicit
19
+
handoffs, independent review, validation evidence, and optional human approval
20
+
gates. It is model-agnostic within OpenCode: each role can use the default
21
+
model or an explicit provider/model available in the user's OpenCode setup.
> This project is a configuration and workflow kit for OpenCode. It is not a hosted platform, a fully autonomous software factory, or a replacement for engineering judgment.
26
+
> This software-engineering agent harness is not a hosted platform, a fully
27
+
> autonomous software factory, or a replacement for engineering judgment.
18
28
19
29
## Why this exists
20
30
@@ -61,6 +71,28 @@ The goal is not to force every request through a heavy process. Small, clear, lo
61
71
| Optional token visibility | TUI plugin for lead and subagent token usage when OpenCode exposes session trees |
62
72
| Versioned documentation | Agent, command, evidence, and validation contracts stored alongside the configuration |
63
73
74
+
### Bounded autonomous execution
75
+
76
+
OAK supports explicitly requested autonomous local work without turning it
77
+
into unlimited or unattended execution:
78
+
79
+
-`/loop` requires an approved task contract before writes, allows at most
80
+
three iterations per invocation within a task-specific one-to-six iteration
81
+
budget, and can resume from durable state. Worktrees are explicit opt-in.
82
+
-`/autonomous` is local-checkout-only, uses a task-specific one-to-six
83
+
iteration budget, runs deterministic validation in every iteration, and
84
+
stops as soon as an independent `reviewer` approves the result.
85
+
- Both workflows use a schema-versioned JSON snapshot, append-only JSONL
86
+
history, an exclusive lock, contract hashing, idempotent action IDs, and
87
+
explicit recovery for interrupted writes.
88
+
89
+
The `/autonomous` contract prohibits network access, worktrees, parallel
deployments, releases, and publication. Sensitive or expanded scope stops for
92
+
human review. See the [`/loop`](opencode/commands/loop.md) and
93
+
[`/autonomous`](opencode/commands/autonomous.md) contracts for the exact
94
+
boundaries.
95
+
64
96
## Built around
65
97
66
98
This kit builds on and integrates with the following projects:
@@ -93,6 +125,51 @@ This kit may not be the right fit if you:
93
125
- Need autonomous parallel execution across many repositories or worktrees.
94
126
- Expect every request to be fully automated without human oversight.
95
127
128
+
## How OAK compares
129
+
130
+
OpenCode orchestration projects optimize for different operating models. This
131
+
summary describes their documented emphasis; it is not a universal ranking.
132
+
133
+
| Approach | Documented emphasis | Consider it when |
134
+
|---|---|---|
135
+
|**OAK**| Versioned software-engineering workflows, specialized phase roles, durable bounded loops, independent review, and local safety contracts | You want research → specification → implementation → review with explicit scope and evidence |
136
+
|[`opencode-orchestrator`](https://github.com/agnusdei1207/opencode-orchestrator)| A persisted mission runtime with Commander, Planner, Worker, and Reviewer roles, local memory, and configurable agent concurrency | You want runtime-governed mission execution and a larger concurrent worker pool |
137
+
|[`oh-my-openagent`](https://github.com/code-yeongyu/oh-my-openagent)| A broad multi-model agent harness with specialized agents, integrated tools, background agents, and opt-in parallel Team Mode | You want an extensive agent/tool ecosystem and optional parallel teams |
138
+
|[`opencode-agent-tree`](https://github.com/beremaran/opencode-agent-tree)| A plugin that makes an orchestrator decompose and delegate every request, with hands-on tools blocked and configurable delegation depth | You want enforced delegation trees and parallel fan-out of independent subtasks |
139
+
140
+
### Choose OAK when
141
+
142
+
- You want OpenCode to behave like a structured engineering team.
143
+
- You want research, specification, implementation, validation, and independent review to remain distinct.
144
+
- You need durable, resumable workflows with explicit scope and acceptance criteria.
145
+
- You prefer bounded autonomy and inspectable local contracts over unconstrained agent loops.
146
+
147
+
### Consider another orchestration approach when
148
+
149
+
- Your primary goal is maximizing parallel worker throughput.
150
+
- You need autonomous execution across many worktrees or repositories.
151
+
- You need a hosted orchestration or control-plane product.
152
+
- You want an unattended software factory rather than bounded engineering workflows.
153
+
154
+
See [OpenCode Agent Orchestration Approaches](docs/comparison.md) for the
155
+
comparison method, architectural distinctions, limitations, and source links.
156
+
157
+
## Engineering quality
158
+
159
+
OAK's reproducibility and safety claims are backed by checked repository
160
+
artifacts rather than a maturity label:
161
+
162
+
- 1,000+ automated unit and script tests across the package and shipped harness.
163
+
- Mechanical validation of agent, command, workflow, evidence, and routing contracts.
164
+
- Type checking plus dependency vulnerability, integrity, and signature audits.
165
+
- Isolated installation and exact-package smoke tests for the `oak` and `oc-switch` CLIs.
166
+
- Compatibility checks across the declared OpenCode and Node.js boundaries.
167
+
- Durable-state recovery, corruption, idempotency, and adversarial fixtures.
168
+
- Public/private configuration boundary checks and release-provenance validation.
169
+
170
+
The [Validation](#validation) section explains the normal and release-grade
171
+
checks and their limits.
172
+
96
173
## How it works
97
174
98
175
Free-form requests start with the `lead` agent.
@@ -316,7 +393,14 @@ From this checkout, run:
316
393
npm run oc-switch
317
394
```
318
395
319
-
To install the command globally with npm from the cloned checkout:
396
+
To install the command globally from the published npm package:
- Both use finite iteration budgets, deterministic validation, durable state,
39
+
and reviewer-only completion.
40
+
41
+
## Comparison table
42
+
43
+
| Project | Delivery form | Primary orchestration pattern | State and completion | Documented concurrency emphasis |
44
+
|---|---|---|---|---|
45
+
|**OAK**| Versioned OpenCode configuration, commands, skills, contracts, and CLI tools | Explicit software-engineering phases and handoffs | Schema-versioned loop state, append-only history, locks, contract hashes, recovery, and independent reviewer closure | Bounded loops are sequential; `/loop` permits only explicit worktree opt-in and `/autonomous` prohibits worktrees and parallelism |
46
+
|[`agnusdei1207/opencode-orchestrator`](https://github.com/agnusdei1207/opencode-orchestrator)| OpenCode plugin and local runtime | Commander → Planner → Worker → Reviewer mission loop | Persisted missions under `.opencode/`, verification gates, a mission ledger, and local-first memory | Configurable concurrency for planner, worker, and reviewer roles; Rust tooling includes parallel execution primitives |
47
+
|[`code-yeongyu/oh-my-openagent`](https://github.com/code-yeongyu/oh-my-openagent)| Multi-edition agent harness and plugin ecosystem | Main orchestrator delegates to planning, implementation, research, and review specialists | Plans and continuation mechanisms vary by mode; the project documents session recovery and persistent objectives | Background agents and opt-in Team Mode run specialized members in parallel |
48
+
|[`beremaran/opencode-agent-tree`](https://github.com/beremaran/opencode-agent-tree)| OpenCode plugin | An orchestrator-only agent decomposes every request and delegates all hands-on work through a configurable tree | The orchestrator reviews subagent reports and delegates corrections; its hands-on tools are denied by configuration | Its directive encourages parallel fan-out for independent subtasks and supports configurable orchestration depth |
49
+
50
+
The rows describe documented architecture, not feature parity. For example,
51
+
OAK's durable loop contract and `opencode-orchestrator`'s mission runtime both
52
+
persist state, but they assign control and completion authority differently.
53
+
54
+
## OAK vs autonomous mission runtimes
55
+
56
+
An autonomous mission runtime owns the continuing execution loop. It can
57
+
schedule or re-invoke roles until the runtime decides that verification is
58
+
sufficient or escalation is required. This is useful when mission throughput
59
+
and runtime control are primary requirements.
60
+
61
+
OAK instead makes the approved workflow contract the control boundary. Its
62
+
bounded cycles use explicit iteration budgets and stop conditions, and only an
63
+
independent reviewer can close the work. Use this approach when reproducible
64
+
scope, evidence, and human-visible authority matter more than keeping a
65
+
mission running unattended.
66
+
67
+
## OAK vs delegation trees
68
+
69
+
A delegation-tree plugin focuses on ensuring that an orchestrator decomposes
70
+
work and never implements it directly. Deeper trees and parallel fan-out can
71
+
increase specialization or throughput.
72
+
73
+
OAK can delegate among specialized roles, but its central concern is the
74
+
meaning of each engineering phase: what the researcher must establish, what
75
+
the specifier must make testable, what the developer may change, and what the
76
+
reviewer must independently verify. Choose a delegation tree when enforced
77
+
task decomposition is the primary requirement; choose OAK when explicit phase
78
+
contracts and workflow evidence are the primary requirement.
79
+
80
+
## OAK vs large agent frameworks
81
+
82
+
Larger coding-agent frameworks may bundle broad tool suites, model routing,
83
+
background agents, hooks, compatibility layers, and interactive team modes.
84
+
That breadth is useful when one integrated agent environment is the goal.
85
+
86
+
OAK keeps the core OpenCode multi-agent workflow smaller and inspectable. It
87
+
uses OpenCode's model/provider configuration and treats design tools,
88
+
methodology plugins, and observability as optional integrations. The tradeoff
89
+
is deliberate: OAK does not attempt to match every runtime or tool feature of
90
+
a larger framework.
91
+
92
+
## Workflow orchestration vs worker-pool orchestration
93
+
94
+
Workflow orchestration organizes responsibility and evidence across stages:
95
+
96
+
```text
97
+
research -> specification -> implementation -> validation -> independent review
0 commit comments