server

On-demand brain entry-point tool. Call this when you need to reach the brain mid-task — do NOT call it on every /aide boot. Boot-time brain precondition state is already reported by aide_info.brain.status; firing aide_brain at boot duplicates that work unnecessarily. It is also how a brain config is set up, repaired or written for any backend, one decision at a time. Every mode is read-only: no call writes to disk. **Optional `source` parameter** — which read runs. Omitted means `"host"`. - `"host"` — one section of the host's `.aide/config/brain.aide`, described below. - `"template"` — `{ template, purpose }`: one section of the bundled template (or its launcher, with `kind: "launcher"`) as verbatim bytes, and that section's one-line purpose from the published contract. The answer is the same whatever state the host's config is in. Use it as a worked example when writing that section for another backend. - `"contract"` — `{ sections }`: every contract section in order, each with `marker`, `role` (`live` or `seed`) and `purpose`, and no section text. - `"draft"` — a structural check of the draft config at `path`, with the same rules and fault vocabulary as the host config check, so a draft that passes is ready to swap in. Returns `{ outcome, instructions }`: `valid`; `invalid` with `fault` (`missing-sections` and its `sections`, or `malformed` and its `reason`); `absent` when no file is at `path`; `refused` when `path` is outside the project, and nothing is read. It checks structure, never content. **Optional `kind` parameter** — host and template reads only: any section marker of the published brain contract (see the enum), live or seed; `"launcher"` only with `source: "template"`. Omitting it means `"orientation"`, the runtime briefing for reaching the brain mid-task. `"config"` is the integration's wiring flow that `/aide:brain config` runs. Seed sections are fetched one per call while seeding. `path` is required with `source: "draft"` and accepted nowhere else; any other combination is rejected before the tool runs. **Host read response shape: exactly `{ status, instructions, found, purpose? }`.** No `backend`, no `connector`, no `name`, no `kind`. - `found: true` — `instructions` is that section's verbatim bytes from the host's `.aide/config/brain.aide`: no trimming, no normalization, no `${...}` substitution. `purpose` is that section's one-line purpose from the published contract; use it when adapting the section for another backend. - `found: false` — `instructions` is remediation, and `purpose` is absent. An absent file → run `/aide:brain config`. A requested section missing from the file → with the user's consent, call `aide_upgrade` with `category: "brain"`. A malformed or unreadable file → the exact fault, a hand fix with the user, then re-check with `aide_info`. Do not proceed as if the section were available. The section is returned on every status where the config exists and is well-formed, including `brain-aide-invalid` with missing sections, `no-mcp-entry` and `mcp-drift`. `status` mirrors the `BrainState` tagged union from `buildBrainState`, with five values: `ok`, `no-brain-aide`, `brain-aide-invalid`, `no-mcp-entry`, `mcp-drift`. Branch on `found` for "did I get the section" and on `status` for "is the brain healthy".

Remove a module's pipeline ephemerals (plan.aide, todo.aide, brief.aide) once that module's cycle has closed, leaving the code and the intent specs as the durable record. It never removes, rewrites or reads anything else: intent specs, research specs, code, and .aide/session.aide are all out of reach. Where plan.aide exists, it refuses unless every plan checkbox is checked and any todo.aide present is fully checked; a missing todo.aide does not block. Where there is no plan.aide, it removes a todo.aide that is fully checked, and refuses a brief.aide (which is removed only together with its plan), a todo.aide with no checkboxes, or a folder with no ephemerals at all. A refusal lists each unchecked item with its file and line, and nothing is removed. By default a plan.aide with no checkboxes is refused; passing allowEmptyPlan: true lets such a plan pass, overrides nothing else, and has no effect where there is no plan.aide. Call it directly, because the real call is already safe. dryRun is an optional preview for inspection only and is never a required step before the real call. This is the cross-platform replacement for a shell delete, so it can be permitted by name.

Scan for .aide spec files in this project. Returns a tree map of where specs live, following progressive disclosure. Without a path: returns a lightweight project-wide map — file locations and types only, no content. Use this once to understand the project's spec architecture. With a path: the response opens with the ancestor chain — the cascading intent lineage from project root down to the target directory, with each ancestor showing its description and alignment status (aligned/misaligned when set). The ancestor chain gives you the full inherited context before you read a single spec body. After the ancestor chain comes the detailed subtree of the target directory — summaries extracted from file content and anomaly warnings. Use this to drill into the area you're working on. .aide files are progressive disclosure specs that live next to orchestrator code — they contain intent (strategy, implementation contracts, anti-patterns), research (sources, data, patterns), or QA checklists (todo). Read .aide files BEFORE reading code — they are the context layer between folder structure and implementation details. File types (.aide, intent.aide, research.aide, plan.aide, todo.aide): - .aide — Intent spec (default). Strategy, contracts, anti-patterns. - intent.aide — Same as .aide, used only when research.aide exists in the same folder. - research.aide — Raw research. Sources, data points, pattern synthesis. - plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor. - todo.aide — QA re-alignment document. Captures where implementation drifted from intent. Never have both .aide and intent.aide in the same folder.

Boot-time reporter called by the orchestrator at startup. Returns independent top-level fields that the orchestrator must branch on separately: **`outdated` (array of stale artifact keys) — soft notification.** Compares the host's `.aide/versions.json` against the canonical manifest shipped with this npm package. Each element names an artifact key that is behind. An empty array means everything is current. A missing `.aide/versions.json` (old install predating version tracking) silently collapses to `[]`. Staleness is informational — the orchestrator continues with a heads-up to the user. **`behind` (`{ installed, latest }` or null) — soft notification.** Non-null only when the project's `aide` entry launches a globally installed server that is older than the latest published version. Suggest `npm i -g @aidemd-mcp/server` once and continue — it never gates the pipeline. Null when the server is launched locally, is current, or the version check could not run (offline checks pass silently). **`brainMigration` (`{ staleSections, legacyLauncher }` or null) — soft notification.** Non-null when the brain config has sections whose text matches an earlier template version, or a legacy brain launcher (`legacyLauncher` lists the reasons: unpinned, unversioned, older-pin, missing-auto-confirm). Mention it once and suggest `/aide:brain config`; it never gates the pipeline and never changes `brain.status`. **`brain` (precondition state) — hard gate.** Reports whether the host's brain MCP entry is wired and consistent. Shape: `{ status, name?, fault?, hints }` — `name` is absent on `no-brain-aide` and `brain-aide-invalid`; `fault` is present only on `brain-aide-invalid`. The orchestrator must halt and direct the user to resolve the issue before continuing if `status` is not `'ok'`. No path validation is performed — the package never stats any directory on disk; state derives entirely from comparing `.aide/config/brain.aide` against `.mcp.json`. The five `brain.status` values: - `ok` — `.aide/config/brain.aide` exists, satisfies the required-section contract, and the host's `.mcp.json` `brain` entry matches the parsed `mcpServerConfig`. `name` is the user-declared descriptive label from brain.aide. The pipeline may proceed. - `no-brain-aide` — `.aide/config/brain.aide` is absent. No `name` field. Remediation: run `/aide:brain config`, which creates the config. - `brain-aide-invalid` — the file exists but falls short. `fault.kind` is `missing-sections` (with `fault.sections` naming each missing required section) or `malformed` (with `fault.reason`). No `name` field. Remediation: run `/aide:brain config`. - `no-mcp-entry` — brain.aide parsed successfully but the host's `.mcp.json` is absent, malformed, or has no `mcpServers.brain` key. `name` is present. Remediation: run sync with the same launcher the project's `aide` MCP entry uses — `aidemd-mcp sync` when the project's `aide` MCP entry runs the globally installed `aidemd-mcp`, or `npx -y @aidemd-mcp/server@<version> sync` with the version that entry pins when it runs through npx. - `mcp-drift` — brain.aide and `.mcp.json` both exist but their `brain` entries disagree on `command` or `args`. `name` is present. Remediation: run sync with the same launcher the project's `aide` MCP entry uses — `aidemd-mcp sync` when the project's `aide` MCP entry runs the globally installed `aidemd-mcp`, or `npx -y @aidemd-mcp/server@<version> sync` with the version that entry pins when it runs through npx. `hints` is always present on every status — an array of candidate brain root paths the orchestrator can surface during recovery. No parameters needed — uses the server's working directory.

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.

Return JSDoc, signature, and kind for a named symbol without opening the full file — Tier 2 progressive disclosure for code. When an agent knows a function name from an import list or orchestrator file, call inspect to learn what the symbol does, what it accepts, and what it returns, based on its contract alone. Searches across TypeScript and JavaScript source files (ts, tsx, js, jsx, mjs, cjs). Use the optional `file` parameter to narrow the search to a single file when the location is already known.

Read an .aide spec file with full context. Returns the file content, its classified type (intent/research/plan/todo), related specs in the same directory, and links found in the content (relative paths, inline references, URLs). Use this after aide_discover to drill into a specific spec.

Create new .aide spec files with automatic naming convention enforcement. Handles the naming rules: intent specs are .aide by default, but become intent.aide when research.aide exists in the same folder. Creating a research.aide auto-renames any existing .aide to intent.aide. Types: - intent — Strategy, contracts, anti-patterns - research — Sources, data, patterns (triggers rename of existing .aide) - both — Creates research.aide + intent.aide pair - todo — QA re-alignment document for QA agents - plan -- Architect's implementation plan (no naming interaction with intent/research)

Compare the AIDE methodology artifacts in this project against the canonical versions and return structured JSON results grouped by category. Use this when the user asks to update AIDE, sync AIDE, refresh AIDE, check for AIDE updates, or bring AIDE up to date. This is NOT for editing user .aide specs — it inspects methodology infrastructure only. The tool uses a two-call pattern for progressive disclosure: **First call (no `category` param):** Returns a lightweight summary — every category with file names, statuses, and counts, but NO file content. Use this to understand what has drifted and present a summary to the user. Ask which categories they want to apply. **Second call (with `category` param):** The tool writes all differs/missing files directly to disk itself and returns a manifest — file results with `filePath`, `status` (`"updated"`, `"created"`, or `"unchanged"`), and `name`, but NO `canonicalContent`. The agent never sees file content and never uses the Write tool for methodology files. Repeat the second call for each category the user confirms. As the calling agent, you must: 1. Call without `category` first to get the summary 2. Present each drifted category (differs/missing) and ask the user which to apply 3. For each confirmed category, call again with `category=X` — the tool writes the files and returns a manifest. Report what was updated/created to the user. 4. For the `mcp` category, the manifest still includes `prescription` data — merge the entry into the existing MCP config yourself (read → merge → write). If `malformed`, tell the user — do not overwrite. 5. For `ide`, the manifest may include `instructions` for VS Code extension install — execute that command for the user. Zed config is written directly by the tool. 6. For `brain`, the summary reports `missingSections`, outdated section text as `staleSections` and a legacy brain launcher as `legacyLauncher` (its reasons), each named separately. The brain category then works through three calls, each one decision at a time: a. `category: "brain"` (after the user's yes) inserts every missing section from the latest bundled template — byte-identical, in the file's line endings — only when the config launches the template's own brain server. It returns `{ outcome: "inserted", inserted }` (markers only; empty when nothing is missing) or `{ outcome: "adapt", adapt, instructions }` naming the sections the user must write for their backend. b. `category: "brain"` with `brainChange: <marker | "launcher">` returns one `{ outcome: "change", target, before, after, beforeHash }` diff to show the user. It is read-only. For a non-template config it returns `missing` with the template's version of an absent section instead. c. The same call plus that `beforeHash`, only on the user's yes to that one diff, returns `applied`, or a `refused` re-fetch instruction when the bytes changed since the preview. Never batch changes under one yes. Every refusal's `instructions` names the next step. **IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion:** Do NOT present all categories at once. Walk the user through ONE category at a time using AskUserQuestion with Yes/Skip options. Stop after each question and wait for confirmation before calling with that category. Categories: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide, readme, brain. Upgrade surface (user code and user .aide specs are never touched): - AIDE pointer stub in the agent config file - Canonical methodology docs under .aide/docs/ - versions.json metadata under .aide/docs/ - Slash commands for all pipeline phases - Pipeline agent files, skill templates - MCP server entry in the project's MCP config - IDE file association config (Zed settings, VS Code extension) - The user-owned brain config, only through the brain category: missing sections and confirmed migrations, one consented change at a time Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects the framework or accepts an override. **MCP step:** only AIDE's own launch forms for the `aide` entry are judged, and a prescription never switches the mode. An npx entry matches only when it is `npx -y` pinned to this server's version, so a `differs` there is how the pin moves forward deliberately. An `aidemd-mcp` entry matches as the bare command or an absolute-path shim of it; a path-launched one may carry `tip`, an informational remark to mention once — never drift, never a merge question. Any other (custom) command under the `aide` key is left alone and reports `matches`. The brain entry is not part of the `mcp` step; a legacy brain launcher is changed only through the brain category's `brainChange: "launcher"` preview and apply, on the user's yes.

Health check for .aide spec files in the project. Detects orphaned specs (in folders with no orchestrator), missing specs (orchestrators with 3+ helper imports but no .aide), naming conflicts (.aide + intent.aide in same folder), broken links, orphaned research (research.aide without intent spec), and missing descriptions (specs with no description field in frontmatter).