bootstrap

name	bootstrap
description	Set up global OpenCode configuration under ~/.config/opencode, including AGENTS.md, opencode.json, tui.json, agents, commands, skills, plugins, themes, MCP servers, providers, and permissions.

Bootstrap OpenCode

Set up the user's global OpenCode environment. All generated global config goes under ~/.config/opencode/, not the current project.

Phase 1: Read the room

Read existing config. Missing files are normal.

1. ~/.config/opencode/AGENTS.md
2. ~/.config/opencode/opencode.json
3. ~/.config/opencode/tui.json
4. ~/.config/opencode/agents/
5. ~/.config/opencode/commands/
6. ~/.config/opencode/skills/
7. ~/.config/opencode/plugins/
8. ~/.config/opencode/themes/
9. ~/.config/opencode/tools/
10. ~/.claude/CLAUDE.md and ~/.claude/skills/ only to understand fallback compatibility
11. ~/.agents/skills/ only to understand compatible global skills

Run diagnostics when available:

opencode --version
opencode auth list
opencode agent list
opencode mcp list
opencode models
which git gh node npm pnpm bun python python3 uv docker rg fd

If keybinds, mouse behavior, or theme rendering are in scope, inspect terminal variables:

echo "$TERM"
echo "$TERM_PROGRAM"
echo "$COLORTERM"
echo "$XDG_SESSION_TYPE"

Present a concise profile:

Environment: Linux X11, WezTerm, Node 22, Bun, git + gh
OpenCode:    1.x.y, global AGENTS.md exists, opencode.json exists
Models:      opencode/gpt-5.1-codex, anthropic/claude-sonnet-4-5 available
Resources:   4 global skills, 2 commands, 1 plugin, system theme
Permissions: edit ask, bash ask, .env reads denied

Do not print secrets from auth files, .env files, or provider config.

Phase 2: Ask only what is missing

Ask at most 3 questions. Useful questions:

• Preferred default model and small model, if not configured.
• Whether global config should be minimal or include opinionated safety permissions/plugins.
• Whether existing Claude Code skills should stay available through compatibility or be copied into ~/.config/opencode/skills/.

Skip questions when the answer is obvious from existing config.

Phase 3: Configure incrementally

Before writing, show the target path and intended change. Never overwrite existing files blindly.

1. Global rules: ~/.config/opencode/AGENTS.md

Create or update a short global instruction file. It should include:

# Global OpenCode Instructions

## Preferences
[communication and workflow preferences]

## Tools & Environment
[default package managers, test runners, shell notes]

## Boundaries
[always / ask first / never]

Target 20-50 lines. Keep project-specific commands out.

If ~/.config/opencode/AGENTS.md exists, propose a diff instead of replacing it.

2. Runtime config: ~/.config/opencode/opencode.json

Only add settings with a reason. Common useful defaults:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual",
  "autoupdate": "notify",
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask",
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  },
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

Do not invent model IDs. Use opencode models output or leave model defaults unset.

3. TUI config: ~/.config/opencode/tui.json

Use a dedicated tui.json for theme, keybinds, mouse, scroll, and diff style.

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "system",
  "diff_style": "auto",
  "mouse": true,
  "keybinds": {
    "leader": "ctrl+x"
  }
}

Only change keybinds when there is a concrete conflict.

4. Agents

Use markdown files in ~/.config/opencode/agents/ for focused behavior, or agent entries in opencode.json when one file is easier to review.

Prefer permission over deprecated tools:

---
description: Reviews code without editing files
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff*": allow
    "git status*": allow
---

Review changed code for bugs, regressions, missing tests, and unsafe behavior. Do not edit files.

5. Commands

Use ~/.config/opencode/commands/ for reusable slash commands. Keep command prompts short and task-shaped.

6. Skills

Use ~/.config/opencode/skills/<name>/SKILL.md for reusable workflows. Skill names must match ^[a-z0-9]+(-[a-z0-9]+)*$ and the directory name.

Do not assume skills are slash commands. Use command files when a user-facing slash command should load a skill.

7. Plugins and packages

Create plugins only when prose or permissions cannot enforce the behavior. Plugins are executable code.

For third-party npm plugins, review source and explain risk before install. OpenCode can install plugin dependencies with Bun at startup.

8. MCP servers and auth

Use opencode mcp add for interactive setup. Do not store tokens in examples. Prefer provider auth through opencode auth login or environment variables.

Phase 4: Recap

Use this format:

Done. Global OpenCode config updated.

  OK ~/.config/opencode/AGENTS.md       [what changed]
  OK ~/.config/opencode/opencode.json   [what changed]
  OK ~/.config/opencode/tui.json        [what changed]
  INFO Agents/commands/skills/plugins   [what changed or recommended]

Restart OpenCode or open a new session for changes to load.

Ground rules

• Global config must be portable across projects.
• Use .opencode/ only for project-local resources.
• Prefer fail-fast examples over silent fallbacks.
• Permissions and plugins are enforcement. Prose is guidance.
• If sharing is configured, default to manual or disabled, never auto without explicit confirmation.