OpenCode.ai: AI-Powered Development Workflow Guide

9/25/2025

🧭 Overview

This guide walks through using OpenCode.ai as an AI-powered development workflow tool that integrates with GitHub Copilot and Anthropic models. OpenCode provides intelligent agents for planning, coding, testing, documentation, and quality assurance, streamlining feature development through automated workflows.

📋 Prerequisites

  • Node.js (v18 or higher)
  • GitHub account with Copilot subscription
  • Anthropic Claude Pro/Max account (recommended for cost-effectiveness)
  • Terminal access

🚀 Installation

Install opencode globally via npm:

npm install -g opencode-ai

Alternative installation methods:

# Using bun
bun install -g opencode-ai

# Using Homebrew (macOS)
brew install sst/tap/opencode

# Using paru (Arch Linux)
paru -S opencode-bin

⚙️ Initial Setup

1. Authentication Setup

OpenCode requires authentication with your AI providers. Run the auth login command to begin:

opencode auth login

For Anthropic (Recommended):

  • Select "Anthropic" from the provider list
  • Browser will open for OAuth authentication
  • Sign in with your Claude Pro/Max account
  • Authorization is stored securely in ~/.local/share/opencode/auth.json

For GitHub Copilot:

  • Select "GitHub Copilot" from the provider list
  • Navigate to the provided GitHub device authorization URL
  • Enter the displayed code to authorize access
  • This leverages your existing GitHub Copilot subscription

For Multiple Providers: You can authenticate with multiple providers and switch between them as needed.

2. Model Selection

After authentication, configure your preferred models:

opencode

Then run the /models command within the TUI to:

  • View available models from authenticated providers
  • Select default models for different agent types
  • Switch between GitHub Copilot models (GPT-4, Claude 3.5 Sonnet, Gemini 1.5 Pro)
  • Access Anthropic models (Claude Sonnet, Claude Opus)

3. Project Initialization

Navigate to your project directory and initialize opencode:

cd /path/to/your/project
opencode /init

This creates:

  • .opencode/ directory with project-specific configuration
  • Agent configurations based on your project structure
  • Integration with existing package.json and framework settings

🤖 Agent Configuration

Agent Storage Approaches

OpenCode supports two primary approaches for storing agent configurations:

  • Project-specific agents: Stored in .opencode/agents/ within each project
  • Global agents: Stored in ~/.config/opencode/agent/ for reuse across projects

For agents you want to reuse across multiple projects, store them globally in your user configuration directory. This approach offers several advantages:

Benefits:

  • Reuse agents across all projects
  • Centralized configuration management
  • Version control your personal agent library
  • Share agent configurations with team members
  • Easier maintenance and updates

Directory Structure:

~/.config/opencode/
├── agent/
│   ├── task-manager.md
│   ├── coder-agent.md
│   ├── tester.md
│   ├── reviewer.md
│   └── subagents/
│       ├── documentation.md
│       └── quality.md
├── config.json
└── workflows/
    └── feature-development.json

Creating Custom Agents

Whether stored globally or per-project, each agent requires a configuration file that defines its role, capabilities, and behavior. The markdown format provides better readability and easier maintenance.

Task Manager Agent Configuration (Markdown Format)

Create ~/.config/opencode/agent/task-manager.md:

---
name: task-manager
description: Plans and breaks down features into actionable tasks
model: claude-3-5-sonnet
temperature: 0.2
maxTokens: 8000
---

# Task Manager Agent

You are a technical project manager and software architect. Your role is to analyze feature requests and break them down into detailed, actionable development tasks.

## Core Responsibilities

- Analyze requested features thoroughly
- Identify all files that need to be created or modified  
- Break down work into logical, sequential steps
- Consider dependencies between tasks
- Provide clear acceptance criteria for each task
- Suggest optimal development workflow
- Include considerations for testing and documentation

## Context Files

Include these file patterns for analysis:
- `package.json`
- `src/**/*.{js,jsx,ts,tsx}`
- `components/**/*.{js,jsx,ts,tsx}`
- `pages/**/*.{js,jsx,ts,tsx}`
- `routes/**/*.{js,jsx,ts,tsx}`
- `README.md`

## Output Format

Structure your response with these sections:

### Overview
Brief summary of the feature and its purpose

