Skip to content
/

OpenCode

opencode · sst/opencode · ★ 165k · last commit 2026-05-26

Primitive shape 13 total
Commands 8 Skills 2 Subagents 3
00

Summary

OpenCode — Summary

OpenCode (by SST) is a terminal-first AI coding agent with a rich TUI, desktop app, and web interface, featuring a novel .opencode/ configuration directory that ships agents, commands, skills, and plugins. Two built-in agents (build for full-access development, plan for read-only analysis) are switchable with Tab. A general subagent handles complex multi-step tasks and is invocable via @general. The .opencode/command/ directory holds 8 slash-command-style prompt files (commit, changelog, learn, translate, etc.), making it the first framework in this batch where the project ships its own operational commands for managing the codebase itself. OpenCode uses multi-model routing: individual commands can specify a model (e.g., commit command uses opencode/kimi-k2.5), and agents can restrict their model (triage agent uses opencode/gpt-5.4-nano).

OpenCode differs from seed frameworks: unlike superpowers or spec-kit (which layer on top of other agents), OpenCode is the agent runtime itself with an extensible plugin system. Unlike aider (terminal-only, no methodology), OpenCode ships its own .opencode/ configuration as a first-class opinionated structure. The multi-model command routing (per-command model selection) is unique in this corpus.

01

Overview

OpenCode — Overview

Origin

Created by SST (the Serverless Stack team, known for building SST framework for AWS serverless apps). The name "opencode" signals both open-source and the open coding agent space. The repo has accumulated 165,000+ stars rapidly, making it one of the most-starred coding agent projects. The project moved from sst/opencode to anomalyco/opencode during development; the GitHub API returns the anomalyco URL in responses.

Philosophy

OpenCode emphasizes:

  1. Terminal-first: Rich TUI with keyboard navigation, themes, and SSH support
  2. Config-as-code: The .opencode/ directory is a first-class project artifact — not just a CLAUDE.md — with typed JSON schema, agents, commands, skills, and plugins
  3. Multi-surface: Same agent available as terminal app, desktop app (Electron-like), and web interface
  4. Multi-model: Different commands and agents can use different models
  5. Plugin system: Custom extensions via .opencode/plugins/

Key Design Principles

From AGENTS.md:

"ALWAYS USE PARALLEL TOOLS WHEN APPLICABLE." "Prefer automation: execute requested actions without confirmation unless blocked by missing info or safety/irreversibility."

The commit command explicitly calls for understanding WHY (not WHAT):

"prefer to explain WHY something was done from an end user perspective instead of WHAT was done" "do not do generic messages like 'improved agent experience' be very specific about what user facing changes were made"

Desktop App

Available as a native desktop application with .dmg, .exe, .deb, .rpm, .AppImage — unusual for a coding agent. Also available via Homebrew cask (brew install --cask opencode-desktop).

Internationalization

README translated into 22+ languages. This signals the project is targeting a global developer audience.

02

Architecture

OpenCode — Architecture

Distribution

Multiple install paths:

# YOLO install
curl -fsSL https://opencode.ai/install | bash

# Package managers
npm i -g opencode-ai@latest
bun install -g opencode-ai
pnpm add -g opencode-ai
brew install anomalyco/tap/opencode  # recommended
brew install opencode                 # official, updated less frequently
scoop install opencode                # Windows
choco install opencode                # Windows
sudo pacman -S opencode              # Arch Linux
nix run nixpkgs#opencode             # Nix
mise use -g opencode                 # mise/asdf

Desktop App

Available at opencode.ai/download or GitHub releases:

  • macOS (Apple Silicon): opencode-desktop-mac-arm64.dmg
  • macOS (Intel): opencode-desktop-mac-x64.dmg
  • Windows: opencode-desktop-windows-x64.exe
  • Linux: .deb, .rpm, .AppImage
  • Homebrew cask: brew install --cask opencode-desktop

Source Layout (Monorepo)

