agents-opencode

OpenCode Agents

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

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

OpenCode Plugin (Alternative)

Add to your opencode.json:

{ "plugin": ["agents-opencode"] }

Then restart OpenCode or run /reload-plugins.

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	License auditing, IP review, data privacy assessment, regulatory guidance

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.

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