Scenario: Which adapter do I pick?

When to use #

You have one or more AI coding CLIs installed (or are choosing one) and need to know which aidokit adapter to scaffold. The decision is mostly mechanical: which CLI are you actually going to use day-to-day?

Decision tree #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart TD
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;
  start(["Which AI CLIs are installed?"]):::actor
  q1{"Have Claude Code?"}:::stop
  q2{"Have Codex CLI?"}:::stop
  q3{"Have GitHub Copilot CLI?"}:::stop
  rec_claude["Use claude-code adapter
(Strict conformance)"]:::ok
  rec_codex["Use codex adapter
(Minimum conformance)"]:::ok
  rec_copilot["Use copilot adapter
(Minimum conformance)"]:::ok
  install["Install any one CLI
(claude / codex / gh copilot)"]:::external
  start --> q1
  q1 -->|yes| rec_claude
  q1 -->|no| q2
  q2 -->|yes| rec_codex
  q2 -->|no| q3
  q3 -->|yes| rec_copilot
  q3 -->|no| install

The three first-party adapters #

Multi-adapter projects #

You can run aidokit init --adapter codex and later aidokit add adapter claude-code (or any other pair) — .codex/ and .claude/ will coexist, sharing docs/, agent-artifacts/, and the Beads task graph. See concepts/adapters-and-stack-packs.md.

Step-by-step #

1. Inventory installed CLIs #

command -v claude
command -v codex
command -v gh

Expected: at least one resolves to a path.

2. Pick the matching adapter #

Use the decision tree above. If you have multiple installed, pick whichever you use most day-to-day and add the others later with aidokit add adapter <name>.

3. Scaffold #

npx aidokit init --adapter <claude-code|codex|copilot> --tier standard --stack node-ts --yes

Pre-v1.0: replace npx aidokit with node /path/to/aidokit/packages/cli/dist/bin/aidokit.js.

Expected: .claude/, .codex/, or .copilot/ written, with adapter-appropriate role surface.

4. (Optional) Add a second adapter later #

aidokit add adapter <name>

Expected: the second adapter's directory appears next to the first; shared artifacts are unchanged.

Common mistakes #

• Scaffolding an adapter you don't actually have installed — aidokit doctor will warn, but the workflow won't run end to end.
• Picking codex or copilot when claude-code is available, then expecting Strict-only behaviour (capability decls, signed outputs).
• Editing the adapter directory by hand instead of going through aidokit sync.

See also #

• Adapters & stack packs
• Conformance levels
• New project
• Quick start