AeroCode

Companion extensions can reuse configured remote model connections through the versioned model access API, including native Decisions requests. API keys remain inside AeroCode.

AeroCode is a browser-compatible, multi-model chat harness for VS Code Web. It supports OpenAI-compatible and Anthropic APIs, plus local LiteRT and Transformers.js runtimes for browser-compatible model packages. Assistant responses render Markdown, including lists, links, and fenced code blocks.

The Chat view appears in the Activity Bar. Use the gear icon in the Chat view header, or the AeroCode: Open Settings command, to configure the default and custom profiles, built-in profile visibility, system prompt, context limits, skills, MCP servers, and inline completions in the regular VS Code Settings UI.

Run AeroCode: Inspect Active Configuration from the Command Palette or Chat view menu to inspect the current chat's model, reasoning, budgets, compaction, and skills. Each row names its source: saved chat selection, profile, workspace or user setting, or shipped default. Normalized limits and unavailable model context budgets are identified. Select a row to open its existing setting, chat picker, or winning skill file; skill collisions explain which source won. The view is a fresh snapshot each time it opens. Like chat execution, settings are resolved without an editor resource or language override. Saved model and reasoning selections survive reload; a manually selected skill clears on reload, while a skill applied through a workflow preset is restored with that chat.

Press Enter or use the arrow in the lower-right of the prompt to send. During generation, the arrow becomes a stop icon. Use Shift+Enter for a newline and /clear to clear the conversation. Type / to open filtered command suggestions; use the arrow keys to choose one and Enter or Tab to insert it. The bottom row also provides a model-profile selector, reasoning-effort selector for compatible OpenAI-style and supported Claude models, and a + menu for active-editor context, additional files, tool discovery, and agent permission mode.

Use the New Chat toolbar action or /new to start another conversation. Chats are saved per workspace and restored after reload; use the Chat History toolbar action to reopen one. To place Chat in the Secondary Side Bar, use VS Code's native drag-and-drop or view context menu; VS Code remembers that layout. Extensions cannot contribute a view directly to the Secondary Side Bar as its initial location, so AeroCode does not override the user's saved workbench layout on activation.

Long conversations mount only nearby messages while remaining continuously scrollable with the mouse, touch, or keyboard. Reading older messages pauses following; a Jump to latest down-arrow appears above the composer only while away from the bottom. Run AeroCode: Export Transcript from the Command Palette to open a named aerocode-transcript-….md snapshot, then Save/Save As to keep it. The snapshot includes retained offscreen and full-length message text, plus live tool rows when the chat view is available; it supports full-text search, selection, and continuous screen-reader reading in the editor. Very large messages retain their bounded preview; Copy message still copies the complete original. Tool payloads load when their Details disclosure is opened. See transcript rendering for performance details.

Run AeroCode: Analyze Tool Usage to inspect the current chat, selected saved chats, or all saved chats in this workspace (up to 50). The local analyzer looks for failed calls followed by possible recovery, repeated failures, and recurring tool sequences in settled turns. It uses saved history, so verbose tracing is not required. These are observations to investigate; a later successful call does not prove what fixed the problem or that a workflow needs changing.

After a response finishes, AeroCode can offer a quiet tip with Inspect evidence, Copy for new chat, and Dismiss. Turn off configurableChat.toolUsageInsights.autoTips to use manual analysis only. The evidence opens as plain text. The copyable brief includes bounded excerpts, attempt references, argument changes, and known limitations, with common credential formats redacted. Review it before sharing. A new chat can use the brief to investigate a focused skill revision, draft feedback for a tool's maintainer, or decide that no change is needed. Analysis does not call models, rerun tools, edit skills, or send feedback.

The model picker ships with full-name profiles for GPT-6.1 Sol (the default), GPT-6 Luna, GPT-6 Sol, and GPT-6 Astra; Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5; the web-compatible Gemma 4 E2B and E4B LiteRT packages; and a q4 Qwen3 0.6B Transformers.js profile. Set configurableChat.showDefaultProfiles to false to hide every built-in entry. Custom profiles configured with configurableChat.profiles are appended to the picker whether or not the built-ins are visible:

[
	{
		"id": "private-terra",
		"label": "Private Terra",
		"provider": "openai-compatible",
		"model": "gpt-5.6-terra",
		"baseUrl": "https://gateway.example.com/v1",
		"reasoningEffort": "medium"
	},
	{
		"id": "claude",
		"label": "Claude",
		"provider": "anthropic",
		"model": "claude-sonnet-5-5",
		"baseUrl": "https://api.anthropic.com/v1",
		"reasoningEffort": "medium",
		"maxOutputTokens": 16384,
		"contextWindowTokens": 1000000,
		"reservedOutputTokens": 16384
	}
]

