OpenCode Nexus

Fixed three-agent execution workflow with conditional planning advice for OpenCode.

Nexus installs a predictable team into OpenCode: orchestrator, implementer, and reviewer for execution, plus the conditional planning-only plan-advisor — with the Nexus Impact Engine, TDD evidence, isolated worktrees, and durable run state under .opencode/.

you describe the work
        ↓
orchestrator brainstorms → plans
        ↓
(standard/deep? plan-advisor → plan-check)
        ↓
(for each execution unit) pre-impact → implementer → post-impact + verify → reviewer
        ↓
REQUEST_CHANGES? → fresh pre-impact → implementer → reviewer (auto)
        ↓
multi-unit → final integration review → final verify → finish
single-unit + unchanged review evidence → final verify → finish

Principle: LLM proposes. Scripts measure. Tests prove. Independent reviewer approves. State machine decides.

Three invariants: (1) brainstorm + plan every request (2) fresh impact before every implementer (3) reviewer APPROVED every execution unit.

Package: @mohammad154/opencode-nexus · Node 20+ · MIT

The unscoped name opencode-nexus on npm is a different project. Always use @mohammad154/opencode-nexus.

At a glance

Nexus gives OpenCode a repeatable delivery loop with explicit ownership and evidence at each handoff:

Capability	What it adds
Orchestration	Fixed execution pipeline: brainstorm → plan → per-unit impact/implement/review loop
Impact mapping	Built-in Nexus Impact Engine (git + AST + imports + tests) before every implementer
Safe implementation	Production edits only via implementer, with branch, worktree, and handoff context
Always-on review	Single `reviewer` on every execution unit; auto fix-loop on REQUEST_CHANGES
Durable state	Stores plans, tasks, handoffs, impact reports, and run state so interrupted work can recover

Installed agents

After install, OpenCode has three canonical execution agents plus one planning-only specialist:

Agent	Role
`orchestrator`	Owns the fixed workflow, plan, and execution-unit loop
`implementer`	Implements one execution unit, running targeted checks after its internal steps
`reviewer`	Reviews each verified execution unit, then the whole branch for multi-unit integration
`plan-advisor`	Conditional read-only challenge for standard/deep plans; never executes code

Nexus also installs a plugin and model config, with the Nexus Impact Engine as the primary canonical evidence provider.

Plans, run state, handoffs, and impact reports live in .opencode/.

Quick start

Do this once on your machine, then open any project in OpenCode.

1. Install the tools Nexus needs (details in Prerequisites):

Node.js 20+, Git, Bash, jq
OpenCode
The Nexus Impact Engine is built-in and requires no external binaries.

2. Install the Nexus CLI globally, then set up OpenCode:

npm install -g @mohammad154/opencode-nexus@latest
nexus install

