Multi-adapter projects

Run Claude Code, Codex CLI, and GitHub Copilot CLI side-by-side in one project — with shared documentation, task graph, and decision memory.

How three engines coexist

Each adapter owns a dedicated engine directory. The user-owned docs/ tree, the agent-written agent-artifacts/, and (optionally) Beads are shared — so a change planned in Claude Code is visible to Codex and Copilot too.

flowchart TB classDef engine fill:#eff6ff,stroke:#2563eb; classDef shared fill:#f0fdf4,stroke:#15803d; subgraph proj ["your project root"] direction TB subgraph engines ["adapter-owned (one per CLI)"] direction LR cc[".claude/
Claude Code"]:::engine cx[".codex/
Codex CLI"]:::engine cp[".copilot/
Copilot CLI"]:::engine end subgraph sharedT ["shared (one copy, all adapters read)"] direction LR DOCS[docs/]:::shared ART[agent-artifacts/]:::shared BD[.beads/]:::shared AIDO[.aido/]:::shared end end cc -. reads .-> sharedT cx -. reads .-> sharedT cp -. reads .-> sharedT

Figure 1. Three engines, one shared backbone. Every adapter writes its own engine tree; nothing outside the engine tree is duplicated.

When you want this

Your team uses more than one AI coding CLI.
You want individual developers to pick their preferred tool while keeping the workflow consistent.
You want CI to run one tool while developers use another.

Bootstrap

shell

npx aidokit@alpha init --adapter claude-code,codex,copilot

Or add adapters to an existing single-adapter project:

shell

npx aidokit add adapter codex --conformance minimum
npx aidokit add adapter copilot --conformance minimum

What gets emitted

tree

my-app/
├── CLAUDE.md                          ← claude-code rules file
├── AGENTS.md                          ← codex rules file
├── .github/copilot-instructions.md    ← copilot rules file
├── .claude/                           ← claude-code engine
├── .codex/                            ← codex engine
├── .copilot/                          ← copilot engine
├── docs/                              ← SHARED (emitted once)
├── agent-artifacts/                   ← SHARED (emitted once)
├── .aido/
│   └── adapter.md                     ← lists all three adapters + per-adapter conformance
└── .beads/                            ← SHARED task graph (if enabled)

Three engine directories. Three rules files. One shared docs/, one shared agent-artifacts/, one shared Beads DB. All three agents see the same source-of-truth and the same task graph.

How the shared trees stay consistent

The CLI deduplicates the docs/ and agent-artifacts/ emissions across adapters. The three adapters all declare they emit those trees, but the CLI runs the emit only once and records the canonical owner in the manifest.

If you later run aidokit sync, only the adapter-owned files (under .claude/, .codex/, .copilot/) are touched. The shared trees and your customizations to them are preserved.

Conformance with mixed levels

Each adapter declares its own level. In a Claude Code + Codex project, you might have:

claude-code at Strict — full seven roles, watchdog hooks, output styles.
codex at Minimum — six roles, prose-level watchdog enforcement.

The user-visible project conformance is the minimum of the installed adapter levels for any given primitive. aidokit doctor surfaces this honestly.

Day-to-day use

Each developer opens whichever CLI they use:

shell

claude        # Alice uses Claude Code
codex         # Bob uses Codex CLI
gh copilot    # Carol uses Copilot CLI

All three see the same Beads task graph, the same docs/specs/, the same artifact templates. Pick up where someone else left off without context loss.

Removing an adapter later

shell

npx aidokit remove adapter copilot       # default: keeps shared docs

Removes .copilot/ and .github/copilot-instructions.md. Shared docs/, agent-artifacts/, and Beads remain untouched.

Caveats

Watchdog parity isn't free. Claude Code's hook-level enforcement is not available on Codex or Copilot. Roles run under prose discipline on those CLIs.
MCPs are per-adapter. Some MCPs (like the Copilot adapter's stubbed MCP surface) don't yet wire through cleanly. aidokit doctor reports per-adapter MCP state.
Per-developer preference, not per-task. The framework is consistent; the CLIs are interchangeable. Don't try to assign different roles to different CLIs — that is not what multi-adapter means.