Set configurableChat.defaultProfile to the profile used by chat and inline completion. Its shipped default is sol-6.1 (gpt-6.1-sol). API keys are stored by provider and endpoint, so models on the same connection share credentials. Endpoint identity preserves case-sensitive paths and queries. After upgrading to endpoint identity v2, re-enter each remote connection's key with /connect or the next send's secure prompt. Legacy profile, provider, global, and old connection keys cannot establish their original endpoint (old connection keys lowercased paths and queries), so they are not reused or automatically migrated. Existing legacy secrets are left untouched. If a remote model has no stored credential, the first send opens the same secure prompt as /connect. Your message appears immediately with Preparing… while credentials, instructions, skills, and attachments load. Preparation failures or cancellation keep the prompt visible with Retry; retry uses the current chat configuration and updates the same bubble. Required context is ready before the model request starts, and token counts update afterward.

Workflow presets

Configure a chat, then choose Save as preset… in the + menu or run AeroCode: Save as Preset. Give it a name and optionally enter your own guidance and output preferences. Presets are saved in VS Code's workspace-local extension storage and survive Developer: Reload Window. They are available to other chats in that workspace, without changing global settings or repository files.

For example, select gpt-6-sol, choose high reasoning, and activate an existing review skill with /skill review. Save Aero reviewer with guidance “Focus on correctness and regressions” and output preferences “List actionable findings with file references, followed by validation gaps.” In another chat, choose Workflow presets…, select Aero reviewer, and choose Apply. Review the concise model, reasoning, skill, guidance, and output preview before confirming. Applying and clearing overrides are available only between runs; finish or stop the current request first.

The saved setup contains a model-profile reference, reasoning choice, optional skill reference, and only the guidance/output preferences you entered. It does not copy profile or skill definitions, credentials, conversation content, permissions, attached context, system prompts, or automatically loaded AGENTS.md instructions. Referenced definitions continue to come from their existing configuration and skill sources. A missing or incompatible profile or skill produces an explanation; restore that reference or update the chat selection and save a replacement preset. AeroCode does not silently select a different one. Reasoning choices are preserved for OpenAI-compatible and supported Claude models. If a referenced profile changes to a model that cannot honor the saved reasoning choice, restore a compatible model or explicitly choose Auto and save a replacement preset.

Applying a preset takes a snapshot into the current chat's existing selection and persistence path. Its model and reasoning take the same precedence as chat selections over configured defaults; later manual selections take precedence over the applied values. Existing profile, workspace/user setting, and skill discovery precedence stays intact. Guidance and output preferences add user-authored request guidance alongside the normally loaded instructions. AeroCode: Inspect Active Configuration identifies the applied snapshot and the source of each active selection. A preset skill reference survives reload; /skill <name> or /skill off replaces that selection through the normal skill path.

Use Workflow presets… or AeroCode: Workflow Presets to Rename, Duplicate, or Delete a saved preset. Those changes affect future applications; chats that already applied it retain their snapshot, including its name and guidance. New chats retain normal configuration resolution until you apply a preset to them.

Run AeroCode: Clear Preset Overrides to remove the applied snapshot and the current chat's model, reasoning, and skill overrides, including later manual changes. This also removes preset guidance/output preferences and returns model and reasoning resolution to the configured defaults and profile defaults, with no active skill. Conversation history and permissions remain unchanged. Clearing conversation content with /clear is a separate action.

Providers

• OpenAI-compatible: select an OpenAI built-in or custom profile. Custom gateways set baseUrl on their profile. Store the endpoint's key with /connect or AeroCode: Configure Credentials; it is held in VS Code Secret Storage instead of workspace settings.
• Anthropic: select a Claude built-in or custom profile. Custom Anthropic endpoints can also set baseUrl. Requests use Anthropic's browser-enabled Messages API. Built-in Claude 5.5 profiles use medium effort and a 16,384-token output cap; the reasoning picker can override effort for supported models.
• LiteRT: select Gemma 4 E2B (about 2.58 GB) or E4B (about 3.65 GB), or add a custom LiteRT profile. The model is downloaded and executed in the browser host, so availability and hardware requirements depend on the user's browser. The built-in Gemma profiles use a 32,768-token context with up to 4,096 output tokens. Custom LiteRT profiles must declare contextWindowTokens and reservedOutputTokens within the export's supported capacity. AeroCode passes these limits to LiteRT instead of relying on its 4,096-token runtime default. The model runs in a worker and stays loaded across successive tool calls and chat turns while its model and context capacity are unchanged. Every request uses a fresh conversation. Stop terminates loading or generation immediately; the next request creates a fresh worker and reloads the model. Loading, preparing context, and generation show their current stage and elapsed time. Switching providers unloads the previous local engine before the next model starts. Browser download caches are preserved.
• Transformers.js: select the curated q4 Qwen3 0.6B profile or add a compatible custom profile with an immutable 40-character revision. AeroCode bundles the exact runtime and WASM artifacts, prefers WebGPU, and falls back to WASM. Only the revision-pinned model weights are fetched lazily when first used. A failed WebGPU initialization retries WASM in a fresh worker. Stop cancels loading or generation by releasing that worker; the next request reloads the model, using the browser's cached files when available. Browser sessions skip ONNX Runtime's ConstantFolding optimization, which aborts initialization of the curated Qwen3 q4 export. Other graph optimizations remain enabled.