npm install -g only puts the nexus command on your machine (including ~/.local/bin when npm's global prefix is not on PATH). Run nexus install afterward so OpenCode gets the agents and plugin.

If nexus is still not found, you do not need to edit PATH — this is equivalent:

npx @mohammad154/opencode-nexus@latest install

3. Check that everything is in place:

nexus doctor

4. Restart OpenCode, pick the orchestrator agent, and describe the change you want.

That is the normal path. The rest of this README is for setup details and scripts.

Prerequisites

Required

Tool	Why
Node.js 20+	CLI, Nexus Impact Engine, state machine, call estimator
Bash	Installer (`Git Bash` or WSL on Windows)
Git	Branches, worktrees, change evidence
`jq`	Merges `opencode.json` on install/uninstall
OpenCode	Host for agents, plugin, and models

jq

# Ubuntu / Debian / WSL
sudo apt update && sudo apt install -y jq

# macOS
brew install jq

# Fedora / RHEL
sudo dnf install -y jq

# Windows
winget install jqlang.jq

jq --version

Optional (recommended)

rg (ripgrep) and fd (fd) speed up repository discovery.

# Ubuntu / Debian / WSL
sudo apt update && sudo apt install -y ripgrep fd-find
command -v fd >/dev/null || sudo ln -sf "$(command -v fdfind)" /usr/local/bin/fd

# macOS
brew install ripgrep fd

# Fedora / RHEL
sudo dnf install -y ripgrep fd-find
command -v fd >/dev/null || sudo ln -sf "$(command -v fdfind)" /usr/local/bin/fd

# Windows
winget install BurntSushi.ripgrep.MSVC
winget install sharkdp.fd

rg --version
fd --version

Install

npm install never touches OpenCode config. Setup is always explicit: nexus install.

Global CLI (recommended)

Install the nexus command once, then set up OpenCode:

npm install -g @mohammad154/opencode-nexus@latest
nexus install
nexus doctor

npm install -g never touches OpenCode config by itself. Always follow it with nexus install.

npm may install the binary under a custom prefix such as ~/.npm-global/bin. After a global install, Nexus also links nexus and opencode-nexus into ~/.local/bin so the command is available without extra PATH setup.

The same nexus install command updates an existing OpenCode setup.

Later:

npm update -g @mohammad154/opencode-nexus
nexus install

From a local clone

./install.sh

The installer is idempotent — re-run nexus install or ./install.sh to update.

If ~/.config/opencode/plugins/nexus.js is a live symlink (for example, to a checked-out hotfix), the installer preserves that local Nexus plugin and removes the Nexus npm-plugin entry from opencode.json. This prevents OpenCode from loading both the local copy and an older cached package. Restart OpenCode after changing the link or running the installer.

Git clone fallback (if you are not using npm):

rm -rf /tmp/opencode-nexus &&
git clone --depth 1 https://github.com/mohammad154/opencode-nexus.git /tmp/opencode-nexus &&
cd /tmp/opencode-nexus &&
./install.sh &&
cd - >/dev/null &&
rm -rf /tmp/opencode-nexus

What gets written

Output	Location
Agents	`~/.config/opencode/agents/*.md`
Plugin + models	`~/.config/opencode/opencode.json`
Optional model overrides	`~/.config/opencode/nexus.models.json` (including `plan-advisor`)

Canonical agent files: orchestrator, implementer, reviewer.

On Windows, set OPENCODE_CONFIG_DIR if your OpenCode config is not under ~/.config/opencode.

V4 migration

V5 installs only orchestrator, implementer, and reviewer as execution agents. It also ships the conditional, planning-only plan-advisor; this specialist is used only for standard/deep planning and is never part of the execution loop. Every nexus install update automatically removes retired V4 agent configuration and files, including blast-analyzer, split reviewers, and unified-reviewer. Nexus Impact Engine (nexus impact) supplies the git, AST, and affected-test evidence those agents previously covered.

--prune-optional-agents remains available for migration scripts, but is normally unnecessary because pruning is automatic:

nexus install --prune-optional-agents

Verification steps and notes: .opencode/INSTALL.md.

Use it

Open your project in OpenCode.
Select the orchestrator agent.
Describe the change (feature, bugfix, refactor). The orchestrator chooses planning depth, optionally obtains a read-only Plan Advisor challenge, runs the deterministic plan check, maps impact with the Nexus Impact Engine, then dispatches implementer and reviewer.

You usually do not need to run the scripts below by hand. They are the same gates the orchestrator uses.

Workflow scripts (optional / debugging)

Initialize a run, optionally inspect advisory classification evidence, and estimate agent calls:

nexus project-init
nexus run init --run-id demo
nexus classify --files 2 --lines 40 --class small-feature-with-tests --focused
nexus estimate --tasks 3
nexus plan-check --json                 # diagnostic only
nexus run transition --to PLANNED --plan-check  # persist the passing gate

Impact analysis & baseline:

nexus impact --json
nexus baseline
nexus verify
nexus verify --baseline

State machine and handoff checks:

nexus run transition --to BRAINSTORMING
nexus run status
nexus run validate-handoff \
  --role implementer \
  --file .opencode/handoffs/<run>-implementer.json

V5 has one fixed workflow—there is no profile selection or direct/no-dispatch path. nexus classify is advisory; nexus run classify --apply records its evidence but does not advance run state. A stale or uncertain analysis must be revalidated before the affected gate can pass.

Handoffs use schema_version 1.1 (shared envelope: run_id, unit_or_task, agent, base_commit, created_at). Legacy 1.0 / 0.9 handoffs migrate as legacy_unverified and cannot satisfy completion gates. Classification artifacts cannot authorize a state transition or bypass a required gate. Impact trust requires provider revalidation — a caller-supplied trusted: true label is not enough.

How the workflow works

request → brainstorm → plan advisor? → plan-check → (per unit) pre-impact → implement → VERIFYING → deterministic verify → unit review → final review → FINAL_VERIFYING → deterministic final verify → finish
                                                      │
                                                      └─ stale or blocked → reconcile

Only the implementer writes production code. Nexus uses one fixed V5 workflow:

Every implementer dispatch requires fresh pre-impact evidence.
Standard/deep plans may use one independent plan-advisor call before synthesis; compact plans do not.
nexus run transition --to PLANNED --plan-check runs the deterministic execution-unit DAG, acceptance/verification, decomposition-warning, and call-estimate gate and persists its passing report; standalone nexus plan-check is diagnostic.
Every execution unit states user_outcome, independently_shippable, review_boundary, and estimated_lines; implementation steps remain inside the unit.
The implementer runs targeted checks after internal steps. Nexus does not persist or authorize each step as a separate verification boundary: it runs deterministic nexus verify for the completed unit before dispatching one task reviewer.
Every task receives a task-scoped review package and reviewer after verification.
A reviewer REQUEST_CHANGES is capped at three remediation attempts per execution unit; exhaustion or an agent-call-budget limit becomes BLOCKED, not another subagent dispatch.
After the final task, a final review package and reviewer examine the whole branch and its multi-unit integration before final verification. The package includes Previous task review evidence; the final reviewer can reuse a task result only when review_evidence_bound: true, files_changed_after_review is available, and the criterion's owning files are absent from that list, then focus on integration and later changes. This never skips the final or task review. A single-unit run may reuse its task review only with the explicit digest/HEAD-bound gate.
Impact risk controls verification-ladder intensity; it does not select a workflow profile or change the review roster.
IMPLEMENTING → VERIFYING and FINAL_REVIEWING → FINAL_VERIFYING are fast authorization transitions. They persist verification_status: PENDING; they do not execute tests.
Run nexus verify in either verification state to measure fresh post-impact, discover the risk-based ladder, execute checks, and seal evidence. Only verification_status: PASSED authorizes the next review/completion transition. A timeout stays in the same state; use nexus verify --resume.
Pass complete handoffs by file (--implementer-handoff-file or --review-handoff-file) rather than rebuilding partial JSON in the orchestrator.

Full policy: docs/workflow.md.

Where files land

Path	What
`.opencode/runs/<run-id>/state.json`	Durable state-machine state
`.opencode/runs/<run-id>/verification.json`	Durable per-step verification progress and sealed-evidence summary
`.opencode/CONTEXT.md`	Active run, branch, and verification context
`.opencode/plans/PLAN.md` and `tasks/`	Plan and execution units
`.opencode/handoffs/`	Implementer and reviewer results
`.opencode/impact/`	Impact analysis reports
`.opencode/reconcile/`	Reconcile reports
`.opencode/memory/` + `reflections/LESSONS.md`	Outcome memory

Customize models

On first install, Nexus writes:

~/.config/opencode/nexus.models.example.json

Copy it, edit the agent entries, then re-run install so they merge into opencode.json:

cp ~/.config/opencode/nexus.models.example.json ~/.config/opencode/nexus.models.json
# edit nexus.models.json
nexus install

The default implementer has "steps": 64: a finite ceiling on agentic tool iterations. At the ceiling OpenCode requests a text summary instead of allowing unbounded tool calls. You can set a different positive steps value in your nexus.models.json override when a unit demonstrably needs it.

One-off overrides (no file edit):

Variable	Effect
`NEXUS_ORCHESTRATOR_MODEL`	Orchestrator model
`NEXUS_IMPLEMENTER_MODEL`	Implementer model
`NEXUS_REVIEWER_MODEL`	Reviewer model
`NEXUS_PLAN_ADVISOR_MODEL`	Planning-only advisor model; keep it different from the orchestrator model
`NEXUS_IMPLEMENTER_VARIANT` / `NEXUS_IMPLEMENTER_REASONING_EFFORT`	Implementer reasoning effort
`NEXUS_REVIEWER_VARIANT` / `NEXUS_REVIEWER_REASONING_EFFORT`	Reviewer reasoning effort

Example:

NEXUS_IMPLEMENTER_MODEL=anthropic/claude-sonnet-4-20250514 nexus install

Uninstall

Removes Nexus agents and plugin entries. Project-local .opencode/ data is left alone. Pre-existing OpenCode agent files are restored from installer backups when those backups exist.

nexus uninstall
npm uninstall -g @mohammad154/opencode-nexus

From a clone:

./uninstall.sh
# equivalent:
./install.sh --uninstall

Verify / tests

nexus doctor

From a clone of this repo:

npm test
npm run test:install

npm test runs the Node test suites. npm run test:install runs installer isolation, retired-agent cleanup, and uninstall lifecycle checks. There are no separate build, lint, or typecheck scripts.

Extra installer checks:

bash scripts/test-install-only.sh
bash scripts/test-optional-agents.sh
bash scripts/test-uninstall-lifecycle.sh
bash scripts/test-adapter-contract.sh
bash -n install.sh uninstall.sh scripts/test-install-only.sh \
  scripts/test-optional-agents.sh scripts/test-uninstall-lifecycle.sh \
  scripts/test-adapter-contract.sh

Confirm agents on disk:

ls ~/.config/opencode/agents/{orchestrator,implementer,reviewer,plan-advisor}.md

Repository layout

agents/          canonical execution + planning-only agent definitions
skills/          workflow skills the orchestrator loads
config/          fixed V5 workflow and model defaults
scripts/         impact, classify, state machine, plan-check, estimate, cleanup
schemas/         handoff, impact, and run-state JSON schemas
bin/nexus.js     npm CLI: install | update | uninstall | doctor
docs/workflow.md V5 workflow reference
install.sh       OpenCode installer
uninstall.sh     matching cleanup

License

MIT

Navigation Menu

Repository files navigation

OpenCode Nexus

Contents

At a glance

Installed agents

Quick start

Prerequisites

Required

Optional (recommended)

Install

Global CLI (recommended)

From a local clone

What gets written

V4 migration

Use it

Workflow scripts (optional / debugging)

How the workflow works

Where files land

Customize models

Uninstall

Verify / tests

Repository layout

Further reading

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.opencode		.opencode
agents		agents
bin		bin
config		config
docs		docs
schemas		schemas
scripts		scripts
skills		skills
temp/.opencode		temp/.opencode
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
package.json		package.json
uninstall.sh		uninstall.sh

Latest commit

History

Folders and files

Repository files navigation

OpenCode Nexus

Contents

At a glance

Installed agents

Quick start

Prerequisites

Required

Optional (recommended)

Install

Global CLI (recommended)

From a local clone

What gets written

V4 migration

Use it

Workflow scripts (optional / debugging)

How the workflow works

Where files land

Customize models

Uninstall

Verify / tests

Repository layout

Further reading

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages