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 Codex CLI?"}:::stop
  q2{"Have GitHub Copilot CLI?"}:::stop
  q3{"Have Claude Code?"}:::stop
  rec_codex["Use codex adapter
(Minimum conformance)"]:::ok
  rec_copilot["Use copilot adapter
(Minimum conformance)"]:::ok
  rec_claude["Use claude-code adapter
(Strict conformance)"]:::ok
  install["Install any one CLI
(codex / gh copilot / claude)"]:::external
  start --> q1
  q1 -->|yes| rec_codex
  q1 -->|no| q2
  q2 -->|yes| rec_copilot
  q2 -->|no| q3
  q3 -->|yes| rec_claude
  q3 -->|no| install

The three first-party adapters #

Pick the adapter for the CLI you actually use. Conformance level is a consequence of what that CLI can support (does it expose hooks and output styles?), not a ranking of the adapters.

Adapter	Conformance	When to pick
codex	Minimum	You use Codex CLI; the CLI exposes no hooks/output styles, so Minimum is the honest ceiling.
copilot	Minimum	You use GitHub Copilot CLI; the CLI exposes no hooks/output styles, so Minimum is the honest ceiling.
claude-code	Strict	You use Claude Code; the CLI exposes hooks + output styles, enabling Strict (audit-ready discipline + capability declarations).

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 codex
command -v gh
command -v claude

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 <codex|copilot|claude-code> --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.
Expecting Strict-only behaviour (capability decls, signed outputs) from codex or copilot — their target CLIs expose no hooks or output styles, so those features cannot be enforced there. Pick the adapter that matches the CLI you use, not the highest level.
Editing the adapter directory by hand instead of going through aidokit sync.