ddev-opencode

A DDEV add-on that runs OpenCode in a dedicated container for AI-powered Drupal development.

Agents, rules, and skills for Drupal development are automatically synced from drupal-ai-agents via ddev-agents-sync – no manual git clone needed.

Quick Start

# 1. Install the add-on
ddev add-on get trebormc/ddev-opencode

# 2. Restart DDEV
ddev restart

# 3. Set up credentials (choose one)
# Option A: If ddev-claude-code is installed, OAuth credentials are synced automatically
# Option B: Create auth.json manually (see Authentication section below)

# 4. Launch OpenCode
ddev opencode

Prerequisites

• DDEV >= v1.23.5
• An API key (Anthropic, OpenAI, or a LiteLLM proxy)

Installation

ddev add-on get trebormc/ddev-opencode
ddev restart

This automatically installs all dependencies:

• ddev-agents-sync – auto-syncs AI agents from git
• ddev-beads – task tracking
• ddev-playwright-mcp – browser automation

Authentication

Option A – Automatic sync from Claude Code (recommended):

If ddev-claude-code is installed, OAuth credentials are synced automatically every 60 seconds. Just run ddev claude-code claude login once and OpenCode will pick up the credentials.

Option B – Manual auth.json:

Create ~/.ddev/opencode/auth/auth.json:

{
  "anthropic": {
    "type": "oauth",
    "access": "sk-ant-oat01-YOUR_ACCESS_TOKEN",
    "refresh": "sk-ant-ort01-YOUR_REFRESH_TOKEN",
    "expires": 0
  }
}

Credentials are stored in a shared directory on the host (~/.ddev/opencode/auth/ by default), so you only need to configure them once – all your DDEV projects share the same credentials automatically.

Configuration

After installation, environment variables are in .ddev/.env.opencode:

# Shared OpenCode directory for credentials and config.
# Shared across ALL DDEV projects. Change only if you need a custom location.
# Subdirectories: auth/ (credentials), config/ (opencode.json, custom overrides)
HOST_OPENCODE_DIR=${HOME}/.ddev/opencode

# Claude Code config directory (for automatic OAuth credential sync)
HOST_CLAUDE_CONFIG_DIR=${HOME}/.ddev/claude-code

# Timezone
TZ=UTC

Agent Configuration

Agents, rules, and skills are automatically synced from drupal-ai-agents via ddev-agents-sync. No manual setup is needed.

The sync process resolves model tokens (like ${MODEL_CHEAP}) to OpenCode model names (like anthropic/claude-haiku-4-5) using the .env.agents file from the agent repository. See drupal-ai-agents for details on model tokens and customization.

To customize which repos are synced, edit .ddev/.env.agents-sync:

# Sync from multiple repos (later repos override earlier ones)
AGENTS_REPOS=https://github.com/trebormc/drupal-ai-agents.git,https://github.com/your-org/private-agents.git

To manually trigger an update: ddev agents-update

Changing agent models

To change which AI models your agents use, override the .env.agents file. Create a private git repo with just an .env.agents and add it as a second entry:

AGENTS_REPOS=https://github.com/trebormc/drupal-ai-agents.git,https://github.com/your-org/my-config.git

See Model Token System for the full list of tokens and how to customize them.

Local config override

To use a custom opencode.json (e.g., to add a LiteLLM proxy or change global permissions), place it in ~/.ddev/opencode/config/opencode.json. It takes precedence over the default from the agent repository. Agents, rules, and skills are always loaded from the synced volume regardless.

Architecture

┌─────────────────────────────────────────────────┐
│              DDEV Docker Network                 │
│                                                  │
│  ┌──────────────┐  docker exec  ┌────────────┐  │
│  │   OpenCode   │──────────────>│    Web     │  │
│  │  Container   │               │  (Drupal)  │  │
│  └──────┬───────┘               └────────────┘  │
│         │ MCP HTTP                               │
│         v                                        │
│  ┌──────────────┐  ┌──────────────┐              │
│  │  Playwright  │  │    Beads     │              │
│  │     MCP      │  │  (bd tasks)  │              │
│  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────┘

OpenCode communicates with the web container via docker exec (through the mounted Docker socket), giving it full CLI access to drush, composer, phpunit, phpstan, and any other tool in the web container. Playwright MCP is accessed over HTTP for browser automation and visual testing.

Commands

Shell Helpers

Inside the container (via ddev opencode shell), these helper functions are available:

Desktop Notifications

OpenCode can send desktop notifications when tasks complete or need attention. If you use drupal-ai-agents, the notification configuration is included by default.

To receive notifications, start the notification bridge on your host:

./scripts/start-notify-bridge.sh

See the DDEV AI workspace for full notification setup details.

Autonomous Execution

For autonomous task execution (overnight runs), see ddev-ralph.

Part of DDEV AI Workspace

This add-on is part of DDEV AI Workspace, a modular ecosystem of DDEV add-ons for AI-powered Drupal development.

Disclaimer

This project is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors – always review changes before deploying to production. See menetray.com for more information and DruScan for Drupal auditing tools.

License

Apache-2.0. See LICENSE.