OpenCode Nexus

Fixed three-agent development workflow for OpenCode.

Nexus installs a predictable team into OpenCode: orchestrator, implementer, and reviewer — with the Nexus Impact Engine, TDD evidence, isolated worktrees, and durable run state under .opencode/.

you describe the work
↓
orchestrator brainstorms → plans
↓
(for each task) pre-impact → implementer → post-impact + verify → reviewer
↓
REQUEST_CHANGES? → fresh pre-impact → implementer → reviewer (auto)
↓
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 task.

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 pipeline: brainstorm → plan → per-task 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 task; 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 agents:

Agent	Role
`orchestrator`	Owns the fixed workflow, plan, and task loop
`implementer`	Implements one task and verifies it
`reviewer`	Spec + correctness + quality + regression review every task

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, profiles, 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.

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`

Canonical agent files: orchestrator, implementer, reviewer.

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

Optional compatibility agent

V5 does not install optional agents. Nexus Impact Engine (nexus impact) covers git, AST, and affected test evidence.

nexus install --with-optional-agents
# from a clone:
./install.sh --with-optional-agents

A later nexus install (without the flag) removes leftover blast-analyzer config and agent files, including copies written by older Nexus releases. To keep it, pass --with-optional-agents again on that update.

To drop it explicitly:

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 classifies risk, plans, maps impact with the Nexus Impact Engine, then dispatches implementer and reviewers.

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, classify, 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 --profile balanced

Impact analysis & baseline:

nexus impact --json
nexus baseline
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

The exact transition sequence depends on the profile and whether the run is direct, delegated, or blocked. A stale or uncertain analysis must be verified before a direct path is allowed.

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. Only classify --apply may authorize direct_eligible. Impact trust requires provider revalidation — a caller-supplied trusted: true label is not enough.

How the workflow works

request → classify → plan → impact → baseline → implement → review → final-verify → finish
│
└─ stale or blocked → reconcile

Only the implementer writes production code. Review shape comes from the profile and the change class:

Profile	When	Branching	Review
`fast`	Tiny, low-risk, high-confidence	One branch per request	Unified review, or skip for docs
`balanced` (default)	Normal features	One branch per feature / execution unit	Risk-based
`strict`	Security, migration, public API, credentials	One branch per task	Spec review, then code review

High-risk work always uses strict and dual review. A HIGH impact always escalates review to dual; the execution profile can stay balanced when impact analysis still says batching is safe.

UNKNOWN impact evidence never classifies as fast. Direct (no-dispatch) work is narrow: small, focused, low-risk, and high classifier confidence.

Full policy: docs/workflow.md.

Where files land

Path	What
`.opencode/runs/<run-id>/state.json`	Durable state-machine state
`.opencode/CONTEXT.md`	Active profile, branch, 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

One-off overrides (no file edit):

Variable	Effect
`NEXUS_ORCHESTRATOR_MODEL`	Orchestrator model
`NEXUS_IMPLEMENTER_MODEL`	Implementer model
`NEXUS_REVIEWER_MODEL`	Reviewer 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 and optional-agent 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-adapter-contract.sh
bash -n install.sh uninstall.sh scripts/test-install-only.sh \
scripts/test-optional-agents.sh scripts/test-adapter-contract.sh

Confirm agents on disk:

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

Repository layout

agents/ canonical agent definitions
skills/ workflow skills the orchestrator loads
config/ profiles and model defaults
scripts/ impact, classify, state machine, estimate, cleanup
schemas/ handoff, impact, and run-state JSON schemas
bin/nexus.js npm CLI: install | update | uninstall | doctor
docs/workflow.md V4 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

Optional compatibility agent

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
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

Optional compatibility agent

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