Zenox supercharges OpenCode with specialized AI agents that handle different aspects of development. Instead of one agent doing everything, you get a team of experts — each optimized for their domain.

Features

• 5 Specialized Agents — Explorer, Librarian, Oracle, UI Planner, Inspector
• Verification Loop — Inspector runs your real checks and reports PASS/FAIL ground truth, not vibes
• Bundled Skills — Auto-installs frontend-design & grill-me, auto-updated with Zenox
• Hardened Background Tasks — Parallel agents with concurrency limits, a per-task timeout, and a background_list recovery tool
• Thinking Mode Variants — Configure thinking levels (high, xhigh, max) per agent
• Keyword Triggers — ultrawork, deep research, explore codebase, review, blueprint
• Session History — Query past sessions to learn from previous work
• Code Intelligence — Search symbols via LSP
• Project Guidelines Auto-Update — Automatically keeps AGENTS.md and CLAUDE.md up-to-date
• Todo Continuation — Auto-reminds when tasks are incomplete (and stays quiet while background agents are working)
• Auto-Updates — Plugin and bundled skills update automatically; toast on new version

Why Zenox?

Most AI coding assistants use a single model for everything. Zenox takes a different approach:

• Explorer finds code fast — optimized for codebase search with a lightweight model
• Librarian digs deep into docs — researches libraries, finds GitHub examples, citations included
• Oracle thinks strategically — architecture decisions, debugging, technical trade-offs
• UI Planner designs beautifully — CSS, animations, interfaces that don't look AI-generated
• Inspector proves it — actually runs your tests/build/lint and reports PASS or FAIL, so "done" means something

The main agent automatically delegates to specialists when needed. You don't have to manage them.

Quick Start

bunx zenox install

That's it. Restart OpenCode and the agents are ready.

Agents

| Agent | What it does | Default Model | |-------|-------------|---------------| | Explorer | Codebase grep, file discovery, pattern matching | claude-haiku-4-5 | | Librarian | Library research, docs lookup, GitHub examples | claude-sonnet-4-6 | | Oracle | Architecture decisions, debugging strategy, code review | gpt-6-astra-fast (variant medium) | | UI Planner | Frontend design, CSS, animations, visual polish | claude-opus-4-8 | | Inspector | Runs tests/build/lint, reports PASS/FAIL/PARTIAL/BLOCKED ground truth | claude-sonnet-5 |

All five agents are read-only except UI Planner (which writes/edits code) and Inspector (which can run bash to execute checks — but still cannot write or edit). Deny rules are declared explicitly per agent rather than relying on omission, since OpenCode's tool config is default-allow.

How delegation works

You don't need to call agents directly. The main agent (Build/Plan) automatically delegates:

You: "Where's the authentication logic?"
→ Explorer searches the codebase

You: "How does React Query handle caching?"
→ Librarian fetches official docs + real examples

You: "Should I use Redux or Zustand here?"
→ Oracle analyzes trade-offs for your codebase

You: "Make this dashboard look better"
→ UI Planner redesigns with proper aesthetics

You: "Add rate limiting to the API"
→ Build agent implements it, then delegates to Inspector with
  "Done when: bun test passes" — Inspector runs it and reports PASS/FAIL

Verification Loop

Implementing something isn't the same as proving it works. Inspector closes that gap:

1. After a non-trivial change, the main agent delegates to Inspector with an explicit Done when: line — the exact check command(s) that prove the work (tests, typecheck, lint, build).
2. Inspector runs it for real via bash — it never edits, fixes, or refactors. It only observes and reports.
3. It returns a structured verdict: PASS, PARTIAL (the check passed but doesn't cover the full Done-when), FAIL, or BLOCKED (can't even run the check — missing deps, broken env).
4. On FAIL, it also emits a stable failure signature — deterministic across re-runs of the same failure, excluding timestamps/paths/ports. If a fix attempt produces the same signature again, that's a sign of no progress, and the main agent escalates to Oracle instead of retrying blindly.

Build agent: implements a feature
  → task(subagent_type: "inspector", prompt: "Done when: bun test && bun run typecheck")
  → Inspector runs both, returns:
      status: FAIL
      signature: "auth.test.ts:42:TypeError-cannot-read-token"
  → Build agent fixes the reported failure, re-verifies
  → Same signature again? → escalate to Oracle instead of retrying the same way
  → PASS → done, reported to you

Inspector's tools are strictly read + bash — it cannot write or edit files, so a bad verdict can never turn into a bad fix by the same agent that would be grading itself.

Keyword Triggers

Include these magic words in your prompt to unlock special modes:

