Skip to content

chore: clean npm tarball, restructure README for sellability, add July metrics #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shahboura merged 2 commits into from
Jul 8, 2026
Merged

chore: clean npm tarball, restructure README for sellability, add July metrics #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
508009a
chore: clean npm tarball, restructure README for sellability, add Jul…
shahboura Jul 8, 2026
c9b9979
Merge branch 'main' into chore/tarball-cleanup-readme-restructure
shahboura Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
254 changes: 109 additions & 145 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,147 +6,135 @@
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://shahboura.github.io/agents-opencode/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Lean OpenCode agent pack for fast setup, safer skill loading, and production-ready workflows.
**9 specialized agents, 23 on-demand skills, production-ready workflows.**
Install once, get 97% context cache hits — sessions start near-instantly and cost ~20× less.

Also available for Claude Code — see [Installation](#installation).

## Why this pack
## Efficiency

- **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.
OpenCode's context caching dramatically reduces token consumption across sessions.
The following metrics are from production usage (May–July 2026) with the
`deepseek-v4-pro` model.

Quick jump: [Agents](#agents) · [Skills Matrix](./docs/skills-matrix.md) · [Commands](#commands) · [Full Docs](https://shahboura.github.io/agents-opencode/)
| Metric | May 2026 | June 2026 | July 2026 | Combined |
|---|---|---|---|---|
| Cache Hit Tokens | 263.3M | 21.9M | 145.0M | 430.2M |
| Cache Miss Tokens | 7.9M | 1.3M | 2.7M | 11.9M |
| Output Tokens | 0.8M | 0.2M | 0.5M | 1.5M |
| Total Requests | 1,407 | 380 | 1,016 | 2,803 |
| **Cache Hit Rate** | **97.1%** | **94.5%** | **98.2%** | **97.3%** |
| Avg Tokens/Request | 193K | 62K | 146K | 158K |

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.

## Quick Start

**Requires:** Node.js

```bash
# 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 .
<details><summary>More install options (filter, update, uninstall, status)</summary>

# Filter language instruction references for a lighter install
```bash
# Filter language 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)
# Uninstall
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:
1. Open the latest backup session folder.
2. Review `backup-manifest.json` for file paths.
3. 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.
**Install:** npm package and installer command: `agents-opencode`. OpenCode CLI runtime command: `opencode`.

Then run:

```bash
opencode
/init
@orchestrator Build a REST API with JWT auth
```
**Uninstall:** targets current project by default; use `--global` or `--all` for
explicit scope. Creates timestamped backups before removal.

## Installation
**Update:** auto-detects installed scopes; use `--all`, `--global`, or
`--project [dir]` for explicit scope.

### npx (Recommended)
**Config:** installer merges only missing global permission defaults into
`opencode.json`. Existing provider/model/instructions settings are preserved.

```bash
npx agents-opencode --global
```
</details>

### Claude Code Plugin
Then run:

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

# Install
/plugin install agents-opencode@shahboura

# Update
/plugin update agents-opencode@shahboura
opencode # start the TUI
/init # initialize a new session
@orchestrator Build a REST API with JWT auth
```

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/](./adapters/claude-code/)
for the plugin manifest and generator script.
The orchestrator plans, delegates to @codebase for implementation,
@review for quality checks, and @docs for documentation — all in one session.

## 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 |
|---|---|
| `@orchestrator` | End-to-end features: plans, delegates to specialists, validates results |
| `@codebase` | Write code across 10+ languages with auto-detected project conventions |
| `@planner` | Architecture reviews, risk assessment, step-by-step implementation plans |
| `@review` | Catch bugs, security holes, and perf issues before they ship |
| `@docs` | READMEs, API docs, ADRs, wiki pages |
| `@blogger` | Blog posts, YouTube scripts, podcast outlines, resumes, LinkedIn profiles |
| `@brutal-critic` | Ruthless content QA against proven frameworks with actionable scores |
| `@em-advisor` | 1-on-1 prep, team strategy, roadmap planning |
| `@legal-advisor` | License auditing, compliance checks, IP review, export controls |

Canonical source for exact allowlists and skill triggers: [Skills Matrix](./docs/skills-matrix.md)

## Skill Loading (OpenCode)
## Commands

- 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.
Type `/command-name` in the TUI to run:

## Skill Scope Policy
| Command | Description |
|---|---|
| `/code-review` | Comprehensive code review |
| `/security-audit` | Security audit |
| `/generate-tests` | Unit test generation |
| `/refactor-plan` | Refactoring plan |
| `/architecture-review` | Architecture review |
| `/architecture-decision` | ADR creation |
| `/api-docs` | Generate API documentation |
| `/create-readme` | Generate README |
| `/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 |

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

## Skill Permissions (Least Privilege)
- **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.

Use `permission.skill` allowlists in agent frontmatter to prevent unrelated skill loads.
## Skill Loading (OpenCode)

Skills load on demand via the `skill` tool — no context cost until you use them.
Use one relevant skill per task/phase; add another only for clear cross-domain work.

Instruction files live in `.opencode/instructions/`, skill packs in `.opencode/skills/<name>/SKILL.md`.
Scope remains core-only; additions pass demand, clear-gap, ownership, and licensing/provenance checks.

<details><summary>Permission configuration (least-privilege patterns)</summary>

Skill permissions (prevent unrelated skill loads):

```yaml
permission:
Expand All @@ -156,11 +144,7 @@ permission:
"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.
Task permissions (control which subagents each agent can invoke):

```yaml
permission:
Expand All @@ -170,63 +154,43 @@ permission:
"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.
Start with `"*": "deny"`, add explicit allows. Rules match in order — last match wins.

## Usage & Efficiency
</details>

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.
## Installation

| 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 |
### npx (Recommended)

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.
```bash
npx agents-opencode --global
```

## Commands
### Claude Code Plugin

Type `/command-name` in the TUI to run:
```bash
# Add marketplace (one-time)
/plugin marketplace add shahboura/agents-opencode-claude

| 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 |
# Install
/plugin install agents-opencode@shahboura

## Agent Evals
# Update
/plugin update agents-opencode@shahboura
```

- `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.
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/](./adapters/claude-code/)
for the plugin manifest and generator script.

## Validation

- Run `npm run doctor` for the complete local validation suite.
- For full check mapping (local commands ↔ CI gates), see **[Compatibility](./docs/compatibility.md)**.
Run `npm run doctor` for the complete local validation suite (agent contracts,
markdown linting, docs links, session state, eval trends, and more).
For full check mapping (local commands ↔ CI gates), see **[Compatibility](./docs/compatibility.md)**.

Agent evals: `npm run eval:agents` runs deterministic contract checks for agent
and command metadata. `npm run eval:agents:json` writes machine-readable output.

## Docs

Expand Down
6 changes: 5 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@
"description": "OpenCode Agents: Intelligent AI assistants for software development. Features 9 specialized agents (including legal-advisor for license auditing and compliance), 14 coding standards, automated code review, documentation generation, OpenCode plugin compatibility, and cross-platform installation. Supports .NET, Python, TypeScript, Flutter, Go, Java, Node.js, React, Ruby, and Rust with plan-first execution and context-aware assistance.",
"files": [
"install.js",
".opencode",
".opencode/agents",
".opencode/commands",
".opencode/instructions",
".opencode/plugins",
".opencode/skills",
"opencode.json",
"scripts/lib"
],
Expand Down
Loading