ddev-agents-sync

A DDEV add-on that automatically syncs AI agent repositories and generates tool-specific configurations for OpenCode and Claude Code.

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

What problem does this solve? AI tools like OpenCode and Claude Code each expect agent configurations in a different format. This add-on lets you write agents once (using a shared “fat frontmatter” format) and automatically generates the correct configuration for each tool. It also resolves model tokens, so the same agent definition can use different models depending on the tool.

On every ddev start, this container clones or updates the configured repositories, resolves model aliases, and produces two separate agent directories (one optimized for each AI tool).

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

This add-on is also automatically installed as a dependency when you install ddev-opencode or ddev-claude-code. You rarely need to install it directly.

Standalone installation

If you need to install it individually (requires familiarity with the DDEV add-on ecosystem):

ddev add-on get trebormc/ddev-agents-sync
ddev restart

OpenCode and Claude Code will automatically pick up the synced agents.

Prerequisites

• DDEV >= v1.24.10

Configuration

Edit .ddev/.env.agents-sync:

# Comma-separated list of git repositories to sync
# Later repos override earlier ones (useful for private overrides)
AGENTS_REPOS=https://github.com/trebormc/drupal-ai-agents.git

# Set to "false" to disable automatic sync on ddev start
AGENTS_AUTO_UPDATE=true

Multiple repos (public + private override)

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

Files from later repos override earlier ones. This lets you use the public Drupal agents as a base and add (or replace) specific agents/skills from a private repo.

How It Works

On ddev start:
  ┌──────────────────────────────────────────────────────────────────┐
  │  agents-sync container                                          │
  │                                                                  │
  │  1. Clone/update each repo in AGENTS_REPOS                      │
  │                                                                  │
  │  2. Merge all repos into /tmp/agents-merged (later repos win)   │
  │                                                                  │
  │  3. Read .env.agents (model alias → real model name mapping)     │
  │                                                                  │
  │  4. Generate /agents-opencode/                                   │
  │     - envsubst: ${MODEL_CHEAP} → opencode/gpt-5-nano            │
  │     - Keeps OpenCode frontmatter (mode, tools object, permission)│
  │     - Removes allowed_tools line                                 │
  │     - Copies opencode.json.example, notifier config, etc.       │
  │                                                                  │
  │  5. Generate /agents-claude/                                     │
  │     - envsubst: ${MODEL_CHEAP} → haiku                          │
  │     - Converts frontmatter to Claude Code format                 │
  │     - Renames allowed_tools → tools (CSV)                        │
  │     - Removes mode, temperature, maxSteps, tools, permission     │
  │                                                                  │
  │  6. Sleep (stay alive for depends_on)                            │
  └──────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────┐  ┌─────────────────────────┐
  │       OpenCode          │  │      Claude Code        │
  │  reads /agents-opencode │  │  reads /agents-claude   │
  │      (read-only)        │  │      (read-only)        │
  └─────────────────────────┘  └─────────────────────────┘

The output directories are Docker named volumes (ddev-{sitename}-agents-opencode and ddev-{sitename}-agents-claude). They persist between restarts and are not visible on the host filesystem.

Merge strategy

Files are copied from each repo in order. The merge is a simple file-level override:

• .claude/agents/*.md: merged (later repos can add or override agents)
• .claude/skills/*/SKILL.md: merged (later repos can add or override skills)
• .claude/rules/*.md: merged (later repos can add or override rules)
• .env.agents: overridden by the last repo that provides it
• CLAUDE.md, opencode.json.example: overridden by the last repo

Model Token System

Agent .md files use model tokens instead of hardcoded model names. This allows the same agent definition to work with both OpenCode and Claude Code, and makes it easy to change models globally.

Available tokens

How tokens are resolved

The .env.agents file in the agent repository defines the mapping:

# OpenCode models (provider/model-id format)
OC_MODEL_SMART=opencode/kimi-k2.5
OC_MODEL_NORMAL=opencode/minimax-m2.5
OC_MODEL_CHEAP=opencode/gpt-5-nano
OC_MODEL_APPLIER=opencode/gpt-5-nano

# Claude Code models (native aliases)
CC_MODEL_SMART=opus
CC_MODEL_NORMAL=sonnet
CC_MODEL_CHEAP=haiku
CC_MODEL_APPLIER=haiku

During sync, envsubst replaces the tokens with the appropriate values for each tool.

Changing models

To change which models your agents use:

1. For all projects: Fork drupal-ai-agents, edit .env.agents, and point AGENTS_REPOS to your fork.

2. Per project: Create a private repo with just an .env.agents file and add it as a second repo:

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

   The .env.agents from your repo will override the public one.

Writing agents with tokens

If you create custom agents in your own repository, use the same tokens in the frontmatter:

---
description: My custom agent for code review.
model: ${MODEL_SMART}
mode: subagent
tools:
  read: true
  glob: true
  grep: true
  bash: false
permission:
  bash: deny
allowed_tools: Read, Glob, Grep
---

Your agent prompt here...

The sync script will automatically substitute the tokens when generating configs for each tool. See Fat Frontmatter for the full format.

Fat Frontmatter

Agent .md files use a “fat frontmatter” format that contains configuration for both OpenCode and Claude Code. Each tool reads the fields it understands and ignores the rest:

---
description: Short description of what this agent does.
model: ${MODEL_CHEAP}                  # Token, replaced by sync

# OpenCode fields (Claude Code ignores these)
mode: subagent                          # primary or subagent
temperature: 0.1                        # optional
tools:                                  # tool availability (YAML object)
  read: true
  glob: true
  grep: true
  bash: false
  write: false
  edit: false
permission:                             # permission policy
  bash: deny

# Claude Code field (OpenCode ignores this, sync renames to "tools:")
allowed_tools: Read, Glob, Grep         # tool availability (CSV)
---

Agent system prompt content...

During sync:

• For OpenCode: the allowed_tools: line is removed. Everything else stays.
• For Claude Code: mode:, temperature:, maxSteps:, tools: (object), and permission: are removed. allowed_tools: is renamed to tools:.

Commands

ddev agents-update

Manually trigger a sync without restarting DDEV:

ddev agents-update

Uninstallation

ddev add-on remove ddev-agents-sync
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.