opencode-starterkit

English

Quick start

Prerequisites: Node >= 20. Bun >= 1.1 is auto-installed by the installer if missing (the memory plugin runs under Bun — OpenCode executes plugins via Bun, which provides bun:sqlite but lacks node:sqlite). Pass --skip-bun to opt out.

1. Set up your machine (once):

npx opencode-starterkit

Installs the shared baseline (agents, skills, plugins, commands, tools) into ~/.config/opencode/. The installer auto-installs three integrations by default — Bun (memory runtime), Codebase-Memory (code intelligence), and WebClaw (URL extraction) — plus RTK (command compression). Use --skip-<name> to opt out of any, or --require-<name> to fail the install if it cannot be enabled.

2. Set up a project (from inside OpenCode — no terminal):

Open any project in OpenCode and type in chat:

/init

The agent does everything for you:

1. Installs the .opencode/ overlay (project memory, AGENTS context, MCP config)
2. Detects your tech stack and validates build/test/lint commands
3. Writes AGENTS.md so OpenCode automatically loads project context on every session

Re-run /init any time to refresh — existing memory files and memory DB are preserved, not overwritten. The machine-level beads CLI (br) is installed during global bootstrap; project .beads/ workspace initialization is optional and /init skips it by default unless you ask for task tracking.

There is no local install command to run. After global bootstrap, open a project in OpenCode and run /init; the agent performs project setup safely from the slash-command runbook.

Integrations installed by default

During the global install, the installer resolves four integrations. Each auto-installs its binary if missing, unless you opt out:

| Integration | Flag | What it does | |-------------|------|--------------| | Bun | --with-bun / --skip-bun / --require-bun | Memory plugin runtime (bun:sqlite). Auto-installed via official installer (PowerShell on Windows, bash on POSIX) with npm i -g bun fallback. | | Codebase-Memory | --with-codebase-memory / --skip-codebase-memory / --require-codebase-memory | Code intelligence MCP: call graphs, Cypher queries, dead-code detection, architecture overview, 158 languages. Auto-downloads the release binary from DeusData/codebase-memory-mcp. Replaced the retired CodeGraph integration. | | WebClaw | --with-webclaw / --skip-webclaw / --require-webclaw | MCP server for URL extraction / browser-agent tools. Auto-downloads the binary from 0xMassi/webclaw releases. | | RTK | --with-rtk / --skip-rtk / --require-rtk | Command-output compression. Auto-installs from rtk-ai/rtk upstream. |

When enabled, Codebase-Memory's MCP server (codebase-memory-mcp) is registered in opencode.json. /init, /verify, and /ship use it for fast local code intelligence. Users do not need to run a separate enable command per project.

What this package actually installs

opencode-starterkit is a bootstrap package for OpenCode.

It installs OpenCode in two layers:

1. Global baseline — installed once into your real OpenCode global surface
2. Project overlay — installed into each repo you want to work on

This package exists so you do not need to copy a huge .opencode/ directory into every repository.

Global install: what it adds and why

Run:

npx opencode-starterkit

This command installs the starterkit package source into:

• ~/.local/share/opencode/starterkit/

Then it syncs the active OpenCode runtime into:

• ~/.config/opencode/agents/
• ~/.config/opencode/skills/
• ~/.config/opencode/plugin/
• ~/.config/opencode/command/
• ~/.config/opencode/tool/
• ~/.config/opencode/opencode.json

Operational backups/manifests are stored under:

• ~/.local/state/opencode/

What the global install actually puts into OpenCode

1) Shared agents

Installed into ~/.config/opencode/agents/.

Current baseline agents (defined in baseline/opencode.json):

• build — primary development agent with full codebase access
• review — code review, debugging, and security audit specialist
• plan — architecture and multi-phase execution planning
• explore — read-only file and code search
• general — general-purpose subagent for small, well-defined tasks
• scout — external research specialist for library docs and patterns
• vision — read-only visual analysis (UI/UX, accessibility, design-system)
• painter — image generation and editing (uses openai/gpt-image-1)
• compaction — context condensation

Purpose: provide reusable agent roles and default model behavior across repositories.

2) Shared commands

Installed into ~/.config/opencode/command/.

Current baseline commands include:

• init, init-user, init-context — project / user / context setup
• plan, start, ship, verify — planning and shipping workflow
• research, review-codebase, handoff, resume, status — research and session continuity
• ui-review, ui-slop-check — UI/UX review and anti-slop audit (use the vision agent)
• pr, design, create — PR drafting, design, and scaffolding
• audit, compound, curate, explore, fix, gc, health, iterate, lfg — additional workflows

Purpose: give every repo the same workflow/runbook command surface instead of re-copying command markdown into each project.

3) Shared plugins

Installed into ~/.config/opencode/plugin/ and activated through global config resolution.

Current baseline plugins:

• memory.ts → project memory runtime and prompt injection pipeline (runs under Bun / bun:sqlite)
• sessions.ts → session search/read tooling
• session-summary.ts → session summarization
• copilot-auth.ts → provider/auth integration helpers
• skill-mcp.ts → skill-scoped MCP bridge
• codesearch.ts → semantic code search
• srcwalk.ts → structural code walk / read
• rtk.ts → RTK command-output compression
• guard.ts → safety guardrails
• prompt-leverage.ts → prompt augmentation

Purpose: extend OpenCode globally with memory, session, search, auth, and MCP capabilities.

4) Shared skills

Installed into ~/.config/opencode/skills/.

The baseline ships 130+ skills grouped into families such as:

• planning & execution: writing-plans, executing-plans, planning-and-task-breakdown, development-lifecycle, incremental-implementation, index-knowledge
• verification & quality: verification-before-completion, verification-gates, test-driven-development, testing-anti-patterns, requesting-code-review, receiving-code-review, code-review-and-quality, agent-code-quality-gate
• debugging & investigation: systematic-debugging, root-cause-tracing, deep-research, debugging-and-error-recovery, source-code-research, code-navigation, code-search-patterns
• context & memory: context-engineering, context-management, context-condensation, context-initialization, memory-system, memory-grounding, compaction, codebase-memory
• UI / frontend / design: frontend-design, mockup-to-code, design-system-audit, visual-analysis, ui-ux-pro-max, ui-ux-research, ux-quality-gates, accessibility-audit, high-end-visual-design, web-design-guidelines, figma, figma-go, v0, stitch
• orchestration & coordination: beads, beads-bridge, swarm-coordination, subagent-driven-development, dispatching-parallel-agents, agent-teams, agent-evals, agent-browser
• platform / infra / provider skills: cloudflare, supabase, supabase-postgres-best-practices, jira, playwright, playwriter, tilth-cli, resend, polar, portless, vercel-deploy-claimable
• security: security-and-hardening, security-threat-model, defense-in-depth
• git & shipping: git-workflow-and-versioning, shipping-and-launch, finishing-a-development-branch, using-git-worktrees, gh-address-comments, gh-fix-ci
• writing & skills: skill-creator, skill-installer, writing-skills, using-skills, sharing-skills

Purpose: give every repo the same shared operating skills without duplicating them per-project.

5) Shared tools

Installed into ~/.config/opencode/tool/.

Current baseline tools:

• context7.ts — resolve and query library documentation
• grepsearch.ts — code pattern search

Purpose: bundle shared helper tools used by the baseline workflows.

6) Global config merge

Merged additively into ~/.config/opencode/opencode.json.

This merge is intended to add:

• agent definitions and model defaults
• plugin entries
• MCP entries
• other baseline config blocks

Purpose: extend the user's global OpenCode config without blindly overwriting existing config.

Why this matters

After the global install, OpenCode should already know about the shared baseline:

• the installed package source lives at ~/.local/share/opencode/starterkit/
• active runtime config remains under ~/.config/opencode/
• the reusable CLI shim is installed into ~/.local/bin/:
  • opencode-starterkit
• skills become available globally
• shared plugins are active
• default agent/model behavior is available without re-copying files into every repo

Project install: what it creates and why

Project setup is normally started from inside OpenCode:

/init

The shared /init command is an agent runbook that creates a thin .opencode/ overlay for the current repo. Local install commands were removed for safety; normal users should use /init.

Project files created

.opencode/
  opencode.json
  memory/
    README.md
    session-context.md
    _templates/
      project.md
      prd.md
      ...
    research/
      benchmark-framework.md
      ...
    project/
      project.md
      state.md
      roadmap.md
      tech-stack.md
      user.md
      gotchas.md
  memory.db

