AeroMD

A VS Code extension that renders an interactive Workspace Graph of your Markdown, Python, JavaScript, and TypeScript files, with related GitHub issues and pull requests alongside their code.

The extension is published as bpcarson.aeromd; its commands, settings, tools, skill, and artifacts use the AeroMD name.

Features

• Force-directed graph — files are nodes, links between them are edges
• Wiki-link support — parses [[note]], [[note|alias]], [[note#heading]]
• Standard Markdown links — parses [text](https://github.com/bpcarson/aeromd/blob/HEAD/path/to/file.md)
• All supported files by default — Markdown, Python, JavaScript, and TypeScript appear together with distinct colors
• Issues and pull requests in Workspace Graph — automatically discovers repository work, connects PRs to changed workspace files and linked issues, and shows supporting evidence in the graph inspector
• Compact visibility controls — open Nodes in the graph corner to hide a file/work type, choose Only to isolate it, or Show all to restore every type
• JavaScript and TypeScript imports — includes JSX/TSX, ES modules, CommonJS, re-exports, and literal dynamic imports resolved to local files
• Editor or Explorer view — choose whether the graph opens in an editor tab or in the Explorer side bar
• Open In Editor from the sidebar — launch the current graph into an editor tab from the sidebar title bar
• Click a file node to open it; select an issue or PR to inspect its relationships and open GitHub
• Hover over a node to highlight its direct neighbours and dim the rest
• Search — type in the search box to filter/highlight matching nodes
• Intent-based search — Graph filters labels/paths; Relevance uses QMD BM25 on desktop or built-in BM25 on the web; Semantic/Hybrid use QMD or an explicitly enabled browser embedding model
• Agent-ready graph and navigation — a v2 extension API, shared workspace tools and specialized navigation tools, and a packaged skill let AeroCode-compatible harnesses search, traverse, and inspect code
• VS Code for the Web — the same extension runs on vscode.dev without Node polyfills; desktop-only capabilities degrade visibly
• Large-repository budgets — bounded discovery, indexing, webview projection, and payload sizes keep the graph from monopolizing memory
• Active editor highlighting — keeps the open supported file and nearby nodes highlighted in the graph
• Graph layouts — choose file-type columns, a force-directed network, radial rings, or a directed hierarchy from the graph's Layout menu
• Motion presets — make the Force layout balanced, calmer, or more lively; the other layouts stay still
• Manual refresh — use the refresh button to rebuild the graph on demand
• Mermaid export — generate README-friendly Mermaid diagrams from the workspace graph, including a verbose mode
• Drag nodes to rearrange the layout
• Zoom & pan — fits the graph on first load and when you choose a layout; scroll to zoom, drag the background to pan, or double-click background to fit again
• Auto-refresh — the graph updates automatically when supported files are created, changed, or deleted

Screenshots

This screenshot is generated by the Playwright browser test in GitHub Actions. It captures the real extension inside a pinned VS Code for the Web workbench rather than a mockup.

Usage

1. Open a workspace that contains Markdown, Python, JavaScript, or TypeScript files.
2. Run the command AeroMD: Open Graph View from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Workspace Graph opens in an editor panel or in the Explorer side bar, depending on aeromd.viewLocation.

The command is also available as an icon button (⊞) in the editor title bar when a supported file is active.

All file types appear by default. Hover, focus, or click Files in the graph corner for a vertical list of visibility controls. These controls hide nodes and their links from that view; they do not change the underlying index or exports. Search-mode diagnostics appear in the AeroMD output log at startup.

JavaScript/TypeScript graph edges resolve relative imports, including extensionless paths, directory index files, and .js/.mjs/.cjs specifiers targeting TypeScript sources. Package imports, workspace package names, and tsconfig path aliases are not resolved.

To export the current workspace graph as Mermaid for GitHub or other Markdown renderers, run AeroMD: Export Mermaid Graph. The extension opens a new Markdown document with a fenced Mermaid block and also copies that block to your clipboard.

If you want more context in the exported labels, run AeroMD: Export Verbose Mermaid Graph from the Command Palette. It keeps the same graph structure but adds folder/path context to node labels when the file is not in the workspace root.

Settings

aeromd.searchBackend remains readable for migration but is deprecated. basic maps to Graph and qmd maps to Relevance until aeromd.searchMode is explicitly set.

The graph's Layout menu saves aeromd.forceMode: Node types (grouped) separates node kinds into fixed columns, or a compact grid when one type is visible; Force (network) reveals relationship clusters; Radial (radial) shows hop distance from the most-connected node in each connected group; Hierarchy (hierarchical) follows link direction from left to right, keeping cycles together. Only Force uses a simulation, controlled by aeromd.layoutPreset. Switching editor tabs preserves the layout and zoom.

Issues and PRs in Workspace Graph

Open AeroMD: Open Graph View. The graph detects GitHub repositories from a local Git checkout or a GitHub Remote Repositories workspace. With an existing GitHub sign-in, it automatically loads a bounded set of open issues and PRs. Connect GitHub handles sign-in; Repositories connects an unknown root or corrects its repository mapping directly in the graph. No Repository Work document is required.

PR nodes connect to their changed files already present in the workspace graph, and to issues through closing relationships, cross-references and text mentions. Select a work node to inspect its title, state and relationship evidence; use Open GitHub for the original item. File matching uses repository identity and exact paths. Captured revisions remain historical evidence, not a claim that the current local contents match them. Unverified mentions and missing/ambiguous files are reported rather than guessed.

Use Nodes to filter Issues and Pull requests, and Issues & PRs to choose open items or a bounded recent set including closed/merged work. Refresh in that toolbar updates GitHub evidence. Fit brings newly discovered nodes into view; ordinary metadata updates retain positions and zoom. The workspace cache survives reopening, and file refreshes reuse captures for five minutes without background polling. Failed refreshes retain the prior capture and its timestamp.

Each repository capture lists at most 50 issues and 30 PRs, with 100 changed files per PR, a 32-request/60-second acquisition budget and explicit coverage notes. Up to five workspace repositories are acquired. Discussion comments and reviews are outside this first slice; referenced PRs outside the captured list may have no acquired file inventory. Missing results do not establish absence. Rendering limits are separate from acquisition coverage. Source-file APIs, document search and Mermaid export retain their existing file-only contracts.

npm run test:graph-work-web exercises automatic acquisition, the production graph webview handshake, source API isolation and persisted cache in a real VS Code Web host using controlled GitHub responses. Browser graph controls and the unit suite cover mixed selection, filtering, budgets and stale acquisition.

Search providers

AeroMD exposes stable search intents and chooses providers internally:

Run AeroMD: Enable Browser Semantic Search to review and approve the pinned model download. AeroMD does not initiate that download during activation or from an agent tool. Use aeromd_search_text for literal workspace matching and aeromd_search for document relevance and graph lookup.

Repository hotspots

Run AeroMD: Analyze Repository Hotspots to inspect GitHub change activity, line churn, weekly history and Python function cyclomatic complexity at a pinned commit. Open the supporting commits and exact source ranges, or export the report as JSON. Agents use aeromd_analyze_hotspots through the editor, CLI or MCP. The priority formula is an explicit heuristic; raw metrics and coverage remain visible. See hotspot definitions, access and limits.

Agent tools and extension API

AeroMD owns repository reading, search and understanding. It works independently of AeroCode; host agents provide orchestration, permissions and change review.

0.4.0 migration: the exported extension API is now v2. Activate bpcarson.aeromd and check api.version === 2. The shared api.repository service supplies all filesystem and evidence operations. getDocument also reads files outside the graph; getBacklinks is asynchronous and returns an evidence object (path, references, totalReferences, truncated, discovery, resolutionDiscovery, analysis) rather than a bare node array. Index status now advertises repositoryToolsVersion: 2 for the separate discovery and text-analysis coverage contract. Clients migrating from repository contract v1 must also check analysis.complete and read text/metadata failures from analysis.skipped, instead of discovery.skipped. The exported extension API remains v2 and the portable tool envelope stays at protocol version 1. There is one document-read tool and one backlink tool; no competing legacy registrations are retained.

Repository discovery includes untracked files, excludes generated/dependency folders and symbolic links, and is bounded to 2,000 files, 4,000 directories and 50,000 directory entries. Text reads reject binary files and files over 1 MiB. Glob scope is applied during discovery, before the matching-file budget, so narrowing to src/** can recover files beyond an incomplete global inventory. Text search, backlinks and metadata search report filesystem inventory in discovery and text-analysis coverage in analysis. Known binary formats remain in the inventory as possible link targets and are deliberately excluded from text reads; analysis.excludedFiles and bounded analysis.exclusions report them. Unexpected text-read or metadata failures appear in analysis.skipped and make analysis.complete false. Inferring absence requires discovery.complete and analysis.complete, with no result truncation, within the reported text scope. Backlinks additionally report target-resolution scope in resolutionDiscovery, which must also be complete. Discovery failures remain in discovery.skipped. File-read line ranges are 1-based; provider definition positions are zero-based UTF-16. Multi-root paths use numeric root prefixes (0:src/app.py), matching graph IDs. Reference parsing and resolution are shared between inspection, backlinks and graph construction: fenced examples are excluded, source-relative links take precedence, and ambiguous basename fallbacks remain unresolved. Adjacent Python implementation/stub pairs resolve to .py; standalone .pyi modules also enter the graph and resolve consistently. Other module-name collisions remain unresolved. Python import inspection is lightweight static parsing, not a call graph or type analyzer.

Inspection and outgoing-reference responses return totalReferences and truncated; inspection also returns totalSections and per-field truncation. References are capped at 200 entries / 24 KiB and sections at 200 entries / 12 KiB of serialized UTF-8. Backlinks respect their requested count and the same 24 KiB byte cap, reporting totalReferences and truncated. Metadata over 8 KiB is omitted with its truncation flag; discovery diagnostics are capped at 8 KiB / 100 entries and report diagnosticsTruncated. These output limits do not truncate the evidence index. Use aeromd_read_file line ranges to read evidence omitted from a response.

Metadata search caps each returned value at 8 KiB and the combined matches array at 24 KiB of serialized UTF-8, in addition to maxResults. Oversized matches are omitted, allowing later smaller matches to be returned. Results include totalMatches (among successfully parsed files in the discovered scope), omittedMatches, omissions by value-byte, response-byte or count limit, and truncated. The tool envelope repeats data as text, so its serialized size is larger than the matches budget but remains bounded.

Frontmatter remains YAML, including ordinary nonrecursive aliases. Markdown and comment-wrapped frontmatter share validation before tool serialization: cycles, unsupported values, invalid mappings, and expansion beyond 32 levels, 10,000 values or 1 MiB are rejected. Inspection reports metadataIssue and metadata truncation while preserving headings/references. Metadata search reports those files in analysis.skipped, sets analysis.complete to false, and continues. Metadata absence requires both discovery.complete and analysis.complete and no result truncation. Raw document reads remain available. Parsed caches use resolved file URIs plus versions, so reordered/replaced workspace roots cannot reuse another file's data.

In the coordinated AeroCode integration, AeroMD is required for activation. workspace/write_file and workspace/replace_text remain in AeroCode together with approvals, edit review, model execution and orchestration. This release does not move editing primitives into AeroMD or provide an optional fallback.

The Markdown/Python/JavaScript/TypeScript graph and ranked retrieval remain narrower than general filesystem discovery. An absent graph path does not establish absence from the repository. Language-provider navigation preserves URI schemes and ranges and uses bundled Python semantics by default; other languages require an active provider.

The repository also ships a portable Node adapter for local agent harnesses. It exposes the same canonical tool names and JSON schemas through a one-shot CLI and newline-delimited MCP JSON-RPC over stdio:

aeromd tools
aeromd tool aeromd_search --input '{"query":"architecture","mode":"relevance"}'
aeromd tool aeromd_get_document_symbols --input '{"uri":"src/example.py"}'
aeromd tool aeromd_find_symbols --input '{"query":"Example","language":"python"}'
aeromd tool aeromd_prepare_review --input - < review-input.json
aeromd mcp

The CLI indexes Markdown, Python, JavaScript, and TypeScript files below its current directory without following symbolic links. Graph and built-in BM25 relevance search are available. Python/Markdown document outlines and workspace symbol search now use bundled Lezer parsers in every host, with no native Python or AeroPy dependency. Editor outlines preserve nonempty language-provider results and use the bundled parser as a fallback. Structural results include source versions, parse recovery information and zero-based UTF-16 source ranges; they describe declarations, not semantic usages.

Python semantics: AeroMD bundles basedpyright 1.40.1 for definitions, references and reviewed rename in Web, desktop and CLI/MCP, without another extension, Python installation or AeroPy. Supported rename targets are undecorated module-level functions in a bounded single-root workspace, including local imports, aliases, re-exports and static __all__. Unsupported configuration, ambiguous/dynamic analysis and incomplete scopes fail explicitly. See supported scope, packaging and tests. Implementations, advanced refactors and published editor diagnostics still require an editor provider.

aeromd_find_symbols performs name-substring matching with an optional language/glob scope, a default 100-file scan (maximum 500), a 100-result default (maximum 500), and a 48 KiB result-array budget. Individual parsed files are capped at 256 KiB and 200,000 syntax-tree nodes. Parsing cooperatively yields between available parser steps and tree-walk chunks. These are cooperative limits, not an isolated worker or hard CPU preemption. Results identify skipped files, parse recovery, truncated symbols, and per-file versions; they do not claim an atomic workspace snapshot. Markdown ranges cover the heading declaration, not the whole section. Python coverage is class/function/method declarations, including nested and decorated declarations; variables, call graphs and type analysis are outside this slice.

aeromd_get_symbol_references is distinct from aeromd_get_references, which reports links/imports/path evidence. Python semantic results use the bundled engine by default, include declarations, and report scope completeness and unresolved dependencies. Other languages use editor providers. aeromd_get_diagnostics reads already published diagnostics for one document; freshness is unknown, and an empty result does not establish an error-free file or an available analyzer. New provider location/diagnostic arrays are capped at 48 KiB, and diagnostic messages at 2,048 characters. These operations are read-only; existing basic file writes retain their current safeguards.

See the specialized-tool roadmap for the intended refactoring and CodeFlux follow-ups. Every invocation retains the version-1 portable result envelope; the extension API stays at v2 with additive methods.

Navigation positions are zero-based {line, character} coordinates where character counts UTF-16 code units, matching VS Code/LSP conventions. Results are bounded to 100 entries by default (500 maximum) and time out after 5 seconds by default (30 seconds maximum). One VS Code deadline/cancellation boundary covers both document opening and provider invocation; a late document-open result does not start a provider after cancellation or timeout. empty, BACKEND_UNAVAILABLE, PROVIDER_ERROR, TIMEOUT, and CANCELLED are distinct outcomes; an empty VS Code provider response is marked inconclusive and must not be interpreted as proof that no provider or definition exists.

Web-host behavior

QMD is a CLI and cannot run inside the browser extension host. On vscode.dev, Relevance falls back to AeroMD BM25, Semantic uses the optional local Transformers.js worker, and new-window graph opening degrades to a new editor tab. Workspace access uses vscode.workspace.fs, including virtual and multi-root workspaces.

Mermaid export

GitHub can render Mermaid diagrams in Markdown, so AeroMD can export the current workspace graph as a Mermaid flowchart. This export is static, not interactive, but it works in places like README.md where VS Code webviews cannot run.

The standard export uses rounded nodes, a smoother curve, and darker edge styling for better contrast in rendered Markdown. A separate verbose export is available when you want folder context in concept-heavy graphs.

Docs

The repository includes a Diataxis-style documentation set in docs/home.md: tutorials, how-to guides, reference, and explanation pages linked together so they also form a useful graph.

Link formats understood

External URLs (http://, https://, mailto:, etc.) and anchor-only links (#heading) are ignored.

Releases

When package.json's version is bumped on main, GitHub Actions verifies source, bundles, tests, and package contents before creating the matching release, uploading one .vsix asset, and publishing it to the Visual Studio Marketplace when VSCE_TOKEN is configured.

The reusable Publish VSIX workflow also runs for manually published GitHub releases and can be dispatched for an existing release tag.

After a successful CI push run on main, Auto Patch Version calls bpcarson/actions/.github/workflows/auto-patch-version.yml@v1. Changes to extension source, media, skills, dependencies, or build configuration without an explicit version change receive an automatically created and merged patch-version PR. The shared workflow then dispatches Verified Release On Version Bump, so the bot-created merge still starts release verification and publishing.

Explicit version choices are preserved. Documentation-only, test-only, and workflow-only changes do not trigger automatic patch bumps.

Repository settings must allow GitHub Actions to create and merge pull requests, and AeroMD must have access to the shared bpcarson/actions workflow.

Download the packaged extension from the repository's Releases page, then use Extensions: Install from VSIX... in VS Code to install it locally.

Development

Install Node.js 20+ first so that node, npm, and npx are available in your terminal.

If you do not want to install Node.js locally, use Docker Compose or open the repo in the included Dev Container instead. Both paths provision Node 20, Python 3.12, and the shared nox automation.

# Build the extension host + webview through the shared automation entry point
python -m nox -s build

# Package a VSIX locally
python -m nox -s package

# Rebuild, package, and reinstall into local VS Code + VS Code Insiders
python -m nox -s reinstall

# Run the full local verification pipeline
python -m nox -s verify

# Lower-level npm commands are still available for a tighter inner loop
npm install
npm run compile
npm run bundle-webview

# Run unit tests
npm test

# Run the same verification pipeline in Docker
docker compose run --rm verify

# Build a VSIX in Docker
docker compose run --rm package

python -m nox -s reinstall installs the freshly packaged extension into both ~/.vscode/extensions and ~/.vscode-insiders/extensions, so reloading the window is enough to pick it up.

Press F5 in VS Code to launch an Extension Development Host with the extension loaded.

If npm is not recognized on Windows, install Node.js from nodejs.org and restart VS Code or your terminal.

For containerized local development, run Dev Containers: Reopen in Container in VS Code.

If Docker Desktop is already running, you can skip local Node.js entirely and use compose.yaml instead.

Export

Example Mermaid export of the markdown graph:

%%{init: {"flowchart": {"curve": "basis"}} }%%
flowchart LR
  n0("home")
  n1("reference · docs/reference")
  n2("settings · docs/reference")
  n0 --> n1
  n1 --> n2
  linkStyle default stroke:#6b7280,stroke-width:2px

Shared portable file operations and the read_file migration are documented in shared workspace tools.

Reviewed symbol edits

Preview Python declaration/Markdown section replacement or insertion with aeromd_plan_symbol_edit, then approve and apply its exact plan with aeromd_apply_edit_plan. Source versions and old text are rechecked; multi-file application is non-atomic. See the edit contract and limits.

aeromd_plan_rename previews bundled Python semantic edits against a complete bounded source/configuration snapshot in Web, desktop and CLI/MCP. Apply its exact reviewed plan with aeromd_apply_edit_plan. Changes, additions or deletions anywhere in the captured scope invalidate the plan, including unedited sources. aeromd.pythonSemanticBackend defaults to bundled; editor explicitly selects installed providers. A failed bundled operation never mixes or substitutes provider edits. AeroPy execution is independent.

aeromd_plan_refactor lists provider refactor actions and previews one exact selection. Supported complete edits include inline text changes, file moves with reference repairs, and provider-proposed deletions. Commands and unrepresentable effects return explicit limitations. Semantic safety and availability depend on the active provider; no generic safe-delete proof is inferred from a lack of search hits.

Semantic response evidence

Bundled Python definitions, references and rename previews return compact analysis by default: up to three items and 2 KiB per diagnostic category, with exact counts, countsByCode and per-category truncation. Existing concerns, diagnostics and unresolvedDependencies arrays remain as bounded samples; scopeConcerns supplies structured codes, source paths and UTF-16 ranges. Diagnostic sources distinguish bundled-basedpyright, aeromd-python-parser and aeromd-python-safety. Editor-published diagnostics retain their separate published-snapshot provenance and do not establish fresh analysis.

Set includeAnalysisDetails: true on the same tool to rerun against a new snapshot and return up to 50 items / 8 KiB per category. Individual messages are capped at 1,024 UTF-16 units and report messageTruncated. An analysis-completeness refusal retains its error code and exposes error.details.blockers, totalBlockers, blockerCountsByCode and blockersTruncated through CLI, MCP and editor tools. The blocker list includes up to five items / 4 KiB by default, or 100 items / 24 KiB with details requested. All totals describe captured evidence before response limits; truncated evidence does not make an analysis complete. The extension API accepts the detail flag as the optional sixth argument to getDefinition and getSymbolReferences, after the cancellation token.

Refactor discovery reports action result (returned or empty) separately from capability.status. Returned provider actions establish available; no actions yield unknown, since the public editor API cannot distinguish an absent provider from one returning no applicable actions. CLI/MCP still report BACKEND_UNAVAILABLE because those adapters do not provide editor refactoring. Graph search results now include an explicit id accepted by neighborhood and relationship-path tools; backlinks also accept it as nodeId.

Portable guided review

Use the bundled code-review skill to investigate a local change or checked-out PR through CLI, MCP or VS Code Web. The invoking harness selects the change, retrieves base-revision guidance and runs checks. AeroMD freezes existing text-file versions, resolves five focused rules with explicit precedence/provenance, imports exact-snapshot check attestations, validates findings and exports JSON plus Markdown. Preparation/reporting do not run a model or create GitHub comments. Explicit approved publication uses the saved-draft tools described below.

For CLI review payloads, use aeromd tool <name> --input - < input.json to read one UTF-8 JSON object from stdin until EOF. Stdin accepts up to 4 MiB of input bytes; tool-specific limits still apply. Inline --input <json> remains available for small requests, but large contexts can exceed operating-system argument limits.

The shared tools are aeromd_resolve_review_rules, aeromd_prepare_review, and aeromd_finish_review; inspect their full input schemas with aeromd tools. See the portable review skill for the end-to-end workflow. Reviews reject stale sources and report incomplete coverage instead of treating missing checks as success. Git metadata/check results are harness attestations, not independently authenticated evidence. A content fingerprint is a freshness guard, not a security signature.

This bounded slice supports at most 50 existing text files, 20 guidance entries and 100 omissions, with a 100,000-character limit for each head/base text and guidance entry. The entire serialized context (including metadata and fingerprint) is limited to 500,000 characters; finish inputs have a separate 100,000-character budget for checks, findings and investigation. Deletions, binaries, oversized files and renamed-from paths must be reported as omissions. If every changed file is omitted, use an empty changes array, at least one omission, and inventoryComplete: false; the report remains incomplete even when checks pass. Configuration discovery, persisted baselines, automatic fixes, historical rule mining and editable local/branch drafts remain follow-ups. AeroMD owns its GitHub review workflow and exposes draft/edit/revalidation/submission tools. AeroCode discovers and invokes those tools through its existing generic bridge while retaining its own basic GitHub tools and harness permissions. Contract fixtures test CLI, MCP and a real VS Code browser host; they validate tool behavior, not the quality of a model's review reasoning.

Use aeromd_review_draft to save, show or edit a PR review and aeromd_submit_review to publish the exact approved draft through the host's GitHub connection. CLI/MCP invocations share a versioned .aeroreview.json; Web uses the same canonical lifecycle with a host-owned submission confirmation. A durable attempt record prevents blind retries after an uncertain write. AeroCode is optional. See portable review lifecycle for approval bindings, limits, recovery and validated host coverage.

Repository Work

Enable Context to explore issues → PRs → commits/files and ticket references with source evidence. Add shared meeting/chat links, configure external ticket prefixes, or start from Related work in the workspace graph. Relationships persist in the work document and can be read or updated through editor and saved-file CLI/MCP tools. See work and code context for acquisition bounds, workspace mapping and revision behavior.

Run AeroMD: Open Repository Work to track configured repositories in a saved workspace document. Repository-grouped cards join issues, PRs, labels, Actions/check status and review attention. Table provides a compact ticket listing. The optional Gantt view maps editable working-day estimates to calendar dates or sprints, with arrows and finish-to-start constraints between blockers and dependents. Refresh is explicit and scoped, with cached snapshots and request limits. Local planning links and overlapping repository groups stay in the file for people and agents to edit. Usage, limits and architecture.

CLI and MCP can create, inspect, update and explicitly refresh that same saved document through aeromd_saved_work_*, then export a selected PR target for guided review. These operations persist immediately and use saved-file content versions; the editor's aeromd_work_* tools retain live buffer, navigation and Undo/Redo semantics. Saved-document tools and examples.

Repository Work also supports validated agent snapshot imports through the editor and saved-file CLI/MCP tools, with per-repository source, fetch time and coverage indicators.