### Tasks
Detailed breakdown of implementation steps:
1. **Task Name**: Clear description
   - Files to modify: `path/to/file.js`
   - Acceptance criteria: What defines completion
   - Dependencies: What must be done first

### Dependencies
Task ordering and relationships

### Considerations  
- Testing requirements
- Documentation needs
- Potential challenges
- Performance implications

Coder Agent Configuration (Markdown Format)

Create ~/.config/opencode/agent/coder-agent.md:

---
name: coder-agent
description: Implements code changes based on task manager plans
model: gpt-4-turbo
temperature: 0.1
maxTokens: 12000
capabilities:
  - file_creation
  - file_modification
  - code_generation
  - refactoring
---

# Coder Agent

You are an expert software developer. Your role is to implement code changes based on detailed plans from the task manager.

## Implementation Guidelines

- Read and understand the task manager's implementation plan
- Implement code changes following existing patterns and conventions
- Ensure proper error handling and edge case coverage
- Write self-documenting code with clear variable and function names
- Follow the project's coding standards and style guide
- Create reusable and modular components where appropriate
- Maintain consistency with existing codebase architecture

## Context Files

Include these patterns for implementation context:
- `src/**/*.{js,jsx,ts,tsx,css,scss}`
- `components/**/*.{js,jsx,ts,tsx,css,scss}`
- `styles/**/*.{css,scss,less}`
- `types/**/*.{ts,d.ts}`
- `package.json`
- `tsconfig.json`
- `.eslintrc*`

## Code Quality Standards

### Error Handling
- Implement comprehensive error boundaries
- Provide meaningful error messages
- Handle edge cases gracefully

### Code Style  
- Follow existing project conventions
- Use consistent naming patterns
- Maintain proper indentation and formatting
- Write clear, descriptive comments for complex logic

### Component Structure
```javascript
// Example component structure
import React from 'react';
import PropTypes from 'prop-types';

const ComponentName = ({ prop1, prop2 }) => {
  // Component logic here
  
  return (
    // JSX here
  );
};

ComponentName.propTypes = {
  prop1: PropTypes.string.required,
  prop2: PropTypes.func
};

export default ComponentName;
```

Tester Agent Configuration (Markdown Format)

Create ~/.config/opencode/agent/tester.md:

---
name: tester
description: Creates comprehensive tests for implemented features
model: claude-3-5-sonnet
temperature: 0.15
maxTokens: 10000
testFrameworks:
  unit: jest
  integration: jest
  e2e: cypress
  component: react-testing-library
coverage:
  threshold: 80
  includeStatements: true
  includeBranches: true
  includeFunctions: true
---

# Tester Agent

You are a quality assurance engineer and test automation expert. Your role is to create comprehensive test suites that ensure code reliability and maintain high coverage.

## Testing Strategy

### Unit Tests
- Test individual components and functions in isolation
- Mock external dependencies
- Cover all branches and edge cases
- Use descriptive test names that explain the scenario

### Integration Tests  
- Test component interactions
- Verify data flow between components
- Test API integrations
- Validate user workflows

### Test Structure
```javascript
describe('ComponentName', () => {
  describe('when prop X is provided', () => {
    it('should render expected content', () => {
      // Test implementation
    });
    
    it('should handle user interaction correctly', () => {
      // Test implementation  
    });
  });
  
  describe('error scenarios', () => {
    it('should display error message when API fails', () => {
      // Test implementation
    });
  });
});
```

## Context Files

Include these patterns for test creation:
- `src/**/*.{js,jsx,ts,tsx}`
- `test/**/*.{js,jsx,ts,tsx}`
- `tests/**/*.{js,jsx,ts,tsx}`
- `__tests__/**/*.{js,jsx,ts,tsx}`
- `*.test.{js,jsx,ts,tsx}`
- `*.spec.{js,jsx,ts,tsx}`
- `jest.config.*`
- `vitest.config.*`
- `cypress.config.*`

## Testing Best Practices

- **Arrange, Act, Assert**: Structure tests clearly
- **Test behavior, not implementation**: Focus on what the component does
- **Use realistic test data**: Mirror production scenarios
- **Test edge cases**: Empty states, error conditions, boundary values
- **Keep tests isolated**: Each test should be independent
- **Provide clear failure messages**: Make debugging easier

Global Configuration

Create ~/.config/opencode/config.json for global settings:

{
  "$schema": "https://opencode.ai/config.json",
  "defaults": {
    "model": "claude-3-5-sonnet",
    "temperature": 0.2,
    "maxTokens": 8000
  },
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    },
    "github": {
      "models": {
        "gpt-4-turbo": {},
        "claude-3-5-sonnet": {},
        "gemini-1-5-pro": {}
      }
    }
  },
  "agents": {
    "task-manager": {
      "model": "claude-3-5-sonnet",
      "temperature": 0.2
    },
    "coder-agent": {
      "model": "gpt-4-turbo", 
      "temperature": 0.1
    },
    "tester": {
      "model": "claude-3-5-sonnet",
      "temperature": 0.15
    },
    "documentation": {
      "model": "claude-3-5-sonnet",
      "temperature": 0.3
    },
    "quality": {
      "model": "claude-3-5-sonnet",
      "temperature": 0.1
    },
    "reviewer": {
      "model": "claude-3-opus",
      "temperature": 0.05
    }
  }
}

Creating Agent Workflows

Create workflow chains to automate the entire sequence in either location:

Global workflow - ~/.config/opencode/workflows/feature-development.json:

{
  "$schema": "https://opencode.ai/workflow.json",
  "name": "feature-development",
  "description": "Complete feature development workflow",
  "agents": [
    {
      "name": "task-manager",
      "waitForCompletion": true,
      "stopOnFailure": true
    },
    {
      "name": "coder-agent", 
      "waitForCompletion": true,
      "stopOnFailure": true
    },
    {
      "name": "tester",
      "waitForCompletion": true,
      "stopOnFailure": false
    },
    {
      "name": "documentation",
      "waitForCompletion": true, 
      "stopOnFailure": false
    },
    {
      "name": "quality",
      "waitForCompletion": true,
      "stopOnFailure": false
    },
    {
      "name": "reviewer",
      "waitForCompletion": true,
      "stopOnFailure": false
    }
  ],
  "onFailure": "continue_with_warnings",
  "outputSummary": true
}

Run workflows:

# Run global workflow
opencode workflow feature-development

# Run project-specific workflow
opencode workflow custom-feature

# List available workflows
opencode --list-workflows

🔄 Agent Workflow Overview

OpenCode orchestrates development through specialized agents:

  1. Task Manager Agent: Plans and breaks down features into actionable tasks
  2. Coder Agent: Implements code changes based on the plan
  3. Tester Agent: Creates and runs tests for the implemented features
  4. Documentation Agent: Updates relevant documentation
  5. Quality Agent: Reviews code quality, standards, and best practices
  6. Reviewer Agent: Performs final review and validation

🛠️ Feature Development Walkthrough

This example demonstrates adding a navigation item that links to a "Coming Soon" page.

Step 1: Planning with Task Manager

Start the task manager agent to plan your feature:

opencode task-manager

Prompt the agent:

Plan feature to: Add a navigation item to the main navigation that links to a new page displaying "This page is coming soon"

The task manager will:

  • Analyze your project structure
  • Identify files that need modification
  • Create a step-by-step implementation plan
  • Break down the feature into discrete tasks
  • Suggest the optimal sequence of changes

Expected Output:

  • Navigation component modifications
  • New route/page creation
  • Styling considerations
  • Integration points with existing navigation

Step 2: Implementation with Coder Agent

Run the coder agent to implement the planned changes:

opencode coder-agent

The coder agent will:

  • Read the task manager's plan
  • Modify navigation components to add the new menu item
  • Create the "Coming Soon" page component
  • Update routing configuration
  • Apply consistent styling and structure
  • Handle framework-specific implementation details

Files typically modified:

  • Navigation component (Header/Navbar)
  • Router configuration
  • New page component
  • Style files if needed

Step 3: Testing with Tester Agent

Ensure your changes work correctly with the tester agent:

opencode tester

The tester agent will:

  • Create unit tests for the new navigation item
  • Test the new page component
  • Verify navigation functionality
  • Run existing test suites to ensure no regressions
  • Generate integration tests if applicable
  • Provide test coverage reports

Step 4: Quality Review

Run quality checks with the quality agent:

opencode quality

The quality agent reviews:

  • Code style and formatting consistency
  • Adherence to project conventions
  • Performance implications
  • Accessibility considerations
  • Security best practices
  • Architecture alignment