Local models default to configurableChat.localModelPromptMode: "lite". The starting prompt includes three small discovery tools (tools/search, tools/describe, and skills/search); full tool schemas and skill instructions are retrieved when needed. Workspace instructions and an active skill remain in the prompt, and discovered tools follow the same approval rules as other tools. Set the mode to "full" to restore the full skill inventory and initial tool descriptions. Remote API profiles keep their existing prompt. Lite mode reduces the starting overhead; large workspace instructions, attached files, and tool results still consume context.

Discovery searches tool and skill descriptions, not repository files. An empty skill search means no matching guidance was found; the model should continue by finding a workspace tool, inspecting its arguments, and reading the requested file. File contents already supplied in the conversation can be used directly.

For Anthropic, maxOutputTokens sets the request's max_tokens: thinking and answer text share this allowance. The default is 16,384 for built-in, custom, and legacy profiles. This is a conservative default for the current non-streaming adapter, not the model's advertised maximum. To change it, add a custom profile as above or override a built-in profile using the same id and its required fields. Values must be safe integers of at least 256; Anthropic also validates the selected model's output limit. Larger caps may require streaming and are not guaranteed to work with this adapter.

reservedOutputTokens reserves space when deciding whether to compact the conversation. For local models it also sets the generation output cap; it must be smaller than contextWindowTokens when both are supplied. Custom Transformers.js profiles without a reserve use a 512-token output cap. For remote providers it does not change the API output cap. Anthropic's effective reserve is always at least maxOutputTokens, including when the reserve is omitted or lower. AeroCode: Inspect Active Configuration shows both the actual API cap and the effective reserve. If the reserve reaches the declared context window, automatic context-budget compaction is unavailable; set a valid context window for the chosen model.

The Anthropic reasoning picker sends explicit low, medium, or high effort only for supported models. Auto leaves effort to Anthropic's default. Models without known effort support, including unrecognized custom identifiers, do not receive an effort parameter. If a response exhausts its output budget or contains no usable answer, AeroCode reports an actionable error and preserves response diagnostics and reported token usage. It does not automatically retry or spend another request's budget.

The + menu can attach the active editor or one or more selected files, up to the configured context limit, alongside each prompt. It also exposes the tools currently available to the agent.

AeroCode provides portable workspace basics directly and runs without AeroMD. VS Code for the Web is the primary host; the shared core has no VS Code or Node dependency.

Operation	AeroCode	AeroMD standalone
Discover/glob	workspace/list_files	aeromd_list_files
Bounded text read	workspace/read_file	aeromd_read_file
Literal text search	workspace/search_text	aeromd_search_text
Create/overwrite	workspace/write_file	aeromd_write_file
Exact text replacement	workspace/replace_text	aeromd_replace_text
Delete file	workspace/delete_file	aeromd_delete_file
Move/rename file	workspace/move_file	aeromd_move_file

AeroMD optionally adds ranked/semantic retrieval, graph relationships, metadata, references and language-provider navigation. AeroCode hides AeroMD's duplicate basics and exposes its specialized tools through the extension-tool adapter. The shared implementation is generated from AeroMD; see shared tool maintenance.

Reads return a version. Pass it as expectedVersion for replacement, deletion, move, or overwrite. write_file without it is create-only. Parent directories must already exist; moves never overwrite destinations. Text is limited to 1 MiB. Dirty editor buffers are readable but must be saved or reverted before writes. Writes follow Ask/Auto permissions; write/replace keep the post-edit review. Multi-root paths use numeric prefixes such as 0:src/app.py.

Read-only extension tools remain selectable in Manage Tool Permissions for Always Ask/Allow/Deny overrides. Use Default Behavior removes the override; known read-only tools then run automatically, including in Ask mode. Edit paths are validated after removing any numeric root prefix, and their resolved URIs must stay inside the selected root before filesystem access.

Repository results report explicit truncation and discovery scope. Treat absence as authoritative only when discovery is complete and results are not truncated. The graph is a Markdown/Python subset; filesystem tools also support CSV/config and other workspace text files. See the AeroMD skill for operation selection.

workspace/pending_changes gives the agent a bounded, model-readable snapshot comparison and unified diff; it is not native Git status. In single-root GitHub virtual workspaces it compares the live filesystem with the current GitHub HEAD tree, including changes that predate the chat. Other and multi-root providers use root-scoped session baselines. Baseline inventory, current inventory, fingerprint/content inspection, uncertain paths, and diff truncation are reported independently. Known added or deleted paths remain visible when their contents cannot be inspected. Incomplete inventories produce prominent warnings and never turn an unobserved path into a confirmed addition or deletion; Source Control remains the final review surface.

VS Code Web workspaces can opt into configurableChat.experimental.webGit.enabled. This adds scm/prepare_commit_message, which places an agent-written message in the native Source Control input and returns control to the user, plus scm/commit, which invokes the active provider's generic commit action. Preparing a message does not mutate the repository and needs no approval. Committing follows the configured Ask/Auto approval mode. The experiment checks for the required workbench SCM capabilities at runtime, does not activate Git extensions, and does not call Copilot or GitHub-specific commit-message commands. It is intentionally unavailable in desktop VS Code.

Web source-control providers decide how commits are published. For example, a virtual GitHub repository may publish the commit directly without a separate push. Pull-request tools registered by installed extensions through vscode.lm.tools remain available through normal discovery.

