ddev-claude-code

A DDEV add-on that runs Claude Code (Anthropic’s official CLI) 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-workspace

Created by Robert Menetray · Sponsored by DruScan

Why this add-on?

There are several DDEV add-ons for Claude Code already available. This one was built for a specific use case and differs from the others in a few key ways:

• Multi-container orchestration. Designed to work as part of a larger AI workspace where the Claude container connects to sibling containers: a Playwright container for browser testing, a Beads container for task tracking, and access to the web container for running drush, composer, phpunit, and phpstan directly against Drupal.
• Minimal and focused. Does not bundle MCPs or extra tooling inside the container. External tools (Playwright, task tracking) run in their own dedicated containers, keeping the Claude container lightweight.
• TUI wrapper with tab titles. Includes a terminal wrapper that sets custom tab titles (project-name - task label), which is useful when juggling multiple agents or projects across several terminals.
• Desktop notifications. Supports optional host notifications (via ai-notify-bridge) when sessions or tasks complete.
• Autonomous execution ready. Pairs with ddev-ralph for autonomous task loops (planning, executing, and closing tasks overnight).

If you need a standalone Claude Code container without the multi-container setup, one of the other add-ons may be a better fit.

Quick Start

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 claude-code  # or: ddev cc

Standalone installation

If you only need Claude Code 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-claude-code
ddev restart
ddev claude-code  # or: ddev cc

This automatically installs the required dependencies:

• ddev-agents-sync: auto-syncs AI agents from git (provides CLAUDE.md)
• ddev-ai-ssh: SSH access to web container
• ddev-beads: task tracking
• ddev-playwright-mcp: browser automation

Prerequisites

• DDEV >= v1.24.10
• An Anthropic API key or OAuth session

Authentication

Run ddev claude-code and follow the prompts. Claude Code handles OAuth and API key authentication natively. No custom commands or manual file editing needed.

Credentials are stored in a shared directory on the host (~/.ddev/claude-code/ by default), so you only need to authenticate once. All your DDEV projects share the same session automatically. Credentials persist across ddev restart, new projects, and machine reboots.

Configuration

After installation, environment variables are in .ddev/.env.claude-code:

# Shared config directory (credentials, settings, and session data).
# Shared across ALL DDEV projects. Change only if you need a custom location.
HOST_CLAUDE_CONFIG_DIR=${HOME}/.ddev/claude-code

# Timezone
TZ=UTC

Note: HOST_CLAUDE_CONFIG_DIR must point to an existing directory. The installer creates ~/.ddev/claude-code/ automatically. If you change this value, make sure the directory exists before running ddev restart.

Permissions

The installer creates a default settings.json with bypassPermissions mode. All permission prompts are disabled since Claude Code runs inside an isolated DDEV container.

To change this, edit ~/.ddev/claude-code/settings.json:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Available modes: bypassPermissions (default, no prompts), auto (smart classifier), acceptEdits (auto-approve edits only), default (prompt for everything).

Since it lives in the shared config directory, permission changes apply to all DDEV projects.

Architecture

┌─────────────────────────────────────────────────┐
│              DDEV Docker Network                 │
│                                                  │
│  ┌──────────────┐     SSH       ┌────────────┐  │
│  │  Claude Code │──────────────>│    Web     │  │
│  │  Container   │               │  (Drupal)  │  │
│  └──────┬───────┘               └────────────┘  │
│         │ MCP HTTP                               │
│         v                                        │
│  ┌──────────────┐  ┌──────────────┐              │
│  │  Playwright  │  │    Beads     │              │
│  │     MCP      │  │  (bd tasks)  │              │
│  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────┘

Claude Code communicates with the web container via SSH (ssh web), giving it full CLI access to drush, composer, phpunit, phpstan, and any other tool in the web container. SSH keys are auto-generated per project in .ddev/.agent-ssh-keys/. Playwright MCP is accessed over HTTP for browser automation and visual testing.

Commands

Tab title for multi-project workflows

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 - Claude Code"
ddev claude-code