Step 5: Final Review

Complete the workflow with the reviewer agent:

opencode reviewer

The reviewer agent:

  • Validates all previous agent outputs
  • Ensures cohesive implementation
  • Checks for potential conflicts
  • Provides comprehensive change summary
  • Suggests any final optimizations

🎯 Model Management

Changing Models Mid-Development

You can switch models during development for different tasks:

# Access model selection within TUI
/models

# Or specify model for specific agent
opencode coder-agent --model claude-3-5-sonnet
opencode tester --model gpt-4-turbo

Provider-Specific Benefits

GitHub Copilot Models:

  • Excellent code completion and generation
  • Strong integration with GitHub repositories
  • Access to GPT-4, Claude 3.5 Sonnet, Gemini 1.5 Pro
  • Context-aware suggestions based on repository

Anthropic Models:

  • Superior reasoning and planning capabilities
  • Excellent for complex refactoring tasks
  • Strong code review and quality analysis
  • Cost-effective with Pro/Max subscriptions

⚙️ Advanced Configuration

Model Selection Guidelines

  • Task Manager: Claude Sonnet/Opus for strategic planning and architecture
  • Coder Agent: GitHub Copilot models for repository-aware code generation
  • Tester: Claude Sonnet for comprehensive test scenarios
  • Documentation: Claude Sonnet for clear, detailed explanations
  • Quality: Claude Sonnet for thorough code analysis
  • Reviewer: Claude Opus for comprehensive final review

Temperature Settings

  • Lower (0.05-0.15): For precise tasks like code generation and final review
  • Medium (0.2-0.3): For balanced creativity in planning and documentation
  • Higher (0.3-0.5): For creative problem-solving (rarely needed)

Context Window Optimization

  • Include only relevant file patterns in includeFiles
  • Use maxTokens to control context size and response speed
  • Prioritize recently modified files and direct dependencies

🚀 Default Build and Plan Agents

Use the built-in default build and plan agents when you need to do something quick or ask general questions. Be specific and try to generate manageable changes. If you get carried away, the MR will be ridiculous and coderabbit will drive you bonkers.

Run default workflows by using the <tab> in the TUI or:

# Default build workflow
opencode build

# Default planning workflow  
opencode plan

# Custom workflow chains
opencode workflow --chain "plan,coder-agent,tester"

📊 Sessions

By typing /sessions in the TUI you can see a list of your project sessions. These are useful if you are in the middle of a change but need to take a break or a day off which you are allowed to do. Sometimes twice a week. You can even share sessions and send a link to a colleague to collaborate on a project. Shared links look like: https://opencode.ai/s/MkdPBLiH

💡 Best Practices

Workflow Optimization

  • Always start with task-manager for complex features
  • Use appropriate models for each agent type
  • Run quality checks before final review
  • Maintain consistent agent sequence for reliability

Model Selection Guidelines

  • Planning/Architecture: Claude Opus or Sonnet for complex reasoning
  • Code Generation: GitHub Copilot models for repository context
  • Testing: GPT-4 for comprehensive test coverage
  • Documentation: Claude models for clear, detailed explanations
  • Quality Review: Anthropic models for thorough analysis

Project Integration

  • Initialize opencode in project root for optimal context
  • Ensure .opencode/ directory is in version control
  • Configure agents based on project stack and requirements
  • Use consistent model selection across team members

🔧 Troubleshooting

Authentication Issues

  • Verify credentials in ~/.local/share/opencode/auth.json
  • Re-run opencode auth login to refresh tokens
  • Check provider service status and rate limits

Model Availability

  • Ensure your subscription includes requested models
  • Verify provider authentication is current
  • Check model deprecation notices
  • Use <provider-id>/<model-id> syntax as described at models.dev

Agent Performance

  • Adjust temperature settings for more/less creative output
  • Increase context window for complex projects
  • Consider model capabilities for specific tasks

🎉 Conclusion

OpenCode.ai provides a powerful AI-driven development workflow that can significantly accelerate feature development while maintaining code quality. The combination of GitHub Copilot and Anthropic models offers the best of both worlds: repository-aware code generation and sophisticated reasoning capabilities.

Regular use of the complete agent workflow ensures consistent, well-tested, and documented code changes that integrate seamlessly with your existing codebase.