GitHub virtual workspaces also expose four atomic tools under the same experiment: github/status reads the current/default branch and exact HEAD, github/create_branch creates a remote branch from an expected HEAD, and github/commit_changes commits an explicit list of workspace-relative paths to a branch. github/create_pull_request creates a draft or ready pull request with an agent-written title and Markdown body, so PR creation does not depend on another extension contributing a language-model tool. AeroCode does not impose a branch naming convention, change-size threshold, or commit grouping policy; the agent follows workspace instructions such as AGENTS.md and the reviewed diff. The returned HEAD from each operation supports multiple ordered commits without switching or reloading the Web workspace. Remote branch operations explicitly return that the mounted workspace did not switch, together with a vscode.dev URL for the new branch. Installed-extension pull-request tools remain available through normal tool discovery alongside the built-in fallback.

Native Source Control and GitHub Web failures are returned to the bounded agent loop as recoverable tool errors. This lets the agent inspect status and choose a safe branch workflow after a provider rejects a commit, while cancellation remains terminal.

GitHub Actions inspection

Built-in read-only Actions tools use the same VS Code GitHub sign-in as the PR tools. They accept an explicit repository or Actions run/job URL; a GitHub virtual workspace supplies the default repository. No external MCP server or experimental Git write setting is required.

• github_actions/list_runs finds CI runs by repository, branch, workflow, or status.
• github_actions/inspect_run returns an exact run attempt, paged jobs, and failed steps. An older job URL selects that job's attempt even after a rerun.
• github_actions/read_job_log reads numbered evidence for one completed job. It defaults to the last 200 downloaded lines. Use a literal query to find errors, then startLine and maxLines to inspect surrounding context.

For example, ask: "Investigate this failed CI job: ". For direct invocation, use:

/tool github_actions/inspect_run {"url":"https://github.com/OWNER/REPO/actions/runs/RUN_ID/job/JOB_ID"}
/tool github_actions/read_job_log {"repository":"OWNER/REPO","jobId":123,"query":"error"}

Logs are downloaded as text through GitHub's short-lived redirect. Downloads are capped at 8 MiB; excerpts at 1,000 lines and 30,000 text characters, with individual lines capped at 4,000 characters. Search windows retain the first match on each line. Truncated lines include inclusive 1-based startColumn/endColumn and omittedBefore/omittedAfter counts in UTF-16 code units. Results report truncation and a continuation line when available. Tail/search operate on the downloaded prefix when the source exceeds the byte cap. Run, attempt, job, and commit identities stay attached to the evidence. Expired/inaccessible logs, unfinished jobs, and browser redirect restrictions are reported rather than treated as successful empty logs. Signed download URLs are not returned. Saved deny and Always Ask policies remain authoritative. These tools inspect ordinary CI and gh-aw runs; workflow dispatch, reruns, and cancellation are separate future operations.

Guided pull-request review

