A DDEV add-on that runs OpenCode in a dedicated container for AI-powered Drupal development.
Part of DDEV AI Workspace — a modular ecosystem of DDEV add-ons for AI-powered Drupal development. Install the full stack with one command:
ddev add-on get trebormc/ddev-ai-workspaceCreated by Robert Menetray · Sponsored by DruScan
Agents, rules, and skills for Drupal development are automatically synced from drupal-ai-agents via ddev-agents-sync. No manual git clone needed.
The recommended way to install this add-on is through the DDEV AI Workspace, which installs all tools and dependencies with a single command:
ddev add-on get trebormc/ddev-ai-workspace
ddev restart
ddev opencode # or: ddev ocIf you only need OpenCode without the rest of the workspace, you can install it individually. This requires familiarity with the DDEV add-on ecosystem and its dependencies:
ddev add-on get trebormc/ddev-opencode
ddev restart
ddev opencode # or: ddev ocThis automatically installs the required dependencies:
- ddev-agents-sync: auto-syncs AI agents from git
- ddev-beads: task tracking
- ddev-playwright-mcp: browser automation
- DDEV >= v1.24.10
- An API key (Anthropic, OpenAI, or a LiteLLM proxy)
Run ddev opencode and follow the prompts. OpenCode handles authentication natively. No custom commands or manual file editing needed.
Credentials are stored in a shared file on the host (~/.ddev/opencode/auth.json by default), so you only need to authenticate once. All your DDEV projects share the same credentials automatically.
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.
# Files: auth.json (credentials), config/ (opencode.json, custom overrides)
HOST_OPENCODE_DIR=${HOME}/.ddev/opencode
# Timezone
TZ=UTCAgents, 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 opencode/gpt-5-nano) 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.gitTo manually trigger an update: ddev agents-update
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.gitSee Model Token System for the full list of tokens and how to customize them.
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.
┌─────────────────────────────────────────────────┐
│ 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.
| Command | Description |
|---|---|
ddev opencode |
Launch the OpenCode TUI |
ddev oc |
Alias for ddev opencode |
ddev opencode tui |
Launch TUI (same as above) |
ddev opencode tui Fix login bug |
Launch TUI with a custom tab title |
ddev opencode shell |
Open a bash shell in the container |
ddev opencode <command> |
Run any command in the container |
When working on multiple DDEV projects at the same time, it can be hard to tell which terminal belongs to which project. The tui subcommand sets the terminal tab title to project-name - custom text, so you can identify each terminal at a glance.
The project name (DDEV_SITENAME) is always included automatically. If you add extra text after tui, it appears as a label. Useful for describing the task you are working on in that terminal.
# Tab title: "mysite - OpenCode"
ddev opencode
# Tab title: "mysite - OpenCode" (explicit tui, same result)
ddev opencode tui
# Tab title: "mysite - Fix login redirect bug"
ddev opencode tui Fix login redirect bug
# Tab title: "mysite - TASK-42 migrate users"
ddev opencode tui TASK-42 migrate usersThis way, if you have three terminals open (two projects, two tasks), each tab shows exactly where you are and what you are doing.
Inside the container (via ddev opencode shell), these helper functions are available:
| Helper | Description |
|---|---|
drush |
Run drush commands in the web container |
composer |
Run composer in the web container |
web-exec |
Execute any command in the web container |
web-shell |
Open an interactive shell in the web container |
bd |
Run Beads task tracking commands |
OpenCode can send desktop notifications when tasks complete or need attention. Notifications are pre-configured via opencode-notifier.json (ships with drupal-ai-agents). No setup needed inside the container.
To receive notifications, install the ai-notify-bridge on your host (one-time setup):
curl -fsSL https://raw.githubusercontent.com/trebormc/ai-notify-bridge/main/install.sh | bashIf the bridge is not installed or not running, OpenCode works normally. Notification calls fail silently with no impact.
For autonomous task execution (overnight runs), see ddev-ralph.
ddev add-on remove ddev-opencode
ddev restartThis add-on is part of DDEV AI Workspace, a modular ecosystem of DDEV add-ons for AI-powered Drupal development.
| Repository | Description | Relationship |
|---|---|---|
| ddev-ai-workspace | Meta add-on that installs the full AI development stack with one command. | Workspace |
| ddev-claude-code | Claude Code CLI container for interactive development. | Alternative AI tool |
| ddev-ralph | Autonomous AI task orchestrator. Delegates work to this container or Claude Code via docker exec. |
Uses this as backend |
| ddev-playwright-mcp | Headless Playwright browser for browser automation and visual testing. | Auto-installed dependency |
| ddev-beads | Beads git-backed task tracker shared by all AI containers. | Auto-installed dependency |
| ddev-agents-sync | Auto-syncs AI agent repositories into a shared Docker volume. Provides agents and config. | Auto-installed dependency |
| drupal-ai-agents | 13 agents, 4 rules, 14 skills for Drupal development. Synced automatically via ddev-agents-sync. | Agent configuration |
This project is an independent initiative by Robert Menetray, sponsored by DruScan. It is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors. Always review changes before deploying to production.
Apache-2.0. See LICENSE.