OpenCode Agent Setup

Agentic instructions for configuring an OpenCode development environment with CLI tools, MCP servers, skills, and global agent rules.

Target platform: macOS (arm64) with Homebrew and Go installed.

Quick Install

curl -fsSL https://raw.githubusercontent.com/SubChord/opencode-setup/main/install.sh | bash

Or clone and run locally:

git clone https://github.com/SubChord/opencode-setup.git
cd opencode-setup
./install.sh

The script is idempotent — safe to re-run at any time.

Step-by-Step Instructions for AI Agents

Follow these steps sequentially. Each step is idempotent.

1. Install CLI Tools via Homebrew

brew install ast-grep shellcheck scc difftastic yq hyperfine watchexec

Tool	Binary	Purpose
ast-grep	sg	Structural code search/refactoring via AST patterns (tree-sitter)
shellcheck	shellcheck	Static analysis for shell scripts
scc	scc	Fast code counter (languages, LOC, complexity)
difftastic	difft	Structural diff by AST nodes
yq	yq	Query/edit YAML, JSON, TOML, XML preserving comments
hyperfine	hyperfine	Command-line benchmarking with statistical analysis
watchexec	watchexec	File watcher that runs commands on change

2. Install Go Tools

Requires Go 1.21+ on PATH.

go install mvdan.cc/gofumpt@latest
go install golang.org/x/vuln/cmd/govulncheck@latest
go install honnef.co/go/tools/cmd/staticcheck@latest

If golangci-lint is not already installed:

brew install golangci-lint

3. Install Superpowers Skills

Clone the superpowers repository and symlink skills into OpenCode's skills directory.

mkdir -p ~/.config/opencode/skills
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers 2>/dev/null || git -C ~/.config/opencode/superpowers pull
ln -sfn ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers

4. Configure MCP Servers

Write the global OpenCode config. This adds two remote MCP servers (no API keys required) and sets up directory permissions. Adjust the permission paths to match your project directories.

Create or update ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/Documents/projects/**": "allow"
    },
    "edit": {
      "~/Documents/projects/**": "allow"
    }
  },
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

MCP Server	URL	Purpose
context7	https://mcp.context7.com/mcp	Up-to-date library/framework documentation
gh_grep	https://mcp.grep.app	Search real code on GitHub via grep.app

5. Create Global Agent Instructions

Create ~/.config/opencode/AGENTS.md with the content below. This file is loaded into every OpenCode session, giving the agent awareness of available tools and behavioral rules.

# Global Agent Instructions

## Available CLI Tools

The following tools are installed on this machine and should be used when appropriate.

### Code Search & Refactoring

- **ast-grep** (`sg`): Structural code search and refactoring using AST patterns. Supports 20+ languages via tree-sitter. Use instead of regex for code pattern matching.
  - Example: `sg -p 'console.log($$$ARGS)' -l js` to find all console.log calls
  - Example: `sg -p '$PROP && $PROP()' --rewrite '$PROP?.()' -l ts` for refactoring

### Analysis & Validation

- **shellcheck**: Static analysis for shell scripts. Run on any shell scripts before suggesting them to catch common pitfalls.
- **scc**: Fast code counter. Use `scc` to get a quick overview of a codebase (languages, lines of code, complexity).
- **difftastic** (`difft`): Structural diff tool that compares by AST nodes. Use `difft file1 file2` for syntax-aware diffs.

### Data Format Tools

- **yq**: Query and edit YAML, JSON, TOML, and XML files programmatically while preserving comments and formatting. Use for config file manipulation.
  - Example: `yq '.services.web.image' docker-compose.yml`
  - Example: `yq -i '.version = "2.0"' config.yaml`

### Benchmarking

- **hyperfine**: Command-line benchmarking with statistical analysis. Use when comparing performance of commands or optimizations.
  - Example: `hyperfine 'command1' 'command2'`
  - Example: `hyperfine --export-markdown results.md 'make build'`

### File Watching

- **watchexec**: File watcher that executes commands on change. Use for persistent feedback loops during development.
  - Example: `watchexec -e go -- go test ./...` to rerun tests on Go file changes
  - Example: `watchexec -e ts,tsx -- npm run build` to rebuild on TypeScript changes

### Go Development

- **golangci-lint**: Go linter aggregator (installed via gvm).
- **gofumpt**: Stricter Go formatter, superset of gofmt. Use for formatting Go code.
- **govulncheck**: Scan Go modules for known vulnerabilities. Run `govulncheck ./...` in Go projects.
- **staticcheck**: Advanced Go static analysis. Run `staticcheck ./...` for additional checks beyond golangci-lint.

## MCP Servers

The following MCP servers are configured in `~/.config/opencode/opencode.json`:

- **context7**: Fetches up-to-date library and framework documentation. Use `context7` tools when you need current docs for a specific library or framework version, rather than relying on training data which may be outdated.
- **gh_grep**: Searches real code on GitHub via grep.app. Use `gh_grep` tools when you need working code examples or want to see how others have implemented a specific pattern or API.

## Behavioral Rules

### Go Projects

- Use `gofumpt` (not `gofmt`) for formatting Go code.
- Run `golangci-lint run ./...` to validate changes before considering Go work complete.
- Run `govulncheck ./...` when `go.mod` or `go.sum` are modified.
- Run `staticcheck ./...` for additional static analysis when doing significant refactoring.

### Shell Scripts

- Always run `shellcheck` on shell scripts before suggesting them to the user.

### Code Search

- Prefer `sg` (ast-grep) for structural code search and refactoring over regex-based approaches when working with supported languages.

### Documentation Lookups

- When needing current documentation for a library or framework, use `context7` MCP tools instead of relying on potentially outdated training data.
- When unsure how to use an API or implement a pattern, use `gh_grep` MCP tools to find real-world code examples on GitHub.

6. Verify Installation

Run these commands to confirm everything is working:

sg --version
shellcheck --version
scc --version
difft --version
yq --version
hyperfine --version
watchexec --version
gofumpt --version
govulncheck -version
staticcheck --version
golangci-lint --version
ls ~/.config/opencode/skills/superpowers/
cat ~/.config/opencode/opencode.json
cat ~/.config/opencode/AGENTS.md

All commands should succeed without errors.

What This Gives You

After setup, every OpenCode session will:

• Know about all installed CLI tools and when to use them (via AGENTS.md)
• Have access to MCP servers for live documentation (Context7) and real-world code search (gh_grep)
• Follow behavioral rules like using gofumpt over gofmt, running shellcheck on scripts, preferring ast-grep for code search
• Have superpowers skills for structured workflows (brainstorming, TDD, debugging, code review, git worktrees, etc.)