agents-opencode

OpenCode Agents

Lean OpenCode agent pack for fast setup, safer skill loading, and production-ready workflows.

Also available for Claude Code — see Installation.

Why this pack

• Fast onboarding: install in minutes with npx.
• Clear execution flow: plan, implement, review, and document with purpose-built agents.
• Safer defaults: on-demand skills + deny-by-default skill permissions.
• Operationally ready: built-in validation and release automation.

Quick jump: Agents · Skills Matrix · Commands · Full Docs

Quick Start

Requires: Node.js

# Via npx (recommended)
npx agents-opencode --global

# Alternative (direct npm install)
npm install -g agents-opencode && agents-opencode --global

# Project install (current directory only)
npx agents-opencode --project .

# Filter language instruction references for a lighter install
npx agents-opencode --global --languages python,typescript

# Update existing installation
npx agents-opencode --update

# Force update both global + current project scopes
npx agents-opencode --update --all

# Uninstall current project scope (default)
npx agents-opencode --uninstall

# Uninstall global scope only
npx agents-opencode --uninstall --global

# Uninstall both global + current project scopes
npx agents-opencode --uninstall --all

# Check detected installation scopes
npx agents-opencode --status

Install behavior note:

• npx/npm installs from the published npm package version (deterministic release artifact).
• npm package and installer command: agents-opencode
• OpenCode CLI runtime command: opencode
• --languages filters language instruction reference files; runtime skill loading remains on-demand per agent allowlists.

Uninstall behavior:

• npx agents-opencode --uninstall targets the current project by default.
• Use --global or --all for explicit scope control.
• Uninstall removes installer-managed files via install manifest tracking.
• Project backups: <project>/.opencode/.backups/<timestamp>--<operation>--<scope>/
• Global backups: ~/.config/opencode/.backups/<timestamp>--<operation>--<scope>/
• Backup retention: latest 10 sessions and sessions newer than 30 days.

Restore from backup:

• Open the latest backup session folder.
• Review backup-manifest.json for file paths.
• Copy files back to their original paths.

Update behavior:

• npx agents-opencode --update auto-detects and updates installed scopes (global and/or current project).
• Use --all, --global, or --project [dir] to force explicit update scope.

Configuration behavior:

• Installer merges only missing global permission defaults (external_directory, doom_loop) into opencode.json.
• Existing provider/model/instructions settings are preserved and never overwritten by installer defaults.

Then run:

opencode
/init
@orchestrator Build a REST API with JWT auth

Installation

npx (Recommended)

npx agents-opencode --global

Claude Code Plugin

# Add marketplace (one-time)
/plugin marketplace add shahboura/agents-opencode-claude

# Install
/plugin install agents-opencode@shahboura

# Update
/plugin update agents-opencode@shahboura

Gives Claude Code access to the same 23 on-demand skills. Skills load only when invoked — no context cost until you use them. See adapters/claude-code/ for the plugin manifest and generator script.

Agents

Agent	Best For
@orchestrator	Multi-phase coordination
@planner	Read-only architecture/planning
@codebase	Feature implementation
@review	Security/performance/code quality
@docs	Documentation updates
@em-advisor	EM/leadership guidance
@blogger	Blog/video/podcast drafting
@brutal-critic	Final content quality gate
@legal-advisor	Legal research, jurisdiction-aware compliance, contract review, license auditing, data privacy, IP, export controls

Canonical source for exact allowlists and skill triggers: Skills Matrix

Skill Loading (OpenCode)

• Instruction files live in .opencode/instructions/*.instructions.md as reference material.
• Reusable skill packs live in .opencode/skills/<name>/SKILL.md.
• Skills are the primary runtime mechanism and are loaded on demand via the skill tool.
• Use one relevant skill per task/phase by default; add another only for clear cross-domain work.
• If stack/domain is unclear, ask for clarification before loading.

Skill Scope Policy

• Scope remains core-only skills (no optional skill packs).
• Additions should pass demand, clear-gap, ownership, and licensing/provenance checks.

Skill Permissions (Least Privilege)

Use permission.skill allowlists in agent frontmatter to prevent unrelated skill loads.

permission:
  skill:
    "*": "deny"
    "python": "allow"
    "sql-migrations": "allow"

This keeps skills focused by agent role and reduces accidental context bloat.

Task Permissions (Subagent Hardening)

Use permission.task allowlists to control which subagents each agent can invoke.

permission:
  task:
    "*": "deny"
    "explore": "allow"
    "review": "allow"

Pattern notes:

• Start with "*": "deny", then add explicit allows.
• Keep allowlists narrow by role.
• Rules are matched in order and the last matching rule wins.

Usage & Efficiency

OpenCode's context caching dramatically reduces token consumption across sessions. The following metrics are from production usage (May–June 2026) with the deepseek-v4-pro model.

Metric	May 2026	June 2026	Combined
Cache Hit Tokens	263.3M	21.9M	285.2M
Cache Miss Tokens	7.9M	1.3M	9.2M
Output Tokens	0.8M	0.2M	1.0M
Total Requests	1,407	380	1,787
Cache Hit Rate	97.1%	94.5%	96.9%
Avg Tokens/Request	193K	62K	165K

Key takeaway: persistent context reuse keeps ~97% of input tokens in cache, avoiding costly re-processing across agent sessions. Cache-hit tokens cost ~120× less than cache-miss tokens, translating to substantial efficiency gains for long-running multi-agent workflows.

Commands

Type /command-name in the TUI to run:

Command	Description
/api-docs	Generate API documentation
/code-review	Comprehensive code review
/generate-tests	Unit test generation
/security-audit	Security audit
/refactor-plan	Refactoring plan
/create-readme	Generate README
/architecture-decision	ADR creation
/architecture-review	Architecture review
/blog-post	Blog post creation
/content-review	Content quality scoring
/plan-project	Multi-phase project planning
/execution-loop	Bounded iterative execution workflow
/stop-loop	Stop loop and summarize state
/checkpoint	Phase-boundary checkpoint for human decision
/1-on-1-prep	Meeting preparation

Agent Evals

• npm run eval:agents runs deterministic contract checks for agent and command metadata.
• npm run eval:agents:json writes machine-readable output to evals/reports/latest.json.
• These checks are integrated into doctor and CI validation summary gating.

Validation

• Run npm run doctor for the complete local validation suite.
• For full check mapping (local commands ↔ CI gates), see Compatibility.

Docs

• Getting Started
• Approval Gates
• Compatibility
• Deprecation & Migration Policy
• State Management
• Full Documentation