# Tab title: "mysite - Claude Code"  (explicit tui, same result)
ddev claude-code tui

# Tab title: "mysite - Fix login redirect bug"
ddev claude-code tui Fix login redirect bug

# Tab title: "mysite - TASK-42 migrate users"
ddev claude-code tui TASK-42 migrate users

This way, if you have three terminals open (two projects, two tasks), each tab shows exactly where you are and what you are doing.

Shell Helpers

Inside the container (via ddev claude-code shell), these helper functions are available:

Agents and CLAUDE.md

When ddev-agents-sync is installed (auto-installed as dependency), Claude Code automatically gets:

• 10 specialized agents in .claude/agents/ (drupal-dev, code-review, etc.)
• CLAUDE.md with Drupal development instructions in the project root
• Rules and skills for Drupal development workflows

Agent .md files use model tokens (like ${MODEL_CHEAP}) that are resolved to Claude Code aliases (like haiku) during sync. See drupal-ai-agents for the full list of agents, tokens, and customization options.

You can place your own CLAUDE.md in your Drupal project root. It won’t be overwritten if it already exists.

Customizing agents and models

To add private agents or change which models agents use, edit .ddev/.env.agents-sync:

# Add a private repo with custom agents or model overrides
AGENTS_REPOS=https://github.com/trebormc/drupal-ai-agents.git,https://github.com/your-org/private-agents.git

See Model Token System for details on changing agent models globally.

Desktop Notifications (optional)

Claude Code can send desktop notifications when sessions finish. First, install the ai-notify-bridge on your host (one-time setup):

curl -fsSL https://raw.githubusercontent.com/trebormc/ai-notify-bridge/main/install.sh | bash

Notification hooks are pre-configured in settings.json when you install the add-on. They include the project name and TUI task label automatically. Example notification title: [mysite] Fix login bug.

If you already have a settings.json from a previous install, add the hooks manually. See the install.yaml for the exact hook configuration.

If the bridge is not installed or not running, the curl call fails silently with no impact on Claude Code.

Multica integration (optional)

Multica is a managed-agents platform that lets you assign tasks to AI coding agents from a central web UI. This add-on can run the Multica daemon inside the Claude Code container so a self-hosted Multica server can delegate work to Claude Code in any of your DDEV projects.

The Multica binary is always installed in the container, but the daemon only runs when you opt in by setting a token in ~/.ddev/multica/.env.multica. With no file or an empty token, the integration stays completely dormant and the container behaves exactly as it does without Multica.

Enable (once, shared with other AI add-ons)

The Multica configuration lives in ~/.ddev/multica/.env.multica, a directory shared by every Multica-aware DDEV add-on (this one, ddev-opencode, …). One configuration enables the daemon in all of them — and across every DDEV project on the same host.

# One-time setup on your host
cp ~/.ddev/multica/.env.multica.example ~/.ddev/multica/.env.multica
$EDITOR ~/.ddev/multica/.env.multica
# Fill in MULTICA_SERVER_URL, MULTICA_APP_URL, MULTICA_TOKEN

Then in any DDEV project using a Multica-aware add-on:

ddev restart

The container’s entrypoint detects the token, logs in, and starts the daemon in the background. Each container registers as a separate Multica runtime — Claude Code containers show up as Claude Code DDEV (<project>) with device name ddev-<project>-claude-code. Watched workspaces are managed from the Multica UI (the daemon auto-subscribes to all your UI workspaces on login).

Verify

ddev claude-code shell
multica daemon status
multica agent list

You should also see the runtime appear in the Multica UI under “Agent runtimes”.

Disable

Empty the file (or delete it) and ddev restart. The entrypoint will skip the Multica section entirely.

: > ~/.ddev/multica/.env.multica

Token rotation

The Personal Access Token from Multica defaults to a 90-day expiry. When it expires, regenerate it in the Multica UI, update ~/.ddev/multica/.env.multica, and ddev restart each project where you need it.

Autonomous Execution

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

Uninstallation

ddev add-on remove ddev-claude-code
ddev restart

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 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.

License

Apache-2.0. See LICENSE.