AIDE — Agent IDE
nulltrope/agent-aide
Scaffolding de documentação agent-ready para repositórios em VS Code
Ver no GitHubExtensão VS Code que cria e gerencia arquivos markdown (CLAUDE.md, MEMORY.md, docs/) para que Claude Code navegue repositórios de forma estruturada. Oferece comandos para bootstrapping de documentação, planos, TODOs e checkpoints com templates reutilizáveis entre projetos.
Instalação
npx convez-ai nulltrope/agent-aide1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preparar repositórios para trabalhar com Claude Code
- Manter documentação estruturada compartilhada entre humanos e agentes
- Gerenciar planos, TODOs e checkpoints em formato padronizado
- Reutilizar templates de documentação entre projetos
Veredito

Ferramenta prática que resolve um problema real: criar documentação estruturada que agentes IA conseguem ler e os desenvolvedores conseguem manter. Templates reutilizáveis economizam setup repetitivo em múltiplos projetos.
README
A tradução para o português deste README ainda está na fila.
AIDE — Agent IDE Documentation
A small VS Code extension that bootstraps and manages the markdown files Claude Code uses
to navigate a repo: CLAUDE.md (which imports a shared, cross-project base), MEMORY.md,
and a standard docs/ working-docs folder for plans, TODOs, and checkpoints.
Drop into any project, run one command, and get a consistent, agent-readable documentation skeleton — driven by templates you define once and reuse everywhere. You can also record your own checkpoints/annotations in the same format and location agents already read, so human and agent notes share one convention.
Commands
| Command | ID | Default hotkey | What it does |
|---|---|---|---|
| AIDE: Bootstrap Repository | aide.bootstrap | ctrl/cmd+alt+a b | Renders the template tree into the repo root (CLAUDE.md, MEMORY.md, docs/). Re-run to refresh managed files. |
| AIDE: New Plan | aide.newPlan | ctrl/cmd+alt+a p | New docs/plans/YYYY-MM-DD-<slug>.md from the plan template. |
| AIDE: New TODO | aide.newTodo | ctrl/cmd+alt+a t | Appends an item to docs/todos/TODO.md. |
| AIDE: Add Checkpoint | aide.addCheckpoint | ctrl/cmd+alt+a c | Timestamped note in docs/checkpoints/, pinned to the active file/selection. |
| AIDE: Open Templates Folder | aide.seedTemplates | — | Seeds your global templates folder with the defaults and reveals it. |
| AIDE: Reset Templates to Defaults | aide.resetTemplates | — | Deletes the global templates folder and restores the bundled defaults (asks first). |
| AIDE: Open Settings | aide.openSettings | — | Opens the AIDE settings. |
The ctrl/cmd+alt+a chord is reserved as the AIDE prefix.
What bootstrap creates
README.md # human-facing project readme (agent keeps it current; no agent directives)
CLAUDE.md # the entry file Claude Code auto-loads; imports the shared base,
# then holds project-specific guidance the agent grows over time
MEMORY.md # durable, high-signal project facts
docs/ # the doc folder (name set by aide.docFolderName)
agents-base.md # shared, cross-project directives (managed — see below)
README.md # documents the convention for agents
plans/ # one file per task
todos/ # TODO.md checklist
checkpoints/ # dated progress notes & human annotations
templates/ # editable item templates (plan/todo/checkpoint)
AIDE targets Claude Code, which auto-loads CLAUDE.md and auto-expands @imports
(plain links/prose are only read on demand). So CLAUDE.md starts minimal and imports the
shared base with @docs/agents-base.md; the agent fills in the project-specific sections
as the project develops. This whole tree is just a render of your templates directory.
Templates
Your templates directory is a literal mirror of what you want in a repo root. Bootstrap
walks it and writes every file to the repo, substituting {{variable}} placeholders in
both file/directory names and file contents. For example, a template directory named
{{docFolderName}}/ renders to docs/ (or whatever aide.docFolderName is set to).
The global templates folder (aide.templatesPath, default ~/.config/aide/templates)
is the single source of truth: if it contains any files, it is used as the complete
template tree; otherwise the extension's bundled defaults are used.
Run AIDE: Open Templates Folder to seed the global folder with the defaults, then edit
the markdown directly. To discard your edits and start over, run AIDE: Reset Templates
to Defaults (it asks for confirmation, then deletes the folder and restores the bundled
defaults). Built-in variables are {{projectName}}, {{date}}, and
{{docFolderName}}, plus anything you add under aide.variables. The item templates in
<docFolderName>/templates/ additionally receive {{title}}, {{note}}, {{file}},
{{lines}}, {{time}}, and {{author}} when a plan/todo/checkpoint is created.
Common directives & managed files
Cross-project guidance that should apply to every repo (e.g. "ask before adding
dependencies", "match existing style", how to use docs/) lives in docs/agents-base.md.
It's a managed file (aide.managedFiles): bootstrap always overwrites it, so it
stays in sync with your central copy. CLAUDE.md imports it via @docs/agents-base.md,
so Claude Code loads it every session.
Settings
| Setting | Default | Description |
|---|---|---|
aide.templatesPath | "" → ~/.config/aide/templates | Global templates folder, mirroring the repo root (supports ~ / ${userHome}). |
aide.docFolderName | docs | Name of the working-docs folder; exposed to templates as {{docFolderName}}. |
aide.overwriteBehavior | skip | skip | prompt | overwrite for existing non-managed files. |
aide.managedFiles | ["{{docFolderName}}/agents-base.md"] | Template-relative paths that bootstrap always overwrites (the shared layer). |
aide.variables | {} | Extra template variables (override built-ins). |
Installing on your machines
AIDE is distributed as a .vsix you build from source.
First time on a machine:
git clone https://github.com/nulltrope/agent-aide.git && cd agent-aide
pnpm install --frozen-lockfile
pnpm run install:local # builds the .vsix and runs: code --install-extension aide.vsix --force
To update later:
git pull && pnpm install --frozen-lockfile && pnpm run install:local
Then reload VS Code (or restart). Notes:
install:localneeds the Node toolchain to build and thecodeCLI on PATH (Command Palette → Shell Command: Install 'code' command in PATH).- Bump
versionin package.json for a clean version jump; otherwise--forcereinstalls the same version in place.
Development
Requires Node and pnpm.
pnpm install
pnpm run compile # bundle to dist/ (esbuild) and copy templates to dist/defaults
pnpm run watch # rebuild on change
pnpm run check-types # tsc --noEmit
pnpm run lint # eslint
pnpm test # unit tests for the pure modules
Press F5 in VS Code to launch the Extension Development Host and try the commands
in a throwaway folder. The dev host points the global templates folder at an isolated
.aide-dev/templates (via AIDE_TEMPLATES_PATH in launch.json),
so development never reads or writes your real ~/.config/aide/templates. Even without
that env var, any non-production run (dev host or tests) falls back to a temp dir.
Layout
src/extension.ts— activation; registers commands with centralized error handling.src/commands/— one file per command.src/templates/manager.ts—{{var}}substitution, path rendering, and whole-dir tier resolution (novscodeimport, unit-tested).src/templates/items.ts— resolves item templates (repo copy → active template tier).src/templates/defaults/— bundled default template tree (shipped viadist/defaults); the{{docFolderName}}/directory is rendered at bootstrap time.src/config.ts— typedaide.*settings, tier building, variable building.src/util/— filesystem, workspace, and text helpers.