OpenCode & Agents

The repo ships a shared OpenCode configuration: agents, slash commands, skills, and lifecycle plugins. Agents, commands, plugins, and shared lib/ modules live in agents/.config/opencode/. Portable skills and reviewed third-party snapshots are maintained independently in 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.

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. Its skills/ directory pins timmo001/skills rather than duplicating those files.

AgentsAgent catalogue with links to each execution posture.

CommandsSlash commands that route to agents and skills.

SkillsReusable workflows and behavioural contracts.

PluginsContext, evidence, and enforcement hooks.

MCP ServersModel Context Protocol servers wired into the config.

Agents / LLMsllms.txt bundles for loading these docs into AI-assisted sessions.

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 <exact sidebar title> 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 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, 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 and MCP Servers.
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, where MRCR falls from 91.5% to 73.8%. The Opus critical band follows Anthropic’s documented 150,000-token default compaction trigger, with 50,000 tokens of warning headroom. The conservative fallback reflects cross-model reports that advertised context and effective context differ, including RULER, NoLiMa, and 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 <paths|config|skill|info|agent> — 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.
/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 <provider/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-check validates branch-context command wiring.
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 <name>/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 <name> 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/<name>/ 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.