
Security News
Re-Enabled GitHub Actions Expose Thousands of Repositories to Mini Shai-Hulud
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
opencode-agent-orchestration-kit
Advanced tools
[](https://github.com/jcarlosrodicio/opencode-agent-orchestration-kit/actions/workflows/check.yml) [
export OPENCODE_CONFIG_DIR="$PWD/opencode"
opencode auth login
opencode
OpenCode now loads the configuration from this repository instead of your default global config.
Try one of these commands:
/scope Research whether this repository should use Stripe Checkout or Payment Element and produce an MVP spec
/plan Add a dry-run flag to the harness check without implementing it yet
/feature Add a small settings page with a saved theme preference
Once you are happy with the workflow, preview and install it into your OpenCode configuration directory:
./install.sh --dry-run
./install.sh
The default target is:
${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}
Use a custom target when needed:
./install.sh --target "$HOME/.config/opencode"
An explicit --target wins over a non-empty OPENCODE_CONFIG_DIR, which wins over $HOME/.config/opencode. Argument values are literal; ~ is not expanded.
The installer inventories the payload, computes a complete plan, and tracks ownership in TARGET/.oak/manifest.json. A dry run performs no writes. A real operation recomputes the plan under an exclusive lock and commits through a durable journal with one rollback generation.
The root package.json is the canonical kit-version source. Display the same
identity through the manager or any lifecycle wrapper:
node scripts/version.mjs
./install.sh --version
./upgrade.sh --version
./doctor.sh --version
./uninstall.sh --version
./rollback.sh --version
Initial install preserves differing AGENTS.md, opencode.json, tui.json, package.json, and package-lock.json as user-owned files. Exact existing matches may be adopted without rewriting. Any other collision blocks the whole operation. A legacy installation without a manifest follows these same initial-install rules.
Use --force only on initial install to authorize replacement of colliding regular files after their bytes and modes are durably backed up:
./install.sh --force
It never authorizes directory or symlink replacement, unsafe paths, state repair, upgrade conflicts, or deletion of user-modified files.
After global installation, install the OpenCode config dependencies:
(cd "${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}" && npm ci --ignore-scripts)
Use that frozen command only when the installed package.json and
package-lock.json still match the shipped manifests. If installation
preserved differing manifests, review and merge the required dependencies
first, then choose the install command for that user-owned dependency graph.
The package also exposes the dependency-free oak CLI as a thin frontend over
the same tested engines:
oak --help
oak doctor
oak check
oak replay
oak state inspect --root /path/to/project --slug task-slug
The shell wrappers remain supported. oak check validates the installed target
without executing a target-provided checker, while oak replay defaults to the
packaged static corpus and synthetic fixtures. See the oak CLI
guide for commands, target precedence, exit codes, and explicit
exclusions.
oak state runs the packaged durable loop-state runtime against an explicit
project root; it is intended for bounded local workflows that need a journal,
lock, and recovery without copying harness scripts into the project.
Its completion gate requires a durable reviewer subagent APPROVE
attestation; see the CLI guide for the exact command.
Preview an ownership-safe upgrade, then apply it:
./upgrade.sh --dry-run
./upgrade.sh
Upgrade aborts before writing if an owned file is missing or modified, an obsolete owned file changed, or an unowned collision exists. Preserved files remain user-owned. When a shipped protected file changes, doctor reports whether the source, user copy, or both changed:
./doctor.sh
Upgrade also compares the local source version with kit_version in the active
manifest. A newer source may upgrade; equal version and payload is a no-op;
equal version with a different payload is blocked as an identity contradiction;
and an older source is blocked to prevent downgrade. doctor reports
not-installed, current, upgrade-available, source-older,
same-version-different-payload, or invalid-version-state without consulting
the network.
Doctor prints twelve ordered findings for OpenCode and Node compatibility,
installed dependencies, managed files and drift, required configuration,
optional plugins, permissions, executable scripts, the generated skill
registry, aggregate compatibility, and legacy residue. Each finding is
classified as pass, info, action-required, or not-applicable, followed
by a deterministic summary. It does not print configuration contents,
subprocess stderr, environment values, credentials, or rollback bytes.
Doctor returns 0 when no finding requires action, 1 for safely actionable
state, and 2 for invalid invocation, corrupt/unsafe state, or an unrecoverable
filesystem error. Suggested actions are never applied automatically, and
preserved custom configuration remains user-owned. See the
installation lifecycle guide for the full diagnostic
contract. To acknowledge a completed manual merge, run:
./doctor.sh --accept-preserved opencode.json
The command prints a full ACK-PRESERVED line containing the exact target/source hashes and modes. Paste that line back byte-for-byte; yes, a path alone, truncated values, or a stale tuple do not authorize mutation.
Uninstall previews first and removes only unchanged files owned by the manifest. Modified, missing, preserved, and unrelated user files are never deleted:
./uninstall.sh --dry-run
./uninstall.sh
./uninstall.sh --yes
The most recent committed install, upgrade, acknowledgement, or uninstall can be reversed once:
./rollback.sh --dry-run
./rollback.sh
If an operation was interrupted, rollback.sh uses the active journal to restore the pre-operation state instead. Do not delete or edit .oak manually: it contains ownership metadata, recovery state, and potentially sensitive exact backup bytes. See the installation lifecycle guide for command syntax, conflict handling, and recovery details.
The kit includes local skills that agents use as practical checklists rather than mandatory process overhead.
Included skills cover:
These skills are available under:
opencode/skills/
They are designed to help agents make better engineering decisions without forcing every task through every checklist.
The integrations below are optional extensions. They are not required for the core agent workflow.
| Integration | What it adds | Setup |
|---|---|---|
| Open Design | Editable, local-first design workspace workflows | Open Design guide |
| Superpowers | Additional skills and software-development workflow discipline | Superpowers guide |
| Impeccable | Design guidance and deterministic frontend-quality checks | Impeccable guide |
Open Design is included as an optional local integration for design-oriented workflows.
The designer agent can use:
PRODUCT.md and DESIGN.md.OPEN_DESIGN_URL.Set OPEN_DESIGN_URL to the base URL of your Open Design workbench:
export OPEN_DESIGN_URL="https://open-design.example.com"
A local or LAN URL is also valid:
export OPEN_DESIGN_URL="http://192.168.1.50:7456"
Do not use a project page or file URL:
# Invalid
export OPEN_DESIGN_URL="https://open-design.example.com/projects/my-project"
export OPEN_DESIGN_URL="https://open-design.example.com/projects/my-project/files/index.html"
Open Design is optional. You can use the rest of the kit without it.
A Docker setup is included:
cd docker/open-design
cp .env.example .env
docker compose up -d --build
If Open Design should use OpenCode as a design engine, authenticate inside the container:
docker exec -it open-design bash
opencode auth login
opencode models openai --refresh
exit
Then configure the Open Design base URL:
export OPEN_DESIGN_URL="http://192.168.1.50:7456"
Superpowers is not vendored into this repository.
When plugins are supported and network access is available, the kit can reference the upstream plugin:
{
"plugin": [
"superpowers@git+https://github.com/obra/superpowers.git#d884ae04edebef577e82ff7c4e143debd0bbec99"
]
}
The human-readable upstream release is v6.1.1; the configuration uses the
full reviewed commit because the label alone is not immutable:
{
"plugin": [
"superpowers@git+https://github.com/obra/superpowers.git#d884ae04edebef577e82ff7c4e143debd0bbec99"
]
}
If your existing opencode.json was preserved during installation, add the plugin manually.
Impeccable is optional and is not included in this repository.
Install it from its upstream source when you want the designer agent to use it as additional design context, particularly when project-specific PRODUCT.md or DESIGN.md files are missing.
The bundled TUI plugin can show:
This depends on OpenCode exposing the session tree through its TUI plugin API.
If your existing tui.json was preserved during installation, add the bundled plugin manually:
{
"plugin": [
"./plugins/token-tree-usage.tsx"
]
}
Normal harness use requires Node.js, npm, and a supported OpenCode version; it does not require a system SQLite client.
Full validation and development additionally require the external sqlite3
binary because the session-evidence tests create real SQLite fixtures. On
Ubuntu or Debian, install it with:
sudo apt-get install -y sqlite3
Run the normal local check with:
npm run check
The bundled routing corpus can also be replayed deterministically without calling a model:
node opencode/scripts/replay-routing.mjs \
--corpus opencode/docs/ai/evolution/benchmarks/router-scenarios.jsonl \
--fixtures opencode/docs/ai/evolution/benchmarks/replay-fixtures.jsonl
Aggregate one or more sanitized replay reports into deterministic routing metrics without calling a model or rereading raw evidence:
node opencode/scripts/summarize-routing-metrics.mjs \
--corpus opencode/docs/ai/evolution/benchmarks/router-scenarios.jsonl \
--report /path/to/routing-replay-report.json
Inconclusive observations are excluded from metric denominators. Token cost is reported as unavailable until the replay report schema carries token evidence.
An isolated live replay is available only through explicit opt-in. It may consume model tokens, is intentionally excluded from normal checks and CI, and does not persist model/provider configuration or raw output by default.
This runs the fast contract checker and every bundled node:test suite. For a
fast structural check while editing documentation or contracts, use
npm run check:quick. Before a release, use npm run check:release; it performs
a frozen dependency install and also runs typechecking, dependency integrity,
audit/signature checks, installation smoke, and the exact package smoke.
Publication remains separately authorized; follow the reviewed artifact and
checksum procedure in the supply-chain policy.
Validate only the canonical identity and current release note with:
npm run check:version
node scripts/version.mjs --check-tag v1.0.37
Tag validation compares an explicitly supplied tag with the package identity. It does not create or push a tag, publish npm content, or create a hosted release. Those remain separate manual, explicitly approved steps.
The contract checker validates the shipped harness, including:
lead routing contract./feature sidecar boundaries./plan behavior.opencode/docs/ai/harness/.The core harness validator is located at:
opencode/scripts/check-harness.mjs
After global installation, you can also run it from the installed OpenCode configuration directory:
node scripts/check-harness.mjs
.
├── .github/
│ ├── ISSUE_TEMPLATE/
│ ├── workflows/
│ ├── CODEOWNERS
│ └── PULL_REQUEST_TEMPLATE.md
├── docker/
│ └── open-design/
├── docs/
│ ├── releases/
│ ├── agents.md
│ ├── commands.md
│ ├── configuration.md
│ ├── docker-open-design.md
│ ├── impeccable.md
│ ├── installation.md
│ ├── models.md
│ ├── open-design.md
│ ├── quickstart.md
│ ├── security.md
│ ├── superpowers.md
│ ├── synology.md
│ ├── troubleshooting.md
│ └── workflows.md
├── opencode/
│ ├── agents/
│ ├── commands/
│ ├── docs/ai/
│ ├── plugins/
│ ├── references/
│ ├── scripts/
│ ├── skills/
│ ├── tools/
│ ├── AGENTS.md
│ ├── opencode.json
│ └── tui.json
├── scripts/
│ ├── check.sh
│ ├── install-smoke.sh
│ ├── manage-installation.mjs
│ └── manage-installation.test.mjs
├── doctor.sh
├── install.sh
├── rollback.sh
├── uninstall.sh
├── upgrade.sh
└── env.example
The shipped OpenCode configuration contains:
| Path | Purpose |
|---|---|
AGENTS.md | Global behavior rules and agent index |
opencode.json | Models, permissions, plugins, and default agent |
tui.json | TUI plugin registration |
agents/ | Specialized agent prompts |
commands/ | Slash-command workflows |
skills/ | Local process skills |
tools/ | Custom TypeScript tools |
plugins/ | Bundled OpenCode/TUI plugins |
references/ | Reusable checklists referenced by skills |
docs/ai/harness/ | Agent, command, evidence, and validation contracts |
docs/ai/evolution/ | Harness-evolution benchmark and evidence records |
scripts/check-harness.mjs | Mechanical harness validation |
The default OpenCode permissions are conservative:
Security recommendations:
.env, authentication files, sessions, logs, or provider credentials.PRODUCT.md or DESIGN.md files unless intended.OPEN_DESIGN_URL is not setSet the base URL only:
export OPEN_DESIGN_URL="http://192.168.1.50:7456"
Do not use a project-specific path.
/api/health failsCheck that Open Design is running and reachable from the machine or container where OpenCode runs.
Run:
opencode auth login
Also verify that opencode is available on PATH.
Restart OpenCode and verify that the Superpowers plugin entry is present in opencode.json.
Verify:
tui.json contains the bundled plugin entry.npm ci --ignore-scripts was run in the OpenCode config directory while
its shipped manifests were intact (or preserved manifests were reviewed and
merged before selecting another install command).Verify:
OPEN_DESIGN_URL.opencode/tools/open_design.ts.crypto.randomUUID fails over HTTP on a LAN URLUse HTTPS, or apply the optional upstream frontend patch described in the documentation.
Detailed guides are available in docs/:
^22.9.0 || ^24.0.0.>=1.14.41 <2.0.0 is supported through tested boundary versions.See the complete compatibility matrix for status definitions, exact pins, evidence, and scope.
Contributions are welcome.
Good contributions include:
Before opening a pull request:
npm run check
Use npm run check:release for release readiness.
If Docker files changed:
docker compose -f docker/open-design/docker-compose.yml config
Please avoid committing credentials, authentication files, sessions, logs, private product documents, or machine-specific paths.
See CONTRIBUTING.md for details.
Licensed under the Apache License 2.0.
See NOTICE.md for attribution notices.
This repository is not affiliated with OpenCode, Open Design, Impeccable, or Superpowers.
FAQs
Open-source multi-agent orchestration harness for OpenCode with specialized agents, durable workflows, review gates, and reproducible software-engineering processes.
The npm package opencode-agent-orchestration-kit receives a total of 0 weekly downloads. As such, opencode-agent-orchestration-kit popularity was classified as not popular.
We found that opencode-agent-orchestration-kit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.

Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.

Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.

Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.