OpenCode Setup

February 3, 2026 ยท View on GitHub

Configure OpenCode for AI-assisted Algorand development.

Note: These instructions are for per-project setup. For global configuration (~/.config/opencode/opencode.json), refer to the OpenCode documentation.

Prerequisites

  • AlgoKit installed
  • OpenCode installed
  • GitHub Personal Access Token (PAT) with expiration date

Setup Steps

1. Clone or Download This Repository

git clone https://github.com/algorand-devrel/algorand-agent-skills.git
cd algorand-agent-skills

2. Copy Files to Your Project

# From your AlgoKit project directory:

# Copy skills
cp -r /path/to/algorand-agent-skills/skills ./

# Copy AGENTS.md (or merge with existing)
cp /path/to/algorand-agent-skills/setups/AGENTS.md ./

# Copy OpenCode config
cp /path/to/algorand-agent-skills/setups/opencode/opencode.json ./

3. Set GitHub Token Environment Variable

The config uses {env:GITHUB_TOKEN} syntax to read your token from an environment variable:

{
  "mcp": {
    "github": {
      "headers": {
        "Authorization": "Bearer {env:GITHUB_TOKEN}"
      }
    }
  }
}

Set the environment variable before running OpenCode:

export GITHUB_TOKEN="github_pat_abc123..."

To make this permanent, add to your shell profile (~/.bashrc, ~/.zshrc, etc.).

PAT Requirements:

4. Authenticate Kapa MCP

The Kapa MCP uses OAuth authentication. On first use, OpenCode will prompt you to authorize access to Algorand documentation.

Files to Copy

SourceDestinationRequired
skills/./skills/Yes
setups/AGENTS.md./AGENTS.mdYes (or merge)
setups/opencode/opencode.json./opencode.jsonYes

AGENTS.md Note

If you already have an AGENTS.md: Merge the content from setups/AGENTS.md into your existing file.

If you don't have one: Copy setups/AGENTS.md to your project root as AGENTS.md.

Verifying Setup

  1. Start OpenCode in your project directory:

    opencode

  2. Test the Kapa MCP:

    Search for "GlobalState" in Algorand docs

  3. Test the GitHub MCP:

    Get the contents of algorandfoundation/puya-ts/examples/hello_world_arc4/contract.algo.ts

  4. Test a skill:

    Create a new smart contract that stores a counter

Troubleshooting

MCP tools not available

  • Verify opencode.json is in your project root
  • Check JSON syntax is valid
  • Restart OpenCode after config changes

GitHub authentication failed

  • Verify GITHUB_TOKEN environment variable is set
  • Verify your PAT has an expiration date
  • Check the PAT hasn't expired

Kapa OAuth issues

  • Run opencode mcp auth to re-authenticate
  • Check your network connection

Resources