| Keyword | What it does | |---------|--------------| | ultrawork or ulw | Maximum multi-agent coordination — fires parallel background agents, sets max precision | | deep research | Comprehensive exploration — fires 3-4 background agents (explorer + librarian) | | explore codebase | Codebase mapping — multiple explorers search in parallel | | review / self-review / code review | Fires exactly one Oracle task with the actual git diff — surfaces critical issues, not nitpicks | | blueprint | Locks a plan before any code: frame the problem, sketch the architecture, write an explicit Done when: line — which Inspector later verifies against |

Examples

You: "ultrawork - add authentication to this app"
→ ⚡ Ultrawork Mode activated
→ Fires explorer + librarian in parallel
→ Maximum precision engaged

You: "deep research how this project handles errors"
→ 🔬 Deep Research Mode activated
→ Fires multiple explorers + librarians
→ Waits for comprehensive results before proceeding

You: "explore codebase for payment logic"
→ 🔍 Explore Mode activated
→ Multiple explorers search patterns, implementations, tests

You: "blueprint a rate limiter for the API"
→ 📐 Blueprint Mode activated
→ Frames the problem, sketches the architecture, locks a "Done when:" line
→ Only then starts implementing — Inspector verifies against that line at the end

You'll see a toast notification when these modes activate.

grill me / "question me" / "interview me" also loads the bundled grill-me skill to stress-test a plan — this one is recognized by the agent from intent, not a hard-coded regex, so phrasing can vary.

Skills

Zenox bundles OpenCode Agent Skills — focused expert workflows the agent loads on demand via the native skill tool.

| Skill | What it does | |-------|--------------| | frontend-design | Anthropic's official design philosophy for distinctive, production-grade UI that avoids generic "AI slop" aesthetics. Used by UI Planner. | | grill-me | Stress-tests a plan/design by interviewing you relentlessly, one decision at a time. |

How skills are installed — fully automatic

You never need a manual step to get skills:

• On zenox install — skills are copied to ~/.config/opencode/skills/.
• On every startup — when Zenox auto-updates (or any time the plugin loads), it re-syncs the bundled skills so they always match the installed Zenox version. No zenox install re-run needed.

OpenCode auto-discovers SKILL.md files in that directory and exposes them to agents. The agent loads one with skill({ name: "frontend-design" }).

Your own skills are never touched

Zenox only manages skill folders it created itself (tracked via a .zenox.json manifest):

• A skill you installed yourself is never modified or removed.
• If you already have a skill named frontend-design or grill-me, Zenox leaves it alone — it will not override it.
• If you edit a Zenox-managed skill, your edits are preserved (Zenox detects the change and skips it).

Manage skills

bunx zenox skills          # Install/update bundled skills
bunx zenox skills list     # List bundled skills
bunx zenox skills update   # Same as install (re-sync)

Disable bundled skills entirely in zenox.json (see Configuration).

Background Tasks

Need comprehensive research? Fire multiple agents in parallel:

background_task(agent="explorer", description="Find auth code", prompt="...")
background_task(agent="librarian", description="JWT best practices", prompt="...")

// Both run simultaneously while you keep working
// You're notified when all tasks complete

| Tool | What it does | |------|--------------| | background_task | Launch a background agent | | background_output | Retrieve a completed task's result | | background_cancel | Cancel a running task (if it was the last one, you also get the "all complete" summary right away) | | background_list | List this session's tasks and their status — use it if you lose track of a task ID or miss a notification |

Hung tasks don't hang forever. Each task has a wall-clock timeout (default 30 minutes, configurable via background.timeout_minutes) — if a background session never goes idle, it's aborted automatically and reported as failed, freeing its concurrency slot.

Notifications are precise. Each finished task is only ever included in one "all complete" summary — no duplicate messages if the notification path fires more than once for the same session.

Toast Notifications

Zenox shows toast notifications for background task events:

• ⚡ Task Launched — Shows task description and agent
• ✅ Task Completed — Shows duration and remaining count
• 🎉 All Complete — Shows summary of all finished tasks
• ❌ Task Failed — Shows error message (including timeouts)

Session History

Query past sessions to learn from previous work:

| Tool | What it does | |------|--------------| | session_list | List recent sessions to find relevant past work | | session_search | Search messages across sessions for how something was done |

You: "How did we implement auth last time?"
→ session_search({ query: "authentication" })
→ Finds excerpts from past sessions where auth was discussed

Code Intelligence

Search for symbols via LSP (Language Server Protocol):

| Tool | What it does | |------|--------------| | find_symbols | Search for functions, classes, variables by name | | lsp_status | Check which language servers are running |

You: "Find where handleLogin is defined"
→ find_symbols({ query: "handleLogin" })
→ Returns: Function in src/auth/handlers.ts, line 42

Todo Continuation

Zenox automatically reminds you to continue working when:

