Opencode Configuration

The opencode configuration lives at the repository root. The installer symlinks these files into ~/.config/opencode/ for opencode to read.

File Structure

ai-dotfiles/
├── opencode.base.json     # Version-controlled template (do not edit directly)
├── opencode.jsonc         # Schema reference
├── opencode.package.json  # Plugin dependency version template
├── AGENTS.md              # Agent working style rules
├── agents/                # Agent definitions
├── skills/                # Skill bundles
├── .secrets/              # Secrets directory template (.gitignore only, no tokens stored in repo)
└── installers/
    └── opencode.sh        # Installer script

~/.config/opencode/
├── opencode.base.json ->  (symlink to repo)
├── opencode.jsonc      ->  (symlink to repo)
├── AGENTS.md           ->  (symlink to repo)
├── agents/             ->  (symlink to repo)
├── skills/             ->  (symlink to repo)
├── opencode.json          # Your editable configuration (created by installer, not tracked)
├── package.json           # Plugin dependencies (copied from opencode.package.json)
├── .secrets/              # External MCP tokens (created by installer, not tracked)
│   ├── github-pat         # GitHub PAT placeholder (fill with your token)
└── node_modules/          # Installed dependencies (not tracked)

opencode.base.json (Template)

opencode.base.json is the version-controlled template at the repository root. It defines the default configuration: agent settings and all pre-installed MCP servers. The installer copies this to opencode.json in ~/.config/opencode/ on first run. Do not edit this file directly — your local changes would show up in every git status.

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan",
  "plugin": [],
  "mcp": {
    "Google Chrome MCP": {
      "type": "local",
      "command": ["npx", "chrome-devtools-mcp@latest"]
    },
    "Linear MCP": {
      "type": "local",
      "enabled": false,
      "command": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/mcp"]
    },
    "Notion": {
      "type": "remote",
      "enabled": false,
      "url": "https://mcp.notion.com/mcp",
      "oauth": {}
    },
    "GitHub": {
      "type": "remote",
      "enabled": false,
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {file:~/.config/opencode/.secrets/github-pat}"
      }
    }
  }
}

opencode.json (Your Config)

On first install, the installer copies opencode.base.json to ~/.config/opencode/opencode.json. This file is outside the repo (it lives in ~/.config/opencode/) so you can customize it freely — git pull will never overwrite your changes.

Behavior	Detail
Auto-created	From opencode.base.json on first install
Git-ignored	Won't appear in git status or get overwritten
Freely editable	Enable MCPs, add custom ones, change plugins

Customizing

Enable a pre-installed MCP — set "enabled": true on any entry:

"Linear MCP": {
  "type": "local",
  "enabled": true,
  "command": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/mcp"]
}

Add a local MCP — specify a command:

"My Custom Tool": {
  "type": "local",
  "command": ["npx", "-y", "my-mcp-server"]
}

Add a remote MCP — specify a url and optional oauth:

"My Remote Service": {
  "type": "remote",
  "url": "https://example.com/mcp",
  "oauth": {}
}

Removing entries from opencode.json is safe — nothing in the repo references it.

Pre-installed MCPs

MCP	Default	Use
Google Chrome MCP	Always enabled	Browser automation, debugging, testing
Linear MCP	Disabled	Issue tracking (set enabled: true to turn on)
GitHub	Disabled	GitHub API access (set enabled: true, requires PAT in ~/.config/opencode/.secrets/github-pat — see setup instructions below)
Notion	Disabled	Documentation (set enabled: true, then run opencode mcp auth Notion)

Setting up GitHub MCP

GitHub MCP connects via the remote endpoint at https://api.githubcopilot.com/mcp/ using a Personal Access Token (PAT) for authentication. OAuth auto-detection is disabled ("oauth": false) because GitHub's OAuth doesn't support dynamic client registration.

1. Create a GitHub PAT

Go to github.com/settings/personal-access-tokens/new and create a fine-grained PAT with these minimal scopes:

• Metadata: Read-only
• Contents: Read and write
• Issues: Read and write
• Pull requests: Read and write

2. Store it in a secret file

The installer already created ~/.config/opencode/.secrets/github-pat for you. Just paste your PAT into it:

# Replace the placeholder with your actual PAT:
printf 'your_pat_here' > ~/.config/opencode/.secrets/github-pat
chmod 600 ~/.config/opencode/.secrets/github-pat

3. Enable in your config

In ~/.config/opencode/opencode.json, set "enabled": true:

"GitHub": {
  "type": "remote",
  "enabled": true,
  "url": "https://api.githubcopilot.com/mcp/",
  "oauth": false,
  "headers": {
    "Authorization": "Bearer {file:~/.config/opencode/.secrets/github-pat}"
  }
}

4. Verify

opencode mcp list
opencode mcp debug GitHub --log-level DEBUG

Then test it inside opencode:

List my GitHub repositories using github mcp tools.

Package Dependencies

{
  "dependencies": {
    "@opencode-ai/plugin": "1.14.50"
  }
}

The opencode plugin system and Chrome DevTools MCP integration are installed via npm:

cd ~/.config/opencode && npm install