aide_init

Bootstrap the AIDE development environment into a project. Returns structured JSON for agent consumption — not prose.

The tool uses a two-call pattern for progressive disclosure:

First call (no category param): Returns a lightweight summary — every step with name, status (would-create/would-overwrite/would-skip/exists), category, and filePath, but NO content fields. Also returns brainHints (brain root candidates) and detected framework. Use this to understand what needs to be done and which categories require user prompts.

Second call (with category param): The tool writes all would-create AND approved would-overwrite files directly to disk itself and returns a manifest — steps with filePath, status (created, overwritten, or exists), and name, but NO content. would-skip steps stay would-skip in the manifest (tool writes nothing for them). The agent never sees file content and never uses the Write tool for new files.

Exception — MCP steps: For MCP steps, the manifest includes prescription data (key name and entry object) so the agent can read the existing config, merge, and write. The tool never touches MCP config directly.

Exception — brain category: The Brain config (brain.aide) step carries brainSummary on every call, including the summary: sections (each section's marker, role, seedPath for seeds, and templateBytes), missingSections, staleSections, legacyLauncher reasons and templateIntegration. It never carries section text, purposes, repair blocks or before/after bodies. Missing sections are inserted with aide_upgrade category: "brain", seeds are read one at a time with aide_brain, and migrations are previewed and applied one at a time through aide_upgrade. Sections the user edited and custom launchers are never offered. The tool creates .aide/config/brain.aide when it is absent and never overwrites an existing one.

Exception — IDE VS Code steps: IDE steps that need external tooling (VS Code CLI) return instructions for the agent to execute, since those aren't simple file writes.

Agent branch logic — silent-on-create, prompt-on-overwrite:

After the first call, walk the categories using this rule:

• Pure-create category (all steps are would-create, would-skip, or exists): apply silently by calling with category=X immediately — no AskUserQuestion. A category with nothing on disk to overwrite has no decision the user can inform.

• Overwrite-bearing category (any step is would-overwrite): pause and use AskUserQuestion with structured options. Name the files that would be overwritten. If the user approves, call with category=X — the tool overwrites and returns overwritten in the manifest. If the user declines an overwrite but wants the new files, call with category=X — the tool writes only would-create steps; the would-overwrite step stays would-overwrite in the manifest.

• Inherent-decision categories (framework, brain root path, MCP config merge, launch mode, IDE choice): always use AskUserQuestion regardless of disk state. These are not file-write decisions — filesystem contents cannot resolve them.

IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion: Do NOT present a summary table of all categories. Do NOT offer "all" as an option. Do NOT ask conversational questions — use the AskUserQuestion tool with structured options at every pause point.

1. Call without category first to get the metadata

2. Present ONLY the detected framework — use AskUserQuestion with Yes/{alternatives} options. STOP.

3. Walk categories in order: methodology, commands, agents, skills, mcp, brain, ide, readme. For each:

   • Pure-create: apply silently (call with category=X), report results, move to next.

   • Overwrite-bearing: use AskUserQuestion naming the would-overwrite files. STOP. Wait for selection, then call with category=X. Report manifest (created N, overwrote M). Move to next.

   • Inherent decision: always use AskUserQuestion. STOP.

4. For brain: read brainSummary from the step, then direct the user to /aide:brain config. Call with category=brain only to receive the manifest; the tool creates .aide/config/brain.aide only when absent and never overwrites an existing one. /aide:brain config asks the brain's launch mode and passes brainMode.

5. For MCP: when the aide step is would-create, first ask the aide server's launch mode with AskUserQuestion — "Global (recommended)" (personal machine, reliable startup; stays on its installed version; one-time npm i -g.) or "Local" (shared repos, cloud/CI; pinned to one version that /aide:upgrade moves forward; flaky cold start.) — and call with category=mcp and aideMode. If the returned step carries globalPackage with installed: false, ask whether to run its installCommand; run it via Bash only on yes. If the user declines or the install fails, call again with aideMode: "local" and tell the user the server will launch locally. Then use AskUserQuestion with Merge/Skip and merge the prescription entry into the existing config yourself (read → merge → write). Never replace an existing aide entry. STOP.

6. For IDE: use AskUserQuestion with multiSelect for Zed/VS Code/Neither. STOP.

Each pause point is ONE AskUserQuestion → wait for selection → then proceed. Never show multiple categories at once. Never ask open-ended conversational questions.