OpenZeus

Your OpenCode setup, explained

OpenZeus is an OpenCode companion agent for understanding and maintaining your actual OpenCode environment.

Ask it why an agent is not loading, where a skill comes from, which configuration wins, whether an old definition should be migrated, or how to design a new OpenCode skill or agent.

@OpenZeus why isn't my reviewer agent loading?
@OpenZeus where did this skill come from?
@OpenZeus audit my OpenCode setup and explain the problems.
@OpenZeus migrate this old agent to the current OpenCode format.
@OpenZeus design a portable skill for this workflow.

OpenZeus uses OpenCode's native configuration, agents, skills, commands and plugins wherever possible. Its value is the layer on top: inspection, diagnosis, migration guidance and higher-level asset design.

What it is for

• Understand the effective setup — global vs project configuration, discovered assets, precedence and eventually provenance/shadowing.
• Diagnose OpenCode problems — invalid definitions, missing assets, configuration drift and compatibility issues.
• Evolve old setups safely — inspect first, plan changes, validate, back up and roll back when needed.
• Design OpenCode assets — especially reusable skills and more complex agent/command setups where a simple scaffold is not enough.
• Prefer native OpenCode behavior — OpenZeus should not duplicate a core feature just because it can.

Installation

OpenZeus 2 is moving to native OpenCode plugin delivery. The plugin owns the focused five-skill core. Until OpenCode allows plugins to add agents, one small bootstrap step installs only agents/OpenZeus.md.

Linux and macOS are supported directly. On Windows, use WSL.

npm install -g openzeus
opencode plugin add openzeus
openzeus install-agent

The current installer resolves the target at runtime. You can override it with OPENCODE_CONFIG_DIR; repository files do not contain user-specific absolute paths.

OpenZeus 2 includes a native OpenCode V2 Promise plugin. It registers the packaged skills/ directory as a native skill source through @opencode-ai/plugin/v2/promise. Current OpenCode V2 cannot add a new agent from a plugin because AgentDraft has no add(); the small agent-file bootstrap therefore remains transitional until upstream exposes that API.

Use OpenZeus

The agent is the primary interface. The CLI is support machinery.

Diagnose

@OpenZeus audit my OpenCode setup.
@OpenZeus why isn't this skill available?
@OpenZeus explain which config applies here.

Current deterministic helpers:

openzeus audit
openzeus audit --json
openzeus inspect --json
openzeus validate --ci

audit is the user-facing diagnostic summary. inspect exposes the raw filesystem evidence used for provenance, precedence and compatibility checks.

Create or improve a skill

@OpenZeus create a reusable skill for our release workflow.
@OpenZeus review this SKILL.md for discovery and portability problems.

OpenZeus keeps dedicated skill-authoring guidance because OpenCode can load skills natively but does not currently provide an equivalent dedicated skill creator workflow.

Work with agents

For a basic agent scaffold, prefer OpenCode's native creator:

opencode agent create

Use OpenZeus when the problem is architectural rather than mechanical:

@OpenZeus design a reviewer agent with safe permissions and two specialist subagents.
@OpenZeus migrate this legacy agent definition without changing its behavior.

Focused skills

OpenZeus now ships only skills that directly help operate or author OpenCode.

Skill	Role
zeus-diagnostics	Runtime/config discovery, precedence and troubleshooting
zeus-migration	Safe OpenCode migration planning
zeus-agents	Advanced agent design and maintenance
zeus-commands	Command design and maintenance
zeus-skills	Skill authoring, discovery and portability

Generic domain packs, pseudo-introspection skills and copied documentation for external plugins are intentionally outside the OpenZeus core.

Current CLI

The CLI is intentionally small:

audit          Summarize actionable findings; --ci fails on warnings
inspect        Inventory filesystem-visible OpenCode sources and precedence
install-agent  Install only the transitional @OpenZeus agent bootstrap
create         Create an agent, skill, or command template
validate       Validate OpenZeus/OpenCode asset structure

OpenZeus no longer ships generic project-management/Git slash commands. Command authoring remains available through @OpenZeus and openzeus create command.

The old generic setup, init-project, recipe, context-init and prompt-capture helpers have been removed from the refocus branch. OpenCode's native /init owns project initialization; OpenZeus stays focused on inspection, diagnosis, migration and OpenCode-specific authoring.

Development

npm test
openzeus validate --ci
npm pack --dry-run

Architecture and campaign state:

• OpenZeus 2 refocus plan
• OpenZeus 2 continuity

Version

Current stable npm release: 1.2.0. This branch prepares 2.0.0.

OpenZeus 2.0.0 is the breaking refocus release: native V2 plugin delivery, five focused skills, runtime inspection/audit, plan-only migration, and a minimal agent bootstrap.

Links

• Repository: https://github.com/Aveer/OpenZeus
• Issues: https://github.com/Aveer/OpenZeus/issues
• OpenCode Docs: https://opencode.ai/docs/
• NPM Package: https://npmjs.com/package/openzeus

OpenCode V2 plugin prototype

The refocus branch exposes the package itself as a V2 plugin:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["openzeus"]
}

The plugin registers the packaged skills/ directory as a native OpenCode skill source. OpenCode then owns normal skill discovery/loading.

Runtime diagnostics remain explicit CLI evidence through openzeus inspect and openzeus audit; the current V2 Promise plugin context does not expose a custom-tool registration surface, so OpenZeus does not claim one.

The plugin does not yet register the @OpenZeus agent itself. Current OpenCode V2 can inspect/update/remove agents from a plugin but cannot add one, so the agent-file bootstrap remains until that upstream limitation changes.

Transitional agent bootstrap

Once the OpenZeus 2 package is published, installation is intended to be:

opencode plugin add openzeus
npx openzeus install-agent

If you already keep the CLI globally:

openzeus install-agent

install-agent never copies skills, commands, plugin code, or private machine state. It copies only agents/OpenZeus.md, refuses to overwrite a different file unless --force is explicit, and supports --backup.

The older openzeus install spelling remains only as a temporary alias to install-agent.

Migration planning

OpenZeus can now turn compatibility findings into an explicit, non-mutating migration plan:

openzeus migrate --plan
openzeus migrate --plan --json

Current plans cover legacy agent permissions/tools/request fields, legacy command subtask, and legacy tui.json(c). Every action is marked automatic: false.

openzeus migrate --apply intentionally refuses to run. Automatic migration will only be added when edits are parser-backed and each supported migration has backup, validation and rollback guarantees.