Build a Custom AI Coding Agent with OpenCode: From Setup to Custom Agents

If you have ever wished for an AI pair programmer that runs locally, respects your privacy, and can be customized to your exact workflow, OpenCode is the tool you have been waiting for. This open-source AI coding agent operates directly in your terminal or as a desktop app, giving you full control over your development environment. In this tutorial, you will install OpenCode, configure its built-in agents, and build a custom agent tailored to your project’s needs. By the end, you will have a powerful, local AI assistant that can analyze codebases, generate tests, and automate repetitive tasks without sending your code to a third-party server.

Prerequisites

Before you begin, ensure you have the following:

• Node.js 18+ or Bun for package management
• Git installed and configured on your system
• Basic familiarity with the terminal and command-line interfaces
• An OpenAI API key or access to a compatible LLM endpoint (OpenCode supports OpenAI, Anthropic, and local models via Ollama)
• A codebase you are comfortable experimenting with (a small personal project is ideal)

Step-by-Step Guide

1. Install OpenCode

OpenCode offers multiple installation methods. For this tutorial, we will use the recommended one-liner that works on macOS, Linux, and Windows (via WSL).

curl -fsSL https://opencode.ai/install | bash

After installation, verify it works by running:

opencode --version

You should see output similar to:

opencode/0.2.5 darwin-arm64

If you prefer a package manager, you can use:

npm i -g opencode-ai@latest

2. Configure Your LLM Provider

OpenCode requires an LLM backend. The simplest option is OpenAI. Create a configuration file at ~/.opencode/config.yaml:

provider: openai
model: gpt-4o-mini
api_key: ${OPENAI_API_KEY}

Set your API key as an environment variable:

export OPENAI_API_KEY=sk-your-key-here

For local models, you can use Ollama:

provider: ollama
model: codellama:7b

3. Explore the Built-in Agents

OpenCode ships with two default agents: build and plan. Switch between them using the Tab key in the terminal UI.

• build: Full-access agent that can read, write, and execute commands. Use this for active development.
• plan: Read-only agent that analyzes code without making changes. Ideal for exploring unfamiliar codebases or planning refactors.

Start OpenCode in your project directory:

cd /path/to/your/project
opencode

You will see the terminal UI. Try asking the plan agent to explain the project structure:

@plan Describe the architecture of this project, listing all directories and their purposes.

The agent will respond with a tree-like summary and explanations, without modifying any files.

4. Build a Custom Agent

Now we will create a custom agent called test-wizard that specializes in generating unit tests. OpenCode agents are defined in a YAML configuration file. Create ~/.opencode/agents/test-wizard.yaml:

name: test-wizard
role: You are a senior QA engineer. Your only job is to write comprehensive unit tests for the code provided. You use Jest and aim for 90%+ coverage. You never modify source files, only test files.
allow_commands: false
allow_edits: true
edit_scope: tests/

This configuration:

• Assigns a specific role to the agent
• Prevents it from running arbitrary commands
• Restricts file edits to the tests/ directory only

Restart OpenCode and press Tab to cycle to your new agent. Test it by asking:

@test-wizard Write tests for the file src/utils/helpers.ts

The agent will create a corresponding test file in the tests/ directory.

5. Use the General Subagent for Complex Tasks

OpenCode includes a @general subagent that can handle multistep research tasks. This is particularly useful for understanding large codebases. For example:

@general Find all places where we handle user authentication and summarize the flow in a diagram.

The general agent will search across files, analyze patterns, and return a structured summary.

6. Integrate with Your IDE

OpenCode can be used alongside your editor. For VS Code, add a keybinding in keybindings.json to send the current file to OpenCode:

{
  "key": "ctrl+shift+o",
  "command": "workbench.action.terminal.sendSequence",
  "args": {
    "text": "opencode analyze ${file}\n"
  }
}

This launches OpenCode with the current file path, allowing you to ask questions about it immediately.

Architecture Overview

The following diagram shows how OpenCode interacts with your codebase and the LLM provider:

OpenCode routes your requests through the appropriate agent, which interacts with the file system and the LLM provider to generate responses or perform actions.

Common Pitfalls and Troubleshooting

OpenCode does not start after installation. Ensure your PATH includes the installation directory. The default location is $HOME/.opencode/bin. Add it to your shell profile:

export PATH="$HOME/.opencode/bin:$PATH"

The agent cannot access my project files. Make sure you run opencode from within the project directory. OpenCode uses the current working directory as the root.

API key errors. Verify your environment variable is set correctly and that your API key has not expired. Test with a simple curl command:

curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

Custom agent not appearing in the list. Check the YAML syntax of your agent file. Use a linter like yamllint to validate it. The file must be placed in ~/.opencode/agents/ with a .yaml extension.

Agent refuses to edit files. Review your agent’s allow_edits and edit_scope settings. The plan agent is read-only by design. Create a custom agent with allow_edits: true if you need write access.

FAQ

Can I use OpenCode with a local LLM like Llama 3? Yes. Configure the provider as ollama and specify the model name. Ensure Ollama is running locally with the model pulled.

How do I share my custom agent with my team? Place the agent YAML file in your project repository under a .opencode/agents/ directory. Team members can copy it to their local ~/.opencode/agents/ folder.

Does OpenCode support multi-file edits? Yes. The build agent can edit multiple files in a single session. For complex refactors, use the @general subagent to plan the changes first.

Is there a way to run OpenCode in non-interactive mode? Yes. Use the --execute flag followed by a command string. For example: opencode --execute "Refactor the database layer".

Next Steps

Now that you have OpenCode running with a custom agent, explore the official documentation to learn about advanced features like custom prompt templates, tool integrations, and the desktop app. Consider contributing to the OpenCode project on GitHub if you find bugs or want to add features. Your custom agents can be shared with the community, making AI-assisted development more accessible for everyone.