ddev-claude-code

A DDEV add-on that runs Claude Code (Anthropic’s official CLI) in a dedicated container for AI-powered Drupal development.

Quick Start

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

# 2. Restart DDEV
ddev restart

# 3. Authenticate (choose one)
ddev claude-code claude login          # OAuth (recommended)
# OR set API key in .ddev/.env.claude-code

# 4. Launch Claude Code
ddev claude-code

Prerequisites

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

Installation

ddev add-on get trebormc/ddev-claude-code
ddev restart

This automatically installs all dependencies:

• ddev-agents-sync – auto-syncs AI agents from git (provides CLAUDE.md)
• ddev-beads – task tracking
• ddev-playwright-mcp – browser automation

Authentication

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.

Option A: OAuth login (recommended for Claude Pro/Team/Enterprise subscribers)

ddev claude-code claude login

This opens a browser for OAuth authentication. Credentials persist across ddev restart, new projects, and machine reboots.

Option B: API key

ddev dotenv set .ddev/.env.claude-code --anthropic-api-key=sk-ant-your-key-here
ddev restart

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

# API key (alternative to OAuth login)
#ANTHROPIC_API_KEY=sk-ant-...

# 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                 │
│                                                  │
│  ┌──────────────┐  docker exec  ┌────────────┐  │
│  │  Claude Code │──────────────>│    Web     │  │
│  │  Container   │               │  (Drupal)  │  │
│  └──────┬───────┘               └────────────┘  │
│         │ MCP HTTP                               │
│         v                                        │
│  ┌──────────────┐  ┌──────────────┐              │
│  │  Playwright  │  │    Beads     │              │
│  │     MCP      │  │  (bd tasks)  │              │
│  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────┘

Claude Code 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 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:

• 13 specialized agents in .claude/agents/ (drupal-dev, three-judges, 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

Claude Code can send desktop notifications when sessions finish. Add a stop hook to .claude/settings.json:

{
  "hooks": {
    "stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://host.docker.internal:5454/notify -H 'Content-Type: application/json' -d '{\"title\":\"Claude Code\",\"message\":\"Session finished\"}'"
          }
        ]
      }
    ]
  }
}

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