• You have incomplete tasks in your todo list
• The session goes idle
• There's been enough time since the last reminder (10 second cooldown)

This keeps you on track without manual intervention. The agent will be prompted to continue until all todos are complete or blocked.

Project Guidelines Auto-Update

Zenox automatically keeps your AGENTS.md and CLAUDE.md files up-to-date with important decisions, patterns, and conventions.

The Problem

Developers forget to update documentation. Important decisions get lost. Team members repeat the same questions. Next session, the agent has no context.

The Solution

Zenox detects important decisions and automatically documents them:

You: "In this project, always use Zustand for state management"
→ Agent checks AGENTS.md — not documented yet
→ Agent saves: "- State Management: Use Zustand, not Redux"
→ Future sessions automatically know this

What Gets Documented

| Trigger | Example | |---------|---------| | User decision | "Always use Tailwind", "We use this API pattern" | | Architecture choice | Agent decides between approaches after analysis | | Reusable code | Agent creates a utility worth reusing | | Convention discovered | Agent notices consistent patterns in codebase |

How It Works

1. Agent recognizes something important
2. Reads AGENTS.md / CLAUDE.md to check if already documented
3. If not there → calls save_project_guideline to add it
4. Both files get updated (or AGENTS.md created if neither exists)

Zero manual work — your project documentation stays current automatically.

Configuration

Custom Models

During installation, choose "Customize models" to pick your own. Or run later:

bunx zenox config

Config saves to ~/.config/opencode/zenox.json:

{
  "agents": {
    "explorer": { "model": "anthropic/claude-sonnet-4-6" },
    "oracle": { "model": "openai/gpt-6-astra-fast" },
    "inspector": { "model": "anthropic/claude-sonnet-5" }
  }
}

Thinking Mode Variants

Configure thinking/reasoning levels for models that support extended thinking (like Claude, GPT with reasoning, etc.):

{
  "agents": {
    "oracle": { 
      "model": "anthropic/claude-opus-4-5",
      "variant": "high"
    },
    "ui-planner": { 
      "model": "openai/gpt-5.5-codex",
      "variant": "xhigh"
    }
  }
}

Available variants (model-dependent):

• low — Minimal thinking
• medium — Balanced thinking
• high — Extended thinking
• xhigh — Extra high thinking
• max — Maximum reasoning depth

Variants are applied safely — if an agent doesn't exist or the model doesn't support the variant, it gracefully falls back.

Disable Agents, MCPs, or Skills

{
  "disabled_agents": ["ui-planner", "inspector"],
  "disabled_mcps": ["grep_app"],
  "disabled_skills": ["frontend-design", "grill-me"]
}

disabled_agents accepts any of: explorer, librarian, oracle, ui-planner, inspector.

A skill listed in disabled_skills is never installed or synced. If it was previously installed by Zenox, it is left in place (Zenox won't auto-remove your files) — delete the folder manually if you want it gone.

Background Task Limits

Control how many background agents can run at once (guards against runaway fan-out that burns through your usage), and how long one is allowed to run before it's considered stuck:

{
  "background": {
    "max_concurrent": 6,
    "max_per_session": 50,
    "timeout_minutes": 30
  }
}

• max_concurrent — max agents running simultaneously (default 6)
• max_per_session — lifetime cap per session, a circuit breaker for runaway loops (default 50)
• timeout_minutes — minutes before a still-running task is aborted and marked failed (default 30)

When the concurrency/circuit-breaker limit is hit, the next background_task is rejected with a message telling the agent to wait and collect results. When the timeout fires, the task itself is aborted and its slot is freed — use background_list to see the timed-out task if you missed the failure toast.

Included MCP Servers

Zenox auto-loads these tools for agents to use:

| Server | Purpose | |--------|---------| | exa | Web search, docs lookup, URL crawling | | grep_app | Search millions of GitHub repos instantly | | sequential-thinking | Step-by-step reasoning for complex problems |

CLI

bunx zenox install          # Add to opencode.json + configure models + install skills
bunx zenox install --no-tui # Non-interactive (uses defaults)
bunx zenox config           # Reconfigure models anytime
bunx zenox mcp              # Enable/disable MCP servers
bunx zenox skills           # Install/update bundled skills
bunx zenox skills list      # List bundled skills
bunx zenox --help           # Show all commands

Auto-Update

Zenox checks for updates on startup. When a new version drops:

1. You see a toast notification
2. Bun cache is invalidated
3. Restart to get the update

When the new version loads, bundled skills are re-synced automatically — you don't need to run zenox install again to get updated skills.

Pin a version to disable: "[email protected]" in your plugins array.

Credits

• OpenCode — The CLI this extends
• oh-my-opencode — Inspiration for orchestration patterns

License

MIT