FAQ

Frequently asked questions about aidokit.

General

Does aidokit call an LLM?

No. Zero LLM calls. Every decision aidokit makes is deterministic. All model traffic happens in your AI coding CLI (Claude Code, Codex, Copilot), using whatever authentication you have configured there.

Does aidokit send any telemetry?

No. Zero network calls from aidokit itself. The only network activity during normal use is npm install (when you first npx it) and the shell commands declared in adapter manifests (e.g. claude mcp add).

Is aidokit a replacement for my AI coding CLI?

No. aidokit scaffolds discipline around the CLI you already use. After aidokit init finishes, you continue working in Claude Code, Codex CLI, or Copilot CLI as before.

Why three CLIs? Why not just pick one?

Different teams pick different tools. Different roles in the same team sometimes pick different tools. aidokit makes the workflow portable across them so you don't have to lock in.

What about Aider / Cursor / Continue / Cline?

Post-v1.0, third-party adapters can be published under any npm scope (@scope/aidokit-adapter-<name>). The standalone SDK that makes third-party adapters first-class ships in the v1.x or v2.0 line per the roadmap.

Install and update

Why @alpha?

Pre-1.0, the latest npm dist-tag is intentionally unset so users don't silently get pre-release builds. From v1.0 GA, latest takes over and you can drop the tag.

How do I update?

npx always fetches the latest version of the tag you specify. To upgrade once you've initialised a project, run aidokit sync to re-emit adapter-owned files from the new version.

Can I pin a specific version?

npx aidokit@0.5.0 init pins to a specific version. aidokit doctor warns if a newer version is available.

Do I need to install aidokit globally?

No. npx is preferred. Global install is optional: npm install -g aidokit@alpha.

Prereqs

Why doesn't aidokit auto-install Node / Claude Code / Beads?

Because installing system software crosses a trust boundary aidokit shouldn't own. We don't know your package-manager preference (Homebrew vs nvm vs asdf vs mise vs winget vs scoop vs …). We can't reason about whether sudo is appropriate. We can't roll back a half-installed prereq. So we detect and print the install command; you run it. See ADR-0008 in the repo for the full reasoning.

Can I bypass the prereq check?

--skip-prereq-check opts out of detection entirely. Use when you know your environment is set up — subsequent stages may still fail if prereqs are genuinely missing.

Configuration and state

Where does aidokit write?

• The project directory: engine dir, rules file, docs/, agent-artifacts/, .aido/, .gitignore.
• (Optionally) ~/.aido/ for personal config and personal skills.

It never touches your shell rc, PATH, SSH keys, credential stores, or other system files.

Where does aidokit get its config?

Per-project: <project>/.aido/adapter.md (your selections at init time). User-level: ~/.aido/config.json for preferences. CLI flags override both.

Can I commit .aido/ to git?

Yes — in fact, you should. .aido/adapter.md documents your team's chosen adapter and conformance level; .aido/state.json is the audit log of installed MCPs. Both belong in version control. The transient .aido-staging/ dir is auto-gitignored.

Workflow

What's the difference between /intake and /implement-task?

• /intake — classify, research, design, and plan a change into Beads tasks. Stops before any code is written. Runs in plan mode.
• /implement-task — execute exactly one approved Beads task end-to-end (Builder, two-stage Tester-Reviewer, then Maintainer). Stops after one task; no auto-progression.

Why "stops after one task"? Why not run them in a loop?

Autonomous loops are how AI coding sessions go wrong: scope creep, accumulating errors, runaway token spend. Human-gated task transitions are core to the design.

What is /orchestrator-next?

A read-only recommender. Reads the project + Beads state and tells you the safest next action. Never edits files.

Adapters, stack packs, MCPs

Why are adapters and stack packs separate?

Different concerns: adapters target a CLI runtime; stack packs encode tech-stack conventions. Keeping them orthogonal means a Django pack works under Claude Code today and Codex tomorrow without modification.

Can I write my own adapter?

Yes — though the standalone third-party SDK package ships post-v1.0. Until then, copy packages/adapter-claude-code/ as a starting point. The contract is at .docs/docs/specs/adapter-contract.md in the repo.

Why is the MCP catalog "data, not a plugin registry"?

Curation. A catalog is a trust signal — users rely on it to know an entry has been vetted for triggers, role-scoping, and security. Plugin registries that anyone can add to have zero curation.

What's the deal with security-sensitive MCPs?

Some MCPs can write outside the engine dir, execute shell, or send data off-host. Those carry a hard confirmation gate that --yes doesn't bypass. See MCP catalog.

Conformance and quality

What does "Strict" buy me over "Standard"?

The seventh role (frontend-browser-tester), output styles for reports, and complete monitoring-stream coverage of stage transitions. Worth picking if you want the full discipline; default Standard is fine for most teams.

Can I drop down from Strict to Standard later?

Yes. Edit the conformanceTarget in .aido/adapter.md and run aidokit sync. aidokit doctor will reflect the new target.

What happens if a check fails in aidokit doctor?

Exit 13 (CONFORMANCE_FAILED) on any MUST failure. Warnings are reported but don't fail unless you pass --strict.

Multi-adapter and brownfield

Can I run Claude Code and Codex in the same project?

Yes. aidokit init --adapter claude-code,codex. Three engine dirs coexist; docs/, agent-artifacts/, and Beads are shared. See Multi-adapter projects.

I already have a project. Will aidokit init nuke it?

No. Use --brownfield. Existing files outside the adapter's declared writesPaths are never touched. See Brownfield.

Pre-1.0 status

How stable is the v1.0 surface?

Roadmap and architecture are stable. Specs and ADRs are frozen for v1.0. The public CLI surface may still shift before GA but follows semver from v1.0 onward. Pre-1.0 breaking changes ship on minor bumps with migration scripts.

When does v1.0 GA ship?

When the exit criteria in the roadmap are met — signed packages, docs site, no P0/P1 bugs, external review of the adapter contract. Target: Q3–Q4 (indicative, not committed).

Troubleshooting

aidokit init exits with code 10

A required prereq is missing. Install it from the printed instructions and retry.

aidokit init exits with code 13

Conformance check failed. Either the installed adapter is broken or its declared level isn't supported. Try pnpm update @aidokit/adapter-claude-code (or your adapter).

Hook scripts don't run in Claude Code

Likely lost the executable bit. Run aidokit sync --scripts or chmod +x .claude/scripts/*.mjs.

MCP commands hang

Some MCPs need network. If you're offline, set AIDO_OFFLINE=1 and re-run with --no-mcp.

I can't tell which MCPs are installed

aidokit mcp list shows installed MCPs and their role scoping.