packages/
  opencode/     # main CLI package
    src/        # TypeScript source
    bin/        # CLI entrypoint
    specs/      # test specs
  core/         # shared agent core
  llm/          # LLM provider integrations
  ui/           # shared UI components
  tui/          # terminal UI
  desktop/      # desktop app
  console/      # web console
  app/          # web application
  sdk/          # public SDK
  plugin/       # plugin system
  enterprise/   # enterprise features
.opencode/
  opencode.jsonc  # project config (JSON with comments)
  agent/          # agent definitions
    duplicate-pr.md
    triage.md
  command/        # slash commands
    ai-deps.md, changelog.md, commit.md, issues.md,
    learn.md, rmslop.md, spellcheck.md, translate.md
  skills/         # behavioral skills
    effect/       # Effect.ts patterns
    improve-codebase-architecture/
  plugins/        # local plugin overrides
  glossary/       # project terminology
  tool/           # custom tools
  themes/         # TUI themes
  tui.json        # TUI configuration
  env.d.ts        # TypeScript env declarations

Config Schema

.opencode/opencode.jsonc with JSON schema at https://opencode.ai/config.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "permission": {},
  "mcp": {},
  "tools": {
    "github-triage": false,
    "github-pr-search": false,
  }
}

Required Runtime

  • Bun (for development)
  • No runtime for CLI binary (pre-built)

Target AI Tools

Works with any provider via config. The .opencode/agent/ files specify models directly:

  • opencode/claude-haiku-4-5 (duplicate-pr agent)
  • opencode/gpt-5.4-nano (triage agent)
  • opencode/kimi-k2.5 (commit command)
  • Any provider supported in packages/llm/
03

Components

OpenCode — Components

Built-in Agents (switchable with Tab key)

Agent Access Purpose
build Full-access Default development agent
plan Read-only Analysis, exploration, planning; denies file edits; asks permission for bash
general Full-access Internal subagent for complex searches/multistep tasks; invoked with @general

Agent Definitions (.opencode/agent/)

File Model Purpose
duplicate-pr.md opencode/claude-haiku-4-5 Searches for duplicate/related open PRs when a PR is opened; hidden from UI
triage.md opencode/gpt-5.4-nano Assigns GitHub issues to team members using github-triage tool; hidden from UI

Agent file format (YAML frontmatter + markdown system prompt):

---
mode: primary
hidden: true
model: opencode/claude-haiku-4-5
color: "#E67E22"
tools:
  "*": false
  "github-pr-search": true
---

Commands (.opencode/command/)

Command Model Purpose
commit.md opencode/kimi-k2.5 Git commit and push with WHY-focused messages
changelog.md (default) Generate changelog entries
ai-deps.md (default) Manage AI dependencies
issues.md (default) GitHub issue management
learn.md (default) Learn from codebase patterns
rmslop.md (default) Remove AI slop from code
spellcheck.md (default) Spellcheck documentation
translate.md (default) Translate documentation

Command file format (YAML frontmatter):

---
description: git commit and push
model: opencode/kimi-k2.5
subtask: true
---

Skills (.opencode/skills/)

Directory Purpose
effect/ Effect.ts library usage patterns
improve-codebase-architecture/ Architecture improvement guidance

Configuration Files

File Purpose
opencode.jsonc Main project config (providers, permissions, MCP, tools)
tui.json TUI appearance config
env.d.ts TypeScript environment declarations
glossary/ Project terminology definitions

AGENTS.md

Global agent instructions file at repo root — injected as context for agents operating on this codebase.

Plugins (.opencode/plugins/)

Local plugin overrides. The plugin system allows extending OpenCode with custom tools and behaviors. Two smoke-test plugins: smoke-theme.json, tui-smoke.tsx.

05

Prompts

OpenCode — Prompts

Prompt 1: Duplicate PR Detection Agent

Source: .opencode/agent/duplicate-pr.md

Technique: Tool-restricted subagent with constrained output. The agent has access to only ONE tool (github-pr-search), forcing it to stay on task. The hidden: true flag means it's not user-visible — it runs automatically.

---
mode: primary
hidden: true
model: opencode/claude-haiku-4-5
color: "#E67E22"
tools:
  "*": false
  "github-pr-search": true
---

You are a duplicate PR detection agent. When a PR is opened, your job is to search for potentially duplicate or related open PRs.

Use the github-pr-search tool to search for PRs that might be addressing the same issue or feature.

IMPORTANT: The input will contain a line `CURRENT_PR_NUMBER: NNNN`. This is the current PR number, you should not mark that the current PR as a duplicate of itself.

Search using keywords from the PR title and description. Try multiple searches with different relevant terms.

If you find potential duplicates:

- List them with their titles and URLs
- Briefly explain why they might be related

If no duplicates are found, say so clearly. BUT ONLY SAY "No duplicate PRs found" (don't say anything else if no dups)

Keep your response concise and actionable.

Prompt 2: Issue Triage Agent

Source: .opencode/agent/triage.md

Technique: Rule-based routing agent with team taxonomy. Uses the cheapest model (gpt-5.4-nano) for a routing task with a fixed set of valid outputs.

---
mode: primary
hidden: true
model: opencode/gpt-5.4-nano
color: "#44BA81"
tools:
  "*": false
  "github-triage": true
---

You are a triage agent responsible for triaging github issues.

Use your github-triage tool to triage issues.

This file is the source of truth for ownership/routing rules.

Assign issues by choosing the team with the strongest overlap...

When calling github-triage, pass one of these team values: tui, desktop_web, core, inference, windows.

## Teams

### TUI
Terminal UI issues, including rendering, keybindings, scrolling...

### Core
Core opencode server and harness issues, including sqlite, snapshots, memory, API behavior...

Prompt 3: Commit Command

Source: .opencode/command/commit.md

Technique: Template-driven commit generation with live context injection (! prefix for shell command execution).

---
description: git commit and push
model: opencode/kimi-k2.5
subtask: true
---

commit and push

make sure it includes a prefix like
docs:
tui:
core:
ci:
ignore:
wip:

For anything in the packages/web use the docs: prefix.

prefer to explain WHY something was done from an end user perspective instead of
WHAT was done.

do not do generic messages like "improved agent experience" be very specific
about what user facing changes were made

if there are conflicts DO NOT FIX THEM. notify me and I will fix them

## GIT DIFF

!`git diff`

## GIT DIFF --cached

!`git diff --cached`

## GIT STATUS --short

!`git status --short`

Note the ! prefix for shell command injection — the command's output is embedded directly into the prompt context.


Prompting Techniques Used

  1. Tool whitelist restriction — agents with "*": false and only 1-2 tools enabled; forces focus
  2. Hidden agent patternhidden: true means automation-only agents (no user-visible UI)
  3. Per-command model routing — each command can specify a different model; cost optimization
  4. Shell injection via ! — live context from git/shell commands embedded in command prompts
  5. Constrained output format — triage agent has exactly 5 valid team values; deviations are errors
  6. Subtask isolationsubtask: true runs commands without polluting main conversation context
09

Uniqueness

OpenCode — Uniqueness and Positioning

Differs from Seeds

OpenCode is a full agent runtime (not a behavior layer) with the most complete .opencode/ configuration system in this batch. Unlike superpowers and BMAD-method (which are behavior layers on top of Claude Code), OpenCode IS the agent. Unlike aider (no methodology, pure execution), OpenCode ships an opinionated .opencode/ directory structure with agents, commands, skills, plugins, glossary, and themes. The multi-model routing (per-command and per-agent model selection with cost-optimized cheap models for routing tasks) is found in no seed framework. Taskmaster-ai is the closest seed in terms of having a dedicated configuration directory (.taskmaster/) but it uses JSON config not markdown-based agent definitions, and doesn't support per-command model routing.

Key Differentiators

  1. Per-component model routing: Each command and agent can specify its own model. commit uses Kimi K2.5, triage uses GPT-5.4-nano, duplicate-pr uses Claude Haiku. This is the most granular multi-model routing in this corpus.

  2. Desktop App: The only framework in this batch with a proper native desktop application available as .dmg, .exe, .deb, .rpm. This positions OpenCode for non-terminal users.

  3. SQLite session persistence: Unlike file-based state (all seeds), OpenCode uses SQLite for structured, queryable session history and snapshots.

  4. .opencode/ configuration system: A typed JSON schema for project configuration, combined with markdown-based agent/command/skill definitions. More structured than CLAUDE.md (agent-os) and more flexible than .taskmaster/config.json (taskmaster-ai).

  5. Hidden automation agents: The duplicate-pr and triage agents run automatically on GitHub events (not invoked by users). This event-driven agent pattern is unusual in this corpus.

  6. Glossary system: .opencode/glossary/ for project terminology — no other framework in this corpus ships this.

  7. Shell injection in commands: The ! prefix in command files injects live shell command output directly into the prompt context.

Observable Failure Modes

  1. Repo moved — from sst/opencode to anomalyco/opencode; links in README and docs may be stale
  2. Plugin system is new/experimental — only 2 smoke-test plugins in the repo
  3. Desktop app is BETA — may have reliability issues
  4. SQLite schema migrations — requires careful handling as the schema evolves
  5. No explicit approval gates — unlike Cline's per-edit approval, the approval model relies on the permission: config block in opencode.jsonc; less visible to users
04

Workflow

OpenCode — Workflow

Standard Interactive Mode

  1. Launchopencode opens TUI
  2. Agent SelectionTab to switch between build (full-access) and plan (read-only)
  3. Request — type in TUI or paste
  4. Subagent delegation — use @general to delegate complex searches
  5. Edit/Execute — agent makes file edits and runs commands
  6. Command invocation — type /commit, /changelog, etc. to run specific commands with their designated models

Plan Mode Workflow

  1. Switch to plan — press Tab
  2. Exploration — agent reads files, searches codebase, explains architecture
  3. No writes — file edits denied by default; bash commands require explicit permission
  4. Switch to build — press Tab when ready to implement
  5. Execute — full-access agent implements the plan

Headless / CI Mode

opencode "run tests and fix failures" --no-interactive

(Exact flags from README: --no-interactive flag or standard pipe input)

Command Workflow

Commands in .opencode/command/ are invokable directly:

/commit   -> uses kimi-k2.5 model, runs git diff, generates WHY-focused commit message
/rmslop   -> removes AI-generated code patterns (verbose comments, over-abstraction, etc.)

Each command can specify subtask: true to run as a subtask (without consuming main context).

Phases + Artifacts Table

Phase Artifact
Plan mode Conversation context (no files)
Build mode Modified files in working tree
Commit command Git commit
Changelog command CHANGELOG.md entry
Triage agent GitHub issue assignment
Duplicate-PR agent PR comment with related PRs

Approval Gates

Gate Type Notes
Plan mode bash commands yes-no Requires explicit permission
Permission config N/A Configured in opencode.jsonc permission: block
Tool enable/disable N/A Configured in opencode.jsonc tools: block
06

Memory Context

OpenCode — Memory and Context

State Storage

State Storage Scope
Session history SQLite (via effect-drizzle-sqlite package) Project
Snapshots SQLite Project
Agent definitions .opencode/agent/*.md Project, cross-session
Commands .opencode/command/*.md Project, cross-session
Skills .opencode/skills/ Project, cross-session
Config .opencode/opencode.jsonc Project
Journal SQLite Project

SQLite Persistence

Unlike most coding agents that use file-based state, OpenCode uses SQLite (via Drizzle ORM) for session history, snapshots, and journal. The database is stored at project level. This enables:

  • Structured querying of past sessions
  • Snapshot/restore of conversation state
  • Journal of agent actions

AGENTS.md

OpenCode reads AGENTS.md at the repo root as global agent instructions — injected as context. This is analogous to CLAUDE.md.

Glossary

.opencode/glossary/ — project terminology definitions injected as context. Unique to OpenCode in this corpus.

Skills as Context

.opencode/skills/ provides domain-specific behavioral context (Effect.ts patterns, architecture principles). These are injected as relevant context, not activated by hooks.

Cross-Session Handoff

The SQLite database persists conversations across sessions. Agents can reference past sessions. The snapshot mechanism allows resuming from a saved state.

Context Compaction

Not explicitly documented in public sources. The SQLite-based history suggests structured compaction may be possible.

07

Orchestration

OpenCode — Orchestration

Multi-Agent

Yes. OpenCode ships a general subagent for complex multi-step tasks, invokable via @general. The duplicate-pr and triage agents are hidden automation agents that run on GitHub event triggers.

Orchestration Pattern

Task-decomposition-tree: the @general subagent handles "complex searches and multistep tasks" on behalf of the main build/plan agent.

Agent Architecture

  • Primary agents: build (full-access) and plan (read-only) — user-visible, Tab-switchable
  • Subagent: general — invoked by primary agents via @general mention
  • Hidden agents: duplicate-pr and triage — event-driven automation agents (not user-visible)

Isolation Mechanism

None explicit for standard sessions. Each agent runs in the same process/context. The hidden automation agents (triage, duplicate-pr) are GitHub-event-triggered, running in an isolated event context.

Multi-Model

Yes. OpenCode implements per-component model routing:

  • duplicate-pr agent: opencode/claude-haiku-4-5
  • triage agent: opencode/gpt-5.4-nano
  • commit command: opencode/kimi-k2.5
  • Primary agents: configurable default model

This is cost-optimized routing: cheap models for structured/routing tasks, capable models for main development work.

Execution Mode

Interactive-loop (TUI) with headless support.

Crash Recovery

SQLite-based session persistence enables recovery after crashes.

Context Compaction

Not explicitly documented.

Consensus Mechanism

None.

Prompt Chaining

Yes: commands with subtask: true run as subtasks that feed results back to the main agent context.

08

Ui Cli Surface

OpenCode — UI and CLI Surface

CLI Binary

Name: opencode
Install: npm i -g opencode-ai@latest or curl install script
Is thin wrapper: No — OpenCode is its own agent runtime
Platform: Pre-built binaries for multiple platforms

Key Features

  • Interactive TUI with keyboard navigation
  • Tab to switch between build/plan agents
  • @general to invoke subagent
  • / to invoke commands from .opencode/command/
  • Themes via .opencode/themes/
  • SSH support

Terminal TUI

Rich TUI built with the tui package (TypeScript, Bun). Features:

  • Agent mode indicator (build vs plan)
  • Conversation history
  • File diff display
  • Theme customization (tui.json, .opencode/themes/)
  • SSH-compatible (can be used in remote sessions)

Desktop App (BETA)

Native desktop application available from opencode.ai/download:

  • macOS: .dmg (arm64 and x64)
  • Windows: .exe
  • Linux: .deb, .rpm, .AppImage
  • Homebrew cask: brew install --cask opencode-desktop

The desktop app provides the same agent experience in a native window.

Web Interface

opencode web launches a browser-based UI. Also available as a hosted service at opencode.ai.

Zen Mode (OpenCode Pro feature)

"OpenCode Zen" — fires tasks to background infrastructure and returns immediately. Results available later. Referenced in AGENTS.md as a paid/Pro tier feature.

Observability

  • SQLite database for session history (structured, queryable)
  • Snapshot capability for session state
  • Journal of agent actions
  • Not a traditional audit log file

MCP Integration

.opencode/opencode.jsonc has an mcp: block for configuring external MCP servers. The tools: block enables/disables specific tools per project.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…

gpt-engineer ★ 55k

ARCHIVED — the original LLM-driven code generation experiment that generates entire applications from a prose specification file.