OpenCode¶

Terminal-based AI coding assistant. Config managed with stow.

Installation¶

cd ~/dotfiles
stow opencode

Symlinks ~/.config/opencode/ to dotfiles.

Structure¶

opencode/.config/opencode/
├── opencode.json      # Config (models, permissions, MCP)
├── agent/             # Agent definitions
├── skill/             # Reusable skills
└── command/           # Slash commands

Agents¶

Primary Agents (User-Facing)¶

Agent	Model	Use Case
`turbo`	default	Fast iteration, minimal approval gates
`ideation`	default	Brainstorming, creative exploration
`airflow-migration-orchestrator`	GPT-5.2	Large-scale DAG migrations

Subagents (Delegated via Task)¶

Agent	Model	Use Case
`builder`	GPT-5.2-Codex	Complex multi-file implementations
`quick-fix`	Claude Haiku 4.5	Small one-off edits (docstrings, renames, imports)
`tester`	GPT-5.2-Codex	Test writing and validation
`airflow-expert`	GPT-5.2-Codex	DAG development and debugging
`summarizer`	Claude Haiku 4.5	Code and project summarization
`reviewer`	default	Code review, security audit
`planner`	default	Task decomposition and planning

opencode                  # Default agent
opencode --agent turbo    # Specific agent
# Tab to switch during session

Model Strategy¶

Quality tasks (builder, tester, airflow-expert): GPT-5.2-Codex - latest code-optimized model
Speed tasks (quick-fix, summarizer): Claude Haiku 4.5 - fast, efficient for focused work
Reasoning tasks (reviewer, planner): default (Sonnet) - deeper analysis needed

Permissions¶

Defined in agent frontmatter. Example from turbo.md:

permission:
  bash:
    "*": "allow"
    "rm -rf /*": "deny"
    "sudo *": "deny"
    "tofu apply*": "ask"
    "kubectl delete*": "ask"
    "git push*": "ask"
  edit:
    "**/*.env*": "ask"
    "**/*.key": "deny"

Permission Levels¶

Level	Behavior
`allow`	Execute without asking
`ask`	Prompt for approval
`deny`	Block completely

Skills¶

Reusable knowledge modules loaded by agents:

Skill	Purpose
`python-uv`	PEP 723 scripts, uv-first policy
`airflow`	DAG patterns, KubernetesPodOperator
`k8s-troubleshoot`	Kubernetes debugging
`aws-iam`	IAM policy creation and debugging
`steampipe-aws`	AWS resource discovery via SQL
`code-review`	Ruthless review methodology
`minimal-build`	Build with minimal code
`progress-tracker`	SQLite-based task tracking

MCP Servers¶

Disabled by default. Enable per-project in opencode.json:

{
  "mcp": {
    "steampipe": { "enabled": true },
    "PieGPT": { "enabled": true }
  }
}

Server	Purpose
`steampipe`	AWS/cloud queries (preferred)
`PieGPT`	K8s ops (Avant)
`spacectl`	Spacelift (Avant)
`mcp-server-docker`	Docker operations

Slash Commands¶

Command	Purpose
`/context`	Project discovery and analysis
`/commit`	Conventional commits with formatting
`/worktrees`	Git worktree management

Tips¶

Use @quick-fix for small edits, @builder for complex work
Check justfile first for project commands
Use git worktrees for parallel work
Prefer Steampipe for AWS resource queries
Load skills explicitly when needed (e.g., "load python-uv skill")

Customization¶

Add agents: Create .md files in agent/

Add skills: Create directories in skill/ with SKILL.md

Add commands: Create .md files in command/