The agent can run a complete pull-request review workflow through the built-in github_review/* tools. AeroCode resolves the target deterministically from an explicit PR number paired with the GitHub workspace repository, a PR workspace URL, or the unique open PR whose head exactly matches the current branch. Those paths invoke no GitHub Pull Requests extension discovery tools. The extension's public visible-PR and active-PR tools are used only as fallbacks when deterministic discovery cannot resolve a target. A complete extension identity may select a different repository; an incomplete identity is never combined with the workspace repository.

Canonical metadata, patches, conversations, checks, and review submission use GitHub's documented APIs through the authenticated GitHub workspace adapter. API checks remain the authoritative baseline. When the GitHub Pull Requests extension is installed, its public checks tool may add attributed review requirements and failed-check logs, but enrichment failure never blocks API-derived review context. Target-discovery provenance and checks-enrichment provenance are reported separately.

Review analysis resolves guidance deterministically from configurableChat.reviewHumanGuide, configurableChat.reviewAgentGuide, each AGENTS.md applicable to a changed file (root to nearest), and an activated review skill. A generic review guide is used only when none of those sources is available. Every policy source and relevant evidence reference is retained on the local draft.

github_review/context returns a version 2 resolved, ambiguous, or unresolved result with structured diagnostics. Ambiguous branch matches include bounded repository-qualified candidates so the caller can select deliberately. Resolved context loads bounded PR evidence and exact diff-hunk digests. github_review/preview creates a local ReviewDraft; it does not create a pending GitHub review. github_review/revise can edit or omit individual inline comments, and github_review/show returns the exact current draft. Inline suggestions are ordinary review comments with an exact replacement rendered in GitHub's suggestion fence.

github_review/submit is one remote mutation and always requires a fresh per-submission approval. Auto mode and saved allows cannot bypass it; a saved deny still blocks it without prompting. Its approval context contains the complete batch: PR and pinned HEAD, review event, summary, inline ranges, rendered suggestions, hunk digests, and policy/evidence provenance. Immediately before submitting, AeroCode re-fetches the PR and rejects the draft if its HEAD or any referenced hunk changed. A successful action sends one batched COMMENT, APPROVE, or REQUEST_CHANGES review. COMMENT is the default; the other decisions require an explicit user choice before the draft can be created or revised.

Context compaction and lifecycle hooks

/compact replaces only the provider-facing context with a versioned, reviewable checkpoint plus recent complete turns. It never deletes or rewrites the visible conversation or canonical provider-protocol transcript. The host collects exact tool effects, artifacts, policy/capability state, active skill provenance, and tool-call/result continuity independently; a tools-disabled compactor model supplies only a strictly validated advisory summary. Compactor tokens are stored separately and are also included in total usage.

Compaction is automatic by default: no questions or confirmation are required. configurableChat.compaction.mode also supports manual and opt-in guided. Automatic and guided modes compare the projected next request with the usable model context window, using an 80% trigger and a 60% lower re-arm watermark. They never use cumulative run token usage. Unknown model context windows disable automatic behavior with a diagnostic; /compact remains available.

Repeated compaction summarizes the active checkpoint plus newer history. It does not repeatedly send the original transcript. Four recent complete user turns are the default target; the tail is reduced to fit 25% of usable context, capped at 15,000 estimated tokens, while keeping at least the newest interaction. Tool calls stay with their results. If the resulting context still cannot fit, the previous context stays active and the failure is reported in Output > AeroCode.

Use /compact review for a one-time review, or choose guided mode to review at the threshold. The short review shows the proposed objective, constraints and next steps. Confirm (or Skip questions) accepts it immediately; Answer questions asks at most three questions only when the summary identifies a material ambiguity; Add correction accepts one short correction. Empty answers skip individual questions. Cancel or close any dialog to retain the previous context. Corrections are stored verbatim with their position in the conversation before activation and carried into later checkpoints. Generated summaries remain advisory and can be imperfect; permissions and current host instructions are enforced separately. Use /compact inspect to view the active checkpoint. Visible and canonical history remain available throughout.

AeroCode also supports version 1 declarative lifecycle hooks from workspace .aerocode/hooks.json, installed hooks/aerocode.json components, and explicit VS Code extension configurableChat.hooks manifest metadata. In VS Code Web, a chatSkills extension can provide the contained <skill-root>/hooks/aerocode.json companion. Use /hooks for a read-only inventory. Enable or disable a component only through AeroCode: Manage Lifecycle Hooks; these actions are never model-callable, and trust is invalidated whenever the exact component digest changes. Web-safe hooks may add bounded advisory context or metadata, show a bounded notification, or request compaction at a safe boundary. They cannot execute code, call tools/models/network resources, interpolate variables, rewrite tool requests, or affect approvals and capability policy. Native OpenAI and Claude command/HTTP/prompt/agent/MCP hooks remain traced but capability-disabled in VS Code Web.

Tool activity

Agent tool calls appear inline as collapsible cards. Each card shows its current waiting, running, completed, denied, or failed state. Expand a card to inspect the tool source, JSON arguments, returned context or result, execution time, and errors. Large results are truncated in the chat display; the complete result remains in canonical history. With bounded tool results enabled (the default), the agent receives a reference and retrieves selected evidence through bounded read/search tools. Verbose JSON tracing remains available through Output > AeroCode when tracing is enabled.

Workspace instructions

The root AGENTS.md in every workspace folder is loaded automatically on each message. If an editor is active, the extension also loads nested AGENTS.md files from the workspace root down through that file's ancestor directories. Files are added root-first, so the nearest nested instructions are the most specific. The combined size is limited by configurableChat.instructions.maxCharacters.

Agent Skills

The extension discovers Agent Skills from .agents/skills and _agents/skills in each workspace folder. Search paths are configurable with configurableChat.skillsPaths; when names collide, the first configured path wins.

Each skill must contain a SKILL.md with name and description YAML frontmatter followed by Markdown instructions. AeroCode retains standard license, compatibility, metadata, and experimental allowed-tools declarations separately from its computed source provenance and SKILL.md digest; declared tool metadata never bypasses AeroCode approvals. Use /skills [query] to refresh and list skills, /skill <name> to activate one for subsequent turns, and /skill off to deactivate it. /skill <name> <prompt> activates it and sends a prompt immediately. Skill summaries are disclosed to the model, while full instructions are loaded only for the active skill.

On activation, skills/load lists a bounded inventory of files under references/, assets/, and scripts/ without loading their contents. skills/read_resource reads one containment-checked UTF-8 resource on demand; binary files and files over 256 KiB are reported but are not injected into model context. Scripts remain readable as package resources but are explicitly non-executable in VS Code Web. When a Web extension filesystem cannot enumerate package directories, safe package-relative paths referenced by SKILL.md are retained and size/content checks run when the resource is explicitly read.

Pinned imports are explicit and approval-controlled. skills/trace_bundle returns a versioned canonical component inventory for a GitHub repository folder at a full 40-character commit SHA without installing or activating it. skills/preview_install stages and validates a standalone skill, a manifestless skill collection, or a supported OpenAI/Claude plugin bundle and reports its license diagnostics and deterministic whole-package digest. Use . as the subpath for a repository-root bundle. skills/install commits that exact plan to VS Code's Web-compatible extension storage; skills/update_installation and skills/uninstall are separate explicit mutations. Existing single-skill records migrate transactionally on the next successful mutation.

Bundles are limited to 1,000 files and 16 MiB in total; per-skill progressive resource limits remain unchanged. Preview staging retains at most four active plans and 32 MiB in aggregate, evicting the oldest plan first. Install and update approval shows the bundle, format, supported contributions, exact source pin, digest, license, size, requirements, and diagnostics; updates show the old and new pins and digests. Single-hop symbolic links to regular files inside the pinned package are materialized without filesystem traversal; escaping, dangling, directory, and chained links remain rejected, as do submodules, truncated Git trees, unsafe paths, and case-colliding paths.

Valid Agent Skills and safe declarative prompt commands are active. Prompt commands are inert text: AeroCode performs no shell execution, code evaluation, variable interpolation, implicit tool invocation, or approval bypass. Agents, native hooks, local MCP servers, LSP, policies, scripts, and other unavailable host components are retained with capability-disabled diagnostics. Gemini extension metadata is available through the read-only tracer only. Precedence is workspace skill, explicitly installed bundle contribution, then VS Code chatSkills, with every discarded source reported by skills/list_installed.

Other commands are /new, /connect, /clear, /stop, /attach, /detach, /model, and /help.

Workspace skill refinement

Use /refine <skill-name> <correction> after a missed failure or a reusable lesson to generate a focused revision of an existing workspace skill. The selected chat model receives only the current skill body and your correction; the request has no tools and does not automatically inspect the conversation. The original YAML frontmatter, skill identity, and referenced package resource paths are preserved. A read-only diff opens before any workspace edit.

Command	Behavior
/refine <skill-name> <correction>	Generate a preview with a revision ID.
/refine preview <skill-name> <correction>	Explicit preview form, including skills named apply or history.
/refine apply <id>	Apply the exact current preview through the workspace file/edit review path.
/refine discard	Discard the pending preview.
/refine history	Inspect workspace-local snapshots, model identity, correction, timestamps, and before/after SHA-256 digests.
/refine rollback <id>	Preview restoring the original snapshot, then choose Rollback.

Apply and rollback reject stale source content, unsaved editor changes, moved workspaces, changed skill precedence, and symbolic-link targets. Workspace, installed, and extension skill precedence and configured settings are unchanged. Applied instructions are refreshed and loaded on the next request. Activate the skill with /skill <name> and rerun the same task to assess the revision; a successful edit does not establish that behavior improved. The existing provider usage counter includes refinement usage when the provider reports it.

This first workflow supports one existing workspace SKILL.md at a time, up to 32,000 characters with a correction up to 4,000 characters. It does not modify installed skills, extension packages, AGENTS.md, or settings. Previews are discarded when the extension restarts. The last 20 committed/recovery snapshots are held in VS Code workspace state. A prepared or rollback_prepared history record means finalization did not finish; its original and proposed snapshots remain available for guarded recovery with /refine rollback <id>.

External evaluation can compare ordinary workspace skill artifacts using the history record's target.uri, beforeSha256, afterSha256, and id. Digests identify the complete UTF-8 file contents. Artifact attribution alone does not prove that a task activated the skill; evaluators must capture that separately.

Inline Code Completion

Inline completion is available for text editors and notebook cells through VS Code's native ghost-text interface. It is disabled by default to avoid unexpected model usage. Enable it with AeroCode: Toggle Inline Completions or configurableChat.completion.enabled.

Completions reuse the configured default profile and its stored connection key, but use an independent system prompt and bounded prefix/suffix context. VS Code cancellation is forwarded to the provider whenever a completion becomes stale. The prompt and context limits are configurable under configurableChat.completion.

MCP Servers

Remote MCP tools are supported through the official Model Context Protocol SDK and Streamable HTTP transport. Configure servers with configurableChat.mcpServers:

[
	{
		"name": "deepwiki",
		"url": "https://mcp.deepwiki.com/mcp",
		"enabled": true
	}
]

Use /mcp to connect or retry and show server status, /tools [query] to list tools available to the agent, /tools all [query] to include hidden runtime tools and their reasons, and /tool <server/tool> <json> to invoke an enabled tool manually. Enabled tools are disclosed to the model for a bounded tool-use loop.

Installed-extension tools with public manifest provenance are enabled by default. AeroCode provides native ui/ask_questions and ui/manage_todos tools that work in its custom view without a VS Code chat-session resource. Unattributed runtime tools are hidden because VS Code does not expose enough public metadata to determine whether they work in a custom webview or VS Code Web. Opt in to a hidden tool by adding its exact ID to configurableChat.extensionToolAllowlist.

Portable extension-tool failures preserve their error code and structured details in the agent's tool result and the tool card's raw result. Details must be a JSON object within 128 KiB, 16 nesting levels and 8,192 values. Invalid or oversized details are explicitly marked detailsOmitted; the original failure message, recoverability, reported effects and artifacts remain intact. Large failures use the same saved-result pagination as successful tool results; their compact agent notices retain the failure status, recovery policy and reported effects. The tool card keeps complete structured JSON for raw inspection separately from its display preview.

AeroCode does not activate every installed extension during manifest inspection. When an installed-extension skill is activated, AeroCode selectively activates that skill's owning extension and refreshes vscode.lm.tools. Running /tools explicitly activates other manifest-declared tool providers that are compatible with the current host; VS Code Web requires a public browser entry point. A tool is exposed to the model only after it is both declared in the extension manifest and registered in vscode.lm.tools.

Raw tool arguments and results remain available in trace logs and under each tool card's collapsed Details disclosure. Rich question and todo cards show their interactive or task-oriented presentation without duplicating the JSON payload. Approval dialogs summarize the action and important fields instead of dumping raw JSON.

Agent actions are controlled by configurableChat.toolApprovalMode: Ask displays Allow Once, Always Allow, and Always Deny before workspace file edits, SCM mutations, installed-extension tools, and remote MCP calls; Auto permits them without confirmation. Always Ask can keep an individual tool gated even in Auto mode. These source-aware overrides are saved per workspace and can be changed through AeroCode: Manage Tool Permissions or the + menu. MCP rules also bind to the canonical server endpoint shown in approval details. Replacing a server URL while keeping its name does not carry over an endpoint's saved allow. Legacy name-only MCP allows become Always Ask, including in Auto mode, until a new endpoint-specific decision is saved. Legacy denies continue to block that name across endpoints; reset the legacy rule in Manage Tool Permissions before replacing it with endpoint-specific rules. A destination change while an approval is pending rejects the stale call and requires fresh discovery/approval. The approval modal's Review Full Context action opens a bounded, read-only JSONC document and leaves the approval available as a notification while it is inspected. Built-in read-only discovery, search, reading, inspection, and reference tools always run automatically. After a workspace write or replacement, AeroCode opens the native VS Code diff editor with the pre-edit content for immediate review and revert workflows. Tool results are returned to the model as untrusted context.

Every agent turn receives the available tool catalog. OpenAI-compatible providers use native function/tool calls with meaningful stable names and keep tool_choice set to auto, so the model decides when evidence or an action is needed. Native assistant tool calls and matching tool results are preserved in the conversation sent back to the provider. When Chat Completions rejects reasoning-effort function tools and directs the client to Responses, the same agent run continues through the Responses API without dropping the selected reasoning effort or returned reasoning items. Providers without native integration use a textual tool-call envelope as a fallback.

Large successful tool results are retained as immutable snapshots in the full chat transcript. Results above configurableChat.toolResultMaxTokens (default 20,000 estimated evidence tokens) are represented in model context by a named reference, original size, source and SHA-256. Smaller results stay inline. Token estimates use UTF-8 bytes / 3, rounded up, like context telemetry; they are not provider-tokenizer counts. Known small-model budgets lower the effective cap to one quarter of usable context (window minus output reserve), with a 256-token minimum. This is a fixed profile safeguard, not a dynamic per-read budget allocator.

context/list_results rediscovers references after compaction. context/read_result returns the whole snapshot when it fits the ordinary cap, otherwise a page up to that evidence-token cap plus compact provenance metadata. No mode selector is needed. Its optional offset and limit remain UTF-16 character positions/counts, not tokens: limit is a length, not an end offset. Oversized positive integer lengths are capped; invalid values get field-specific recovery guidance. Follow the returned nextOffset only when more evidence is needed; null means no further page. complete says whether the response contains the entire snapshot. Automatically chosen page ends avoid splitting surrogate pairs.

Use context/read_result with { "ref": "<result reference>", "full": true } to request the entire snapshot beyond the ordinary cap. Do not combine full: true with offset or limit. The host checks the estimated complete request, including history, instructions, native tool definitions or fallback envelopes, and output reservation. Agent reads are checked again after the consuming request is prepared, including newly queued hook advice and excluding expired one-shot context; hooks are not replayed for estimation. If that final check fails, only the unconsumed retrieval is replaced with recovery guidance and saved before sending. If the window/reserve is unknown or the result will not fit, it returns a recoverable error recommending bounded reads or search. It never silently truncates a full read or discards history to make it fit. This preflight uses estimates; existing conversation compaction remains separate.

context/search_result finds a case-sensitive literal with a targeted excerpt of at most 2,048 characters, also subject to the evidence-token cap. Its nextOffset advances past the match start to preserve overlapping matches. Cite the reference, digest and exclusive-end range. These tools inspect historical evidence, not fresh file or network state, and cannot use a filename, URL or another chat's reference as a read target.

The canonical transcript, visible tool results and trace remain complete. Native Chat Completions, Responses and fallback tool envelopes retain their pairing; only the model/compactor projection changes. Snapshots share the existing workspace-scoped chat history lifetime: they survive reload and compaction, remain isolated between chats, and disappear with chat deletion/history eviction. Reload validation uses VS Code’s Developer: Reload Window command so the workbench can flush its buffered storage; abrupt browser termination before that flush can lose recent workspace state. No additional filesystem cache or duplicate durable result store is created. Existing history with no host reference metadata is not retroactively offloaded. Storage/memory use still grows with the full transcript; failed history persistence is reported rather than silently truncating evidence. This feature bounds each new tool result, not the entire prompt, tool catalog or accumulation of results.

Set configurableChat.boundedToolResults to false for full-result projection. Compare fresh chats on the same extension revision with identical task, model, tools and budgets when measuring bounded versus full-result context. Disabling keeps existing snapshots readable and sends retained result bodies in full; it cannot undo earlier compaction. Re-enabling restores references for snapshots already captured, while results obtained with the setting disabled stay inline. Read/search/list still use the existing tool permission, cancellation and trace path, and do not rerun the original tool or grant new permissions.

All tools discovered from enabled MCP servers are available to the bounded tool-use loop. Use VS Code Settings to add, remove, or disable MCP servers.

VS Code Web cannot start local stdio MCP servers. Endpoints must use HTTPS Streamable HTTP and provide CORS headers that allow the browser host. The initial integration supports unauthenticated endpoints; OAuth and secret-backed custom headers remain future work.

Agent tracing

Set configurableChat.trace.enabled to write verbose JSON events to Output > AeroCode. Events include the provider turn and tool-selection mode, provider responses, tool arguments, tool results, and errors. API keys are never added to trace events.

Set configurableChat.trace.saveToWorkspace to also write the current session as JSONL under .configurable-chat/traces/ in the first workspace folder. Both destinations can contain prompts, AGENTS.md content, and source returned by tools; keep tracing disabled when that content should not be retained. configurableChat.trace.maxCharacters bounds each string field.

OpenTelemetry export

AeroCode can also export agent, turn, model, tool, approval, retry, and terminal spans to any OTLP/HTTP trace endpoint. Set configurableChat.telemetry.exporter to otlp-http, then choose the generic custom destination or the langsmith preset. For LangSmith, optionally set configurableChat.telemetry.langsmithProject; its standard OTLP endpoint is used when no endpoint override is configured. Run AeroCode: Configure Telemetry Credentials to store a LangSmith API key or custom OTLP headers in separate, destination-scoped VS Code SecretStorage entries.

Export is structural and content-free by default. Prompts, responses, tool arguments, and tool results each require a separate machine-scoped opt-in. Even when enabled, secret-shaped keys and common credential formats are redacted and values are bounded by configurableChat.telemetry.maxContentCharacters. Non-local endpoints must use HTTPS. Export is bounded and fail-open: telemetry backpressure, configuration errors, or collector failures do not interrupt the agent run.

Parity Roadmap

The official jupyterlite/ai project under refs/ai is the behavioral reference. Work is prioritized as follows:

1. Skills and /skills
2. Inline code completion (initial provider complete; notebook-wide context remains)
3. MCP integration (initial remote Streamable HTTP client complete; OAuth remains)
4. Unified built-in and custom model picker (complete)
5. Browser retrieval tools
6. Diff and review workflows
7. Conversation save and restore (complete)
8. Common slash commands
9. Context usage display
10. Configurable custom providers

Audio notifications

Enable AeroCode › Audio Notifications in Settings (configurableChat.audioNotifications) for a short chime when a response finishes, a request fails, or an approval, question, compaction review, or model download confirmation needs your attention. Sounds are off by default. Cancelled requests and restored chat history stay silent.

After enabling, click or type in the chat once to allow browser audio. Sounds can play while the chat is hidden, as long as the browser keeps the view running and allows audio. Muted tabs and browser autoplay restrictions can prevent playback; missed sounds are not replayed when you return.

Token counts

The chat composer shows cumulative provider-reported usage and the estimated current context. Turn AeroCode › Show Token Counts off in Settings (configurableChat.showTokenCounts) to hide all token displays; usage continues to be recorded. Expand a composer count or the token line beneath a user message to inspect the whole turn (all model calls and automatic compaction for that request), including its tool argument/result estimates. Completed tool cards also show their estimated context footprint. Turn details and chat totals survive reopening a saved chat.

• Summaries use compact numbers (for example, 12.4k tokens). Expanded details show exact totals and separate input/output counts when the provider supplies them. ≈ marks estimates; * marks partial usage and expands to explain missing reports. Missing usage remains unavailable, distinct from a reported zero.
• Chat totals include repeated input across requests, retries with returned usage, and compaction. Tool estimates are informational and are not added to those totals.
• Context uses the active, possibly compacted transcript, system/skill/workspace instructions and tool definitions. It is an estimate (≈), not a billing count. The percentage uses the full model window; expanded details and the tooltip state the output reserve. Models without a known window still show an estimate, with limit unknown.
• Unsent composer text and attachments are excluded. Tool result estimates use the shortened result passed into context when large-output bounding is enabled.
• Older chats retain previously saved totals; per-turn details are available for turns recorded with this feature. Usage metadata is never sent to the model.

Coordinated AeroMD development

Merge/release AeroMD 0.4.0 first, then merge this integration. Browser CI installs bpcarson.aeromd from the Marketplace; it cannot pass activation against 0.3.x. To test both PR checkouts before release, build AeroMD and run:

AEROMD_EXTENSION_PATH=/absolute/path/to/aeromd npm run test:e2e

The manifest dependency installs AeroMD; the runtime API/version check enforces the minimum contract because VS Code extension dependencies cannot pin versions.