---
title: OpenCode & Agents
description: Shared OpenCode agents, commands, skills, and plugins.
sidebar:
label: Overview
order: 1
---
The repo ships a shared [OpenCode](https://opencode.ai) configuration: agents, slash commands, skills, and lifecycle plugins. Agents, commands, plugins, and shared `lib/` modules live in `agents/.config/opencode/`; isolated OpenCode v2 server and TUI plugin ports live under `plugins-v2/` while the v1 plugin API remains active. The OpenCode v2 runtime loads the migrated `workflow-manifest` server plugin from that isolated directory. Portable skills and reviewed third-party snapshots are maintained independently in [`timmo001/skills`](https://github.com/timmo001/skills), pinned at `agents/.agents/skills/`, and exposed through the shared `~/.agents/skills/` path.
The repo-local `opencode.json` allows agents to inspect the live directories managed by stow and list their parent config directories. Direct edits to unmanaged files in those directories are denied; change the matching source under `~/.config/dotfiles` and run `dot stow` instead. Existing stowed symlinks resolve to their repository source, so edits still land in the tracked package. Personal repository references are supplied by the private machine overlay as writable local paths rather than repository-backed cache clones. References declared inside `docs/` resolve back to this checkout, including the `opencode-config` alias because that repository is a generated mirror of this source.
The notes capture daemon is intentionally separate from this shared interactive configuration. Dotfiles only installs its systemd units and private launch wrappers; the dedicated fail-closed agent and OpenCode config are owned by the `notes` repository.
The OpenCode-specific assets are generated from this dotfiles repo and published automatically to [`timmo001/opencode-config`](https://github.com/timmo001/opencode-config). Its `skills/` directory pins [`timmo001/skills`](https://github.com/timmo001/skills) rather than duplicating those files.
:::tip[The portable basis]
Unlike the rest of these (personal) dotfiles, the OpenCode config is built to be reused. `opencode-config` is a standalone, portable export with its own install instructions, so you can adopt individual agents, commands, skills, or plugins without taking on anything else here. Plugins that share support modules are published with the `lib/` directory they import and should be copied with that directory.
:::
:::caution[OpenCode v2 hybrid]
The published lifecycle plugins use the v1 plugin API. The private `opencode2` route shares agents, commands, skills, instructions, and compatible server configuration, but loads isolated v2 plugin ports instead of the v1 implementations. The workflow manifest tool is available in both versions; other lifecycle-backed context injection and guards described below remain v1-only until their server plugins are ported.
:::
Agent catalogue with links to each execution posture.
Slash commands that route to agents and skills.
Reusable workflows and behavioural contracts.
Context, evidence, and enforcement hooks.
Model Context Protocol servers wired into the config.
Lightweight companion workflows sharing skills and project instructions.
Machine-readable docs and the hosted MCP endpoint.
## How it fits together
- **Graduated agent permissions** - agents range from workspace-read-only (`reviewer`) through ask-gated (`build-ask`) to edit-capable (`refactorer`). Read-only primary agents use native task allowlists, while `general-readonly` and `researcher-readonly` are terminal subagents with task delegation denied. The interactive `researcher` can fan out once without allowing recursive research chains.
- **Comparative primary-source research** - `/research` answers direct facts from the source that owns them. When judgement is involved, it compares relevant project policy, maintainer and contributor practice, independent evidence, and credible disagreement claim by claim rather than ranking people by reputation. Clear findings can hand straight to the build agent, while unresolved work routes to a targeted question, `/plan`, or `/grill` according to its size. Research agents can inspect indexed local agent history through the read-only `ctx` status, source, search, show, locate, docs, and SQL commands; shell output flags remain blocked across these read-only agents.
- **Plain-language restatement** - `/bro` re-pitches the previous response with enough context to recover the thread, using short, direct, unambiguous language while preserving concrete facts, decisions, paths, commands, citations, and next actions.
- **Session references** - `/session-reference ` resolves another OpenCode session by its listed title and loads the complete indexed `ctx` transcript into the current conversation. It adds context only and does not continue that session's work unless the request says to.
- **Workflow failure diagnosis** - `/fix-workflows` inspects recent GitHub Actions failures for the current branch, or a named workflow or run, reproduces the failing path locally where possible, applies the smallest fix, and verifies it without committing, pushing, or rerunning workflows automatically.
- **Skill-based routing** - commands are thin wrappers that name an agent, declare required skills, and state whether branch context is needed. The workflow logic lives in skills and plugins.
- **Coding-practices routing** - code work loads `changeset-scope` first when bounded, then `effect` for Effect code or `effect-principles` for non-Effect code. Independently applicable repository, language, framework, cleanup, domain, and design skills activate through their own descriptions.
- **Question-led stress-testing** - `/grill` asks every currently unblocked material decision in one numbered round. Light runs one highest-leverage round; Full recomputes the decision frontier until no material branch remains. Phrases such as "lightly grill me" select Light directly, and unclear intensity is asked once.
- **Questionnaire drafts** - `to-questionnaire` turns knowledge held by another person into a channel-aware draft for a GitHub comment, Slack or Discord conversation, or a full Markdown document. It returns text in chat by default and never posts a comment, sends a message, or writes a file without an explicit request for that exact action. Slack and Discord remain draft-only.
- **Human-only steps** - `human-step-guide` activates only when available tools cannot cross a human boundary such as an approval, physical action, credential entry, or dashboard step. It gives the location, exact action, expected result, information to return, and follow-up verification without changing secrets, environment files, external settings, comments, or messages.
- **Staged implementation** - `/plan` identifies one active stage, records separate reviewable stages as deferred, and makes no edits. It recommends one numbered handoff per deferred reviewable phase. In a new repository it tries handoffs first, then proposes one temporary, all-in-one repository-local working Markdown plan when repository notes are not available yet; that document tracks numbered phases and updates their status at every checkpoint. During execution, the `staged-implementation` skill defines shared contracts before delegation, uses targeted checks while iterating, and pauses at validated checkpoints between separate review units unless the user requested one combined delivery. Broad, risky stages backed by an approved plan or handoff may use one implementation worker and one fresh read-only review. Bounded local review fixes may resume that worker once; broader remediation starts a fresh worker from a compact handoff. Ordinary stages stay with the host, and deterministic validation rather than agent agreement remains the completion gate.
- **Visual plan and code review** - Plannotator opens plan review from OpenCode's `plan` agent and provides `/plannotator-review`, `/plannotator-annotate`, and `/plannotator-last` for manual review. Its CLI is pinned through mise's GitHub backend because it is not available from Arch, AUR, or the Aqua registry.
- **Visible browser control** - The Browser Control skill drives the mise-managed `browser-control` CLI against attached Chromium tabs. The stowed `browser-control-extension-sync` helper copies the bundled extension to `~/.local/share/browser-control/extension` and links the installed package back to that stable path, so Chromium keeps the same unpacked-extension identity across upgrades. Mise's global `postinstall` hook runs that helper after `npm:@opencode-ai/browser-control` installs or upgrades. Load the stable directory once in Chromium, then restart Chromium or reload the extension after upgrades. Private doctor checks can require the extension in Chromium and reject copies in other browser profiles because one relay supports only one extension instance. Its MCP server is optional and is not configured by default.
- **Branch context injection** - commands registered with the `branch-context` plugin receive pre-computed git and PR state as structured XML instead of running their own `git` or `gh` calls. The plugin consumes the standalone [`context`](https://context.timmo.dev) CLI (`context git --json`), preserves explicit unresolved default-branch state, and keeps the plugin-specific injection rules here. `/update-docs` queries the Context MCP server's `git_context` tool directly when it needs recent-change state.
- **Commit context injection** - `/commit`, `/commit-push`, and `/commit-push-watch` stay in the active parent session and receive current Context CLI state plus path-level ownership evidence from persisted session patches and successful mutation tools. Existing staged files take precedence, unrelated dirty paths remain excluded, and multi-repository sessions receive one independently collected scope per Git root. Incomplete evidence falls back to an explicit Context MCP refresh rather than widening commit scope.
- **Codebase stack injection** - the `stack-context` plugin injects a deterministic tech-stack summary (languages, ecosystems, and frameworks with their general locations) computed by [`context stack --json`](https://context.timmo.dev/context/stack/), including structured notices when safety limits make a section partial. It injects automatically on the first message of a session inside a git repository, and on demand via `/inject-stack` or (alongside branch context) `/inject-context`.
- **Repository notes**: the `repo-notes` plugin injects the current repository's notes path, the `notes` MCP server owns vault reads and writes, and `notes-guard` blocks direct file or shell access to the notes vault. See [Notes & Handoffs](/dot/notes/) and [MCP Servers](/opencode/mcp/).
- **Secret protection** - the `env-protection` plugin blocks reads of `.env` files (except `.env.example`).
- **Generated artefact protection** - the `generated-artifact-guard` plugin blocks direct mutation of generated dotfiles artefacts and names the canonical regeneration command. Read-only inspection (`cat`, `git diff`, `rg`, and similar) is allowed. The guard activates only inside this dotfiles repository layout.
| Generated artefact | Regenerate with |
| --- | --- |
| `docs/src/content/docs/dot/commands.md` | `mise run docs:gen:cli` |
| `docs/src/content/docs/reference/{agents,commands,skills,plugins}.md` | `mise run docs:gen:opencode` |
| `bash/.local/share/bash-completion/completions/dot` | `dot completions bash` |
| `fish/.config/fish/completions/dot.fish` | `dot completions fish` |
| `zsh/.local/share/zsh/site-functions/_dot` | `dot completions zsh` |
| `scripts/.local/bin/dot` | `mise run dot:build` |
| `docs/public/og.png` | `mise run docs:og` |
- **Background dev servers** - starting a long-running dev server follows a precedence: the project's own `AGENTS.md` workflow first, then framework-native background mode (Astro 7+ self-detaches `astro dev` under an agent), then pitchfork as the fallback. The `pitchfork-dev-server-guard` plugin covers only the pitchfork tier, redirecting foreground dev commands to `serve:*` or `pitchfork start` when a project declares `pitchfork.toml`, and it leaves `astro dev` to Astro's native mode.
- **Herdr agent launches** - agent-created Herdr layouts stay provisional until OpenCode starts in the pane returned by Herdr, receives its instructions through `agent prompt`, and reports a pane-bound lifecycle state through `agent get`. A new workspace or tab already supplies its root pane. Failed starts or deliveries remove only the topology created by that attempt, while transcript or artefact evidence remains required before claiming the requested work completed.
- **Contextual notifications** - main-session idle completions and all permission prompts send an Omarchy-formatted desktop notification when `omarchy` is available. Outside Herdr they also ring BEL and play the freedesktop message sound when `paplay` is available; Herdr sessions leave those sounds to Herdr. When the plugin starts under Hyprland, it captures the active window address so clicking a notification can return focus to that window. In Herdr it also focuses the originating workspace and tab. Background completion events stay silent.
### Context reliability warnings
| Model | Warning | Critical |
| --- | ---: | ---: |
| GPT-5.6 Sol | 256,000 | 512,000 |
| Claude Opus 4.8 | 100,000 | 150,000 |
| Claude Opus 5 | 100,000 | 150,000 |
| Other models | 64,000 | 128,000 |
These are context-health policies, not hard model limits. GPT-5.6 Sol's bands follow OpenAI's published [256K-512K and 512K-1M long-context results](https://openai.com/index/gpt-5-6/#long-context), where MRCR falls from 91.5% to 73.8%. The Opus critical band follows Anthropic's documented [150,000-token default compaction trigger](https://docs.anthropic.com/en/docs/build-with-claude/compaction#parameters), with 50,000 tokens of warning headroom. The conservative fallback reflects cross-model reports that advertised context and effective context differ, including [RULER](https://arxiv.org/abs/2404.06654), [NoLiMa](https://arxiv.org/abs/2502.05167), and [Context Rot](https://research.trychroma.com/context-rot).
Each band appears once per session and resets after successful compaction. The count uses prompt occupancy (`input + cache read`), matching the context supplied to the model without counting generated output, reasoning, or cache writes. The thresholds remain context-health policies rather than authoritative next-request limits. Alerts appear as both built-in TUI toasts and clickable system notifications, so background sessions remain visible; headless runs silently skip unavailable notification paths.
## Tooling
- `opencode` is installed through mise's Aqua backend. The explicit `c` alias resolves to the same binary and keeps the GitHub MCP bearer scoped to the launched harness process.
- `dot agents-sync` — mirror `~/.config/opencode/AGENTS.md` into agent harness instruction files. Runs automatically at the end of full `dot update` and `dot init`.
- `opencode debug ` — inspect resolved OpenCode config, paths, skills, and agents directly.
- `DOT_CONTEXT_CAPTURE=1` - capture assembled system-prompt segments and tool definitions for starter-context profiling. See [Environment Variables](/configuration/environment/#debugging-and-output).
- `/agent-benchmark [benchmark flags]` - launch this repository's OpenCode benchmark as the managed Pitchfork daemon `agent-benchmark` through the repo-local skill. The command returns after startup; use `mise run benchmarks:opencode:status`, `mise run benchmarks:opencode:logs`, and `mise run benchmarks:opencode:stop` to manage it. `mise run benchmarks:opencode:logs:follow` provides an interactive live stream (`mise run benchmarks:opencode:logs -- --follow` is equivalent), but it keeps running after the benchmark completes and must be cancelled manually. Use status and ordinary logs rather than follow mode to check completion. Completed logs contain the full benchmark invocation, deterministic pass count, artifact path, and host report path. The process invokes `mise run benchmarks:opencode`; pass `--model ` to override the current session model. Valid ids come from `opencode models`, limited to providers OpenCode authenticates natively: each run loads the context-capture plugin alone, so plugin-backed providers such as `cursor/*` are unavailable inside the benchmark and fail every scenario. Each scenario receives a fresh repository with one synthetic baseline commit and no upstream history, plus the current worktree's shipped `refactorer` or `reviewer` agent and required skills. Implementation scenarios expose one scenario-owned verification command; the harness first proves each verifier rejects the baseline and accepts a maintained reference implementation, then requires both the agent invocation and the host rerun to pass. Deterministic checks also audit agent and skill source hashes, skill load order, changed paths, implementation content, review findings and Standards/Spec sections, recorded tool calls, external access, answer lookup, and successful starter-context capture. Aggregate output reports per-scenario all-run consistency plus tool-call, repeated-call, post-mutation investigation, elapsed-time, context-size, and loaded-skill measurements without imposing arbitrary efficiency thresholds. A separate read-only model report assesses that evidence and flags unnecessary skill loads. The stable `host-report.json` entry point combines behavioural and context results, and checksummed, write-protected evidence remains under the ignored `.benchmarks/output/opencode/` path. The benchmark uses provider credentials and is intentionally not part of CI.
- `dot skill-updates` checks the writable `~/repos/skills` checkout. Clean updates are materialised through the Vercel Skills CLI and repository-owned `imports.json` overlay; adapted changes open an interactive review without replacing the committed snapshot. The scheduled skills-repo workflow uses the same importer to open clean update PRs and keeps adapted changes on a dashboard issue.
- `dot skill-updates-agent` is the shared Effect workflow for skill updates. GitHub mode checks imports, publishes clean upstream updates, dispatches validation, and refreshes the dashboard issue even when publishing fails. Device mode reads the private YAML config for repository paths, the authorised prompt, agent, and ordered model fallback chain. Each device run uses a kernel lock that is released automatically if the process is killed, requires clean default-branch worktrees, streams OpenCode progress, validates new PR diffs, commit subjects, assignment, and auto-merge state, refreshes the dashboard, and records completion atomically only after one exact success status. The private systemd timer invokes device mode through a thin wrapper.
- `dot skill-check` validates branch-context command wiring and compares every file in adapted imported skills with their current upstream source. Use `--skill ` to check one adapted import. Exact matches no longer need a maintained local adaptation, so human sessions offer to reimport them through the standard Skills CLI while agent sessions print the command to run.
- `dot is-agent` — detect whether dot is running under an AI agent, from agent environment variables with a Linux `/proc` ancestry fallback (exit `0`/`1`, so scripts can branch with `if dot is-agent`). `DOT_AGENT=1`/`0` overrides detection. When an agent (or a non-interactive stdout) invokes a `dot` command that would open the TUI, dot refuses and points at the machine-readable equivalent instead.
## Adding Skills
For a new repository-owned skill, add `/SKILL.md` in `timmo001/skills`, classify it in `skills.sh.json` and `PORTABILITY.md`, then run the repository validator and installer discovery check.
For a third-party skill, add its origin, reviewed path SHA, licence, and local-edit declarations to `imports.json`. Run `python scripts/import_skill.py ` to review the complete CLI-materialised snapshot. Use `--apply` only for a clean import; adapted skills are edited after review, then their accepted SHA is recorded in `imports.json` and materialised with `--metadata-only`. Commit and review the snapshot before updating the dotfiles submodule pin. Normal `dot update` only pulls and stows that committed revision.
Dotfiles-specific global skills belong in `dotfiles-skills/.agents/skills//` and are applied with `dot stow`; they are not published through the shared skills repository.
Publishing to `opencode-config` happens automatically via GitHub Actions on push. The Agents, Commands, Skills, and Plugins pages above are generated by `mise run docs:gen:opencode` from the live assets and pinned skills checkout, so they always match what ships. Edit OpenCode assets here and skills in `timmo001/skills`, not the generated pages. Renovate manages the skills submodule revision after reviewed snapshots land upstream. See also the generated [`dot` Command Reference](/dot/commands/).