Project setup is performed by the shared /init runbook. There is no local install command. When Codebase-Memory integration is enabled globally, /init indexes the project so call-graph and architecture queries work immediately. If Codebase-Memory is disabled or unavailable, /init skips that step without blocking project setup.

What each project-local piece does

• .opencode/opencode.json

  • thin repo-specific config
  • points OpenCode at the repo's local project memory files
  • may carry project-specific model/MCP overrides later

• .opencode/memory/project/*.md

  • human-readable project context that gets injected via instructions[]
  • typical roles:
    • project.md → project purpose and goals
    • state.md → current working state
    • roadmap.md → milestones / phases
    • tech-stack.md → stack and technical constraints
    • user.md → project/user preferences
    • gotchas.md → repo-specific footguns and warnings

• .opencode/memory.db

  • per-project runtime memory database (created via Bun / bun:sqlite)
  • stores operational memory for the OpenCode memory plugin
  • this is intentionally project-local, not global
  • examples of stored data include temporal messages, distillations, observations, and pipeline state

Why this matters

Each project keeps its own:

• project context
• runtime memory
• repo-specific behavior

while still reusing the heavy shared baseline from the global layer.

Architecture summary

• Global baseline = shared OpenCode operating system
• Project overlay = thin repo-specific wrapper
• Project memory DB = local runtime state per repo (Bun / bun:sqlite)

That means:

• shared skills/plugins/agents/commands/tools are installed once
• each repo still has its own memory and context

Commands

Global bootstrap

npx opencode-starterkit

Project bootstrap

Normal user entrypoint inside OpenCode:

/init

Local install commands were removed for safety; /init is the only project setup entrypoint.

What is bundled in this repo

This package currently vendors a baseline under:

baseline/
  agent/
  command/
  plugin/
  skill/
  tool/
  opencode.json
  ...

It also ships:

• CLI entrypoints in bin/
• installer logic in src/
• migration/audit notes in docs/reports/

Who should use this

Use this if you want:

• one shared OpenCode baseline across many repositories
• smaller .opencode/ folders in each repo
• project-local memory and context preserved per repo

Tiếng Việt

Package này thực sự cài cái gì

opencode-starterkit là package bootstrap cho OpenCode theo mô hình 2 tầng:

1. Tầng global — cài một lần vào đúng bề mặt global của OpenCode
2. Tầng project — cài lớp mỏng cho từng repo cụ thể

Mục tiêu là không phải copy nguyên một thư mục .opencode/ nặng vào mọi project nữa.

Cài đặt nhanh

Yêu cầu: Node >= 20. Bun >= 1.1 được tự cài bởi installer nếu thiếu (memory plugin chạy trên Bun — OpenCode thực thi plugin qua Bun, cung cấp bun:sqlite nhưng không có node:sqlite). Dùng --skip-bun để bỏ qua.

1. Cài máy (một lần):

npx opencode-starterkit

Cài baseline dùng chung (agents, skills, plugins, commands, tools) vào ~/.config/opencode/. Installer tự cài Bun (memory runtime), Codebase-Memory (code intelligence), WebClaw (URL extraction), và RTK (command compression) theo mặc định. Dùng --skip-<tên> để bỏ qua, hoặc --require-<tên> để fail install nếu không bật được.

2. Cài project (từ trong OpenCode — không cần terminal):

Mở project trong OpenCode rồi gõ:

/init

Agent tự làm hết:

1. Cài .opencode/ overlay (project memory, AGENTS context, MCP config)
2. Detect tech stack và kiểm tra build/test/lint
3. Viết AGENTS.md để OpenCode tự load project context mỗi session

Tích hợp được cài mặc định

Khi cài global, installer xử lý 4 tích hợp. Mỗi tích hợp tự cài binary nếu thiếu, trừ khi opt out:

| Tích hợp | Flag | Tác dụng | |----------|------|----------| | Bun | --with-bun / --skip-bun / --require-bun | Runtime cho memory plugin (bun:sqlite). Tự cài qua official installer (PowerShell trên Windows, bash trên POSIX), fallback npm i -g bun. | | Codebase-Memory | --with-codebase-memory / --skip-codebase-memory / --require-codebase-memory | Code intelligence MCP: call graph, Cypher, dead-code, architecture overview, 158 ngôn ngữ. Tự download binary từ DeusData/codebase-memory-mcp. Thay thế CodeGraph đã retire. | | WebClaw | --with-webclaw / --skip-webclaw / --require-webclaw | MCP server cho URL extraction / browser-agent. Tự download binary từ 0xMassi/webclaw. | | RTK | --with-rtk / --skip-rtk / --require-rtk | Nén output command. Tự cài từ rtk-ai/rtk. |

Khi bật, MCP server codebase-memory-mcp được đăng ký trong opencode.json. /init, /verify, /ship dùng Codebase-Memory để agent hiểu repo nhanh. Không cần chạy lệnh enable riêng cho từng project.

Global install: nó thêm những gì và để làm gì

Chạy:

npx opencode-starterkit

Lệnh này sync baseline dùng chung vào:

• ~/.config/opencode/agents/
• ~/.config/opencode/skills/
• ~/.config/opencode/plugin/
• ~/.config/opencode/command/
• ~/.config/opencode/tool/
• ~/.config/opencode/opencode.json

Những gì tầng global thực sự cài vào OpenCode

1) Agents dùng chung

Cài vào ~/.config/opencode/agents/.

Baseline hiện có các agent (định nghĩa trong baseline/opencode.json):

• build — agent phát triển chính, truy cập full codebase
• review — code review, debug, security audit
• plan — kiến trúc và thực thi multi-phase
• explore — tìm file/code chỉ-đọc
• general — subagent cho task nhỏ, rõ ràng
• scout — research external (docs thư viện, pattern)
• vision — phân tích visual (UI/UX, accessibility, design-system) chỉ-đọc
• painter — sinh/chỉnh sửa ảnh (dùng openai/gpt-image-1)
• compaction — cô đặc context

Tác dụng: cung cấp role/model mặc định dùng chung cho nhiều repo.

2) Commands dùng chung

Cài vào ~/.config/opencode/command/.

Baseline hiện có các command:

• init, init-user, init-context — setup project / user / context
• plan, start, ship, verify — workflow lập kế hoạch và ship
• research, review-codebase, handoff, resume, status — research và liên tục session
• ui-review, ui-slop-check — review UI/UX và audit anti-slop (dùng agent vision)
• pr, design, create — draft PR, design, scaffolding
• audit, compound, curate, explore, fix, gc, health, iterate, lfg — workflow bổ sung

Tác dụng: đưa các command workflow/runbook dùng chung lên global để repo nào cũng gọi được.

3) Plugins dùng chung

Cài vào ~/.config/opencode/plugin/ và được runtime activate qua global config resolution.

Baseline hiện có các plugin:

• memory.ts → memory runtime và prompt injection (chạy trên Bun / bun:sqlite)
• sessions.ts → đọc/tìm session
• session-summary.ts → tóm tắt session
• copilot-auth.ts → auth/provider integration
• skill-mcp.ts → MCP bridge cho skill
• codesearch.ts → semantic code search
• srcwalk.ts → structural code walk / read
• rtk.ts → nén output command (RTK)
• guard.ts → safety guardrails
• prompt-leverage.ts → prompt augmentation

Tác dụng: mở rộng capability chung cho OpenCode ở tầng global.

4) Skills dùng chung

Cài vào ~/.config/opencode/skills/.

Baseline ship 130+ skills theo các nhóm:

• planning & execution: writing-plans, executing-plans, planning-and-task-breakdown, development-lifecycle, incremental-implementation, index-knowledge
• verification & quality: verification-before-completion, verification-gates, test-driven-development, testing-anti-patterns, requesting-code-review, receiving-code-review, code-review-and-quality, agent-code-quality-gate
• debugging & investigation: systematic-debugging, root-cause-tracing, deep-research, debugging-and-error-recovery, source-code-research, code-navigation, code-search-patterns
• context & memory: context-engineering, context-management, context-condensation, context-initialization, memory-system, memory-grounding, compaction, codebase-memory
• UI / frontend / design: frontend-design, mockup-to-code, design-system-audit, visual-analysis, ui-ux-pro-max, ui-ux-research, ux-quality-gates, accessibility-audit, high-end-visual-design, web-design-guidelines, figma, figma-go, v0, stitch
• orchestration & coordination: beads, beads-bridge, swarm-coordination, subagent-driven-development, dispatching-parallel-agents, agent-teams, agent-evals, agent-browser
• platform / provider skills: cloudflare, supabase, supabase-postgres-best-practices, jira, playwright, playwriter, tilth-cli, resend, polar, portless, vercel-deploy-claimable
• security: security-and-hardening, security-threat-model, defense-in-depth
• git & shipping: git-workflow-and-versioning, shipping-and-launch, finishing-a-development-branch, using-git-worktrees, gh-address-comments, gh-fix-ci
• writing & skills: skill-creator, skill-installer, writing-skills, using-skills, sharing-skills

Tác dụng: mọi repo dùng chung cùng một bộ operating skills, không phải copy vào từng project.

5) Tools dùng chung

Cài vào ~/.config/opencode/tool/.

Baseline hiện có:

• context7.ts — resolve và query docs thư viện
• grepsearch.ts — search code pattern

Tác dụng: helper tool chung cho các workflow/search/context surface.

6) Global config merge

Merge-additive vào ~/.config/opencode/opencode.json.

Phần merge này nhằm bổ sung:

• agent definitions và model defaults
• plugin entries
• MCP entries
• config block nền tảng khác

Tác dụng: thêm baseline vào global config hiện có mà không đè bừa config người dùng.

Tác dụng của tầng global

Sau khi cài global, OpenCode sẽ dùng được baseline chung:

• skill xuất hiện ở global
• plugin chung được activate
• agent/model baseline có sẵn cho nhiều repo khác nhau

Local project install: nó tạo gì và để làm gì

Trong OpenCode, mở repo cần dùng rồi chạy:

/init

Command /init là runbook cho agent tự tạo .opencode/ mỏng cho repo hiện tại. Local install command đã bị xoá để an toàn; workflow duy nhất cho người dùng là /init.

Những file được tạo

.opencode/
  opencode.json
  memory/
    README.md
    session-context.md
    _templates/
      project.md
      prd.md
      ...
    research/
      benchmark-framework.md
      ...
    project/
      project.md
      state.md
      roadmap.md
      tech-stack.md
      user.md
      gotchas.md
  memory.db

Project setup được thực hiện bởi runbook /init. Không còn local install command. Nếu Codebase-Memory đã được bật ở global, /init index project để call-graph và architecture query chạy được ngay. Nếu Codebase-Memory bị tắt hoặc không có sẵn, /init skip phần đó và vẫn tiếp tục setup project. Beads CLI (br) đã được cài ở tầng global; .beads/ workspace trong repo chỉ tạo khi cần task tracking, không tạo mặc định.

Từng phần có tác dụng gì

• .opencode/opencode.json

  • config mỏng riêng cho repo
  • trỏ OpenCode vào project memory của repo này
  • sau này có thể chứa override riêng của project

• .opencode/memory/project/*.md

  • là project context file để inject vào prompt
  • ví dụ:
    • project.md → project này làm gì
    • state.md → trạng thái hiện tại
    • roadmap.md → roadmap/phase
    • tech-stack.md → stack và constraint kỹ thuật
    • user.md → preference/quy ước riêng
    • gotchas.md → footguns của repo

• .opencode/memory.db

  • là memory runtime riêng của từng project (tạo qua Bun / bun:sqlite)
  • OpenCode memory plugin dùng DB này để lưu:
    • temporal messages
    • distillations
    • observations
    • pipeline state
  • phần này cố ý để theo từng repo, không global hóa

Tác dụng của tầng project

Mỗi repo giữ được:

• context riêng
• memory runtime riêng
• override riêng nếu cần

trong khi vẫn dùng lại baseline nặng từ tầng global.

Tóm tắt kiến trúc

• Global baseline = OpenCode operating system dùng chung
• Project overlay = lớp mỏng riêng từng repo
• Project memory DB = runtime memory riêng theo repo (Bun / bun:sqlite)

Tức là:

• phần nặng cài một lần
• phần riêng của project vẫn tách riêng và giữ đúng ranh giới

Lệnh hiện tại

Cài tầng global

npx opencode-starterkit

Cài tầng project

Trong OpenCode:

/init

Local install command đã bị xoá để tránh người dùng tự cài sai. /init là entrypoint project duy nhất.

Repo này hiện chứa gì

Repo package đang vendor baseline tại:

baseline/
  agent/
  command/
  plugin/
  skill/
  tool/
  opencode.json
  ...

Ngoài ra còn có:

• CLI trong bin/
• installer logic trong src/
• tài liệu audit/migration trong docs/reports/