convez.ai
AgenteProdutividadeIntermediário
nulltrope

AIDE — Agent IDE

nulltrope/agent-aide

Scaffolding de documentação agent-ready para repositórios em VS Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Extensã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-aide

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

CommandIDDefault hotkeyWhat it does
AIDE: Bootstrap Repositoryaide.bootstrapctrl/cmd+alt+a bRenders the template tree into the repo root (CLAUDE.md, MEMORY.md, docs/). Re-run to refresh managed files.
AIDE: New Planaide.newPlanctrl/cmd+alt+a pNew docs/plans/YYYY-MM-DD-<slug>.md from the plan template.
AIDE: New TODOaide.newTodoctrl/cmd+alt+a tAppends an item to docs/todos/TODO.md.
AIDE: Add Checkpointaide.addCheckpointctrl/cmd+alt+a cTimestamped note in docs/checkpoints/, pinned to the active file/selection.
AIDE: Open Templates Folderaide.seedTemplates—Seeds your global templates folder with the defaults and reveals it.
AIDE: Reset Templates to Defaultsaide.resetTemplates—Deletes the global templates folder and restores the bundled defaults (asks first).
AIDE: Open Settingsaide.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

SettingDefaultDescription
aide.templatesPath"" → ~/.config/aide/templatesGlobal templates folder, mirroring the repo root (supports ~ / ${userHome}).
aide.docFolderNamedocsName of the working-docs folder; exposed to templates as {{docFolderName}}.
aide.overwriteBehaviorskipskip | 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:local needs the Node toolchain to build and the code CLI on PATH (Command Palette → Shell Command: Install 'code' command in PATH).
  • Bump version in package.json for a clean version jump; otherwise --force reinstalls 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 (no vscode import, unit-tested).
  • src/templates/items.ts — resolves item templates (repo copy → active template tier).
  • src/templates/defaults/ — bundled default template tree (shipped via dist/defaults); the {{docFolderName}}/ directory is rendered at bootstrap time.
  • src/config.ts — typed aide.* settings, tier building, variable building.
  • src/util/ — filesystem, workspace, and text helpers.
Ver o original no GitHub

Bom para

Relacionados