Skip to content
| Marketplace
Sign in
Visual Studio Code>AI>Armada AINew to Visual Studio Code? Get it now.
Armada AI

Armada AI

Lattice AI

| (0) | Free
Armada in VS Code: connect to your Armada Admiral, navigate every Armada area, and work the mission and voyage black box (failures, FIX THIS briefs, recovery, timelines, attempt diffs, overlap previews, conflict decorations) with live updates.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

Armada for VS Code

The Armada extension brings Armada into the editor. It connects to your Armada Admiral (the local one with no setup), shows the Armada navigation in its own view container, and works the mission and voyage black box: when a mission or voyage fails, the Admiral records where it failed, how, why, which files and missions conflicted, and the ranked recovery paths. The extension lists those entries for the repository you have open, hands the FIX THIS brief to your coding agent, and runs recovery paths with a dry run and a confirmation.

The extension is being built out to full parity with the dashboard, the TUI, Harbor and the CLI (VSCODE_EXTENSION_PLAN.md). Today, areas other than the black box open the matching dashboard page in your browser.

The Armada view container

The Armada icon in the activity bar opens two views:

  • Navigation: the dashboard's navigation model (the same one the dashboard sidebar and the mobile app use): Dashboard, Ask Armada, then OPERATIONS, BUILD, CONFIGURATION and SYSTEM, with hub tabs such as Planning and Black Box. Each page opens in the dashboard in your browser until the extension has its own view for it.
  • Failures: the black box tree (below).

While the extension is not connected, both views show what to do: connect, or open the output.

Connecting

The extension connects by itself after VS Code starts; nothing runs while the extension is activating. It takes the Admiral and the credential from the Armada settings already on the machine, so nothing about the connection lives in VS Code settings. It looks, in this order, at:

  1. Harbor: ~/.armada-harbor/settings.json (or $ARMADA_HARBOR_HOME). ServerLinkUrl names the Admiral Harbor links to, whose REST API is the same host and port over http or https, and AccessKey is sent as a bearer token. A running Harbor puts its Admiral first.
  2. The local Admiral: ~/.armada/settings.json (or $ARMADA_DATA_DIR): admiralPort and the local apiKey, sent as X-Api-Key to http://127.0.0.1:<port>. The Admiral writes the key the first time it starts.
  3. The TUI's server profiles: ~/.armada/tui.json, with each profile's session token from the TUI's credential store (the macOS Keychain or libsecret, else tui-credentials.json).

Entries for the same Admiral are merged, and every credential found for it is tried in turn. At startup the extension connects to the Admiral last picked with Armada: Connect, else to the first one that answers and accepts a credential.

Armada: Connect is the one connect command. It lists the Admirals found on the machine (with where each came from, whether it responds, and whether a credential was found) and Enter an Admiral URL... for any other. A key is asked for only when no stored credential works; it is tried as a bearer token and then as X-Api-Key, and the one that works is kept in VS Code secret storage for that Admiral.

Each connection probes GET /api/v1/status/health, checks the Admiral's contract version (the major part must match the extension's; otherwise it says whether the Admiral or the extension is too old; an Admiral from before contract versions, 1.3.0 and earlier, reports none and is treated as contract 1), then proves the credential with GET /api/v1/whoami. The context keys armada.connected, armada.connectionState, armada.role.globalAdmin and armada.role.tenantAdmin follow the result, for menus and when clauses.

The status bar shows the state and the target (Armada: local, Armada: armada.example.com, Armada: server too old, ...), and its tooltip says where the Admiral was found and which credential is in use. Click it for connection actions: open the dashboard, connect to another Admiral, reconnect or retry, disconnect, show the output, open the settings. Armada: Show Output opens the Armada log, which records every connection attempt and live-update change (never a key).

Armada: Disconnect drops the connection and removes a stored remote key; the extension then stays disconnected, also after a restart, until you run Armada: Connect.

The extension does not start an Admiral yet; start Armada yourself (for example with armada server start).

Live updates

The extension keeps one WebSocket connection (/ws) per Admiral, subscribes once, and passes every event to the surfaces that listen (today the black box). When the socket drops it reconnects after 5 seconds, doubling up to 5 minutes, and meanwhile polls every armada.liveUpdates.pollIntervalSeconds. With armada.liveUpdates.useWebSocket off it only polls.

Black box

  • Failures view in the Armada container (and, with armada.failures.showInExplorer, as Armada Failures in the Explorer): recent black box entries grouped by vessel, with kind, step and age. By default it shows only the vessel whose repository is open (matched by git remote URL against the vessel's RepoUrl). The view badge counts open entries.
  • FIX THIS: copy the brief, open it as a Markdown document with a preview, or send it to the editor chat.
  • Recovery paths: a dry run shows what will happen, a modal dialog confirms, and only then does the path run. Paths marked dataLossRisk are refused unless you tick an explicit acknowledgement.
  • Resolve entries and add notes.
  • Ask Armada About This Failure: opens the dashboard Ask page with the canonical prompt.
  • Armada resilience: right after the Summary the entry view shows whether Armada's own handoff and landing could have healed the failure (and what it could have done), the detection gap and invariant, severity with recurrence, the recoveries Armada already attempted, code pointers at the Armada build, the proposed Armada changes with acceptance tests and the regression test; outside handoff and landing, one line saying why no Armada change is suggested. An entry triaged ArmadaDefect carries a "Suspected Armada defect" badge. Draft Armada Fix Mission copies the top proposed change as a mission brief and opens it in the editor chat; Show Resilience Gaps lists the Armada resilience gaps (failure modes triaged ArmadaDefect in handoff and landing scope) page by page.
  • Entry view: Summary, Armada resilience, Where, How, Status, Why, Conflict, What would have prevented it, What Armada could change, Recovery (with each path's tracked success rate and, when a runbook is linked, the runbook name linking to the dashboard), Attempts, Recurring on this vessel (the vessel's configuration doctor: recommendations that keep recurring, with a link to an example entry) and Notes, with buttons for every action, including Timeline and Compare Attempts.
  • Black box timeline: one ordered timeline across the entry and its notes, the mission, the dock, the merge queue entry, the captain and the Harbor link, as a Markdown table, page by page.
  • Attempt diff: what changed between two attempts of a mission (or any two entries) side by side: captain, model, base commit, configuration, step, and the files only each attempt changed.
  • Mission overlap preview: before dispatching, enter a brief for the open repository's vessel and see the overlap warnings (active missions, reserved and hotspot directories) and brief lint warnings dispatch would return.
  • File decorations: files that conflicted in an open entry's landing get a BX badge and the hover text "conflicted in msn_x landing, 2026-10-28"; the vessel's hotspot directories get an H badge.
  • Live updates from the extension's single Armada WebSocket connection (see Live updates).

Requirements

  • VS Code 1.101 or later (or a compatible editor such as Cursor).
  • An Armada Admiral with contract version 1.x (or one from before contract versions), and a credential for it: one already on the machine (Harbor's access key, the local API key, a TUI session), or a bearer token from POST /api/v1/credentials or an API key entered in Armada: Connect.

Install from a VSIX

From the repository root, ./build-vscode.sh --install (or build-vscode.bat --install) builds vsix/armada-vscode-<version>.vsix and installs it. For a .vsix from a release, use code --install-extension <file>.

Settings

Setting Default Meaning
armada.tenant empty Optional tenant id; admin credentials use it to narrow lists to one tenant
armada.dashboardUrl empty Dashboard URL for links and Ask Armada; empty means Harbor's DashboardUrl for Harbor's Admiral, else the connected Admiral plus /dashboard
armada.fixThis.openPreview true Open a Markdown preview beside the FIX THIS editor
armada.failures.showInExplorer false Also show the black box tree in the Explorer, as Armada Failures
armada.failures.filterToWorkspaceVessel true Show only the open repository's vessel (falls back to all vessels when none matches)
armada.failures.includeResolved false Also list resolved entries
armada.failures.maxEntries 50 Entries loaded per vessel
armada.liveUpdates.useWebSocket true Listen on the Armada WebSocket
armada.liveUpdates.pollIntervalSeconds 60 Polling interval when the socket is off or down (10 to 3600)
armada.decorations.enabled true Conflict and hotspot file decorations
armada.decorations.hotspotLimit 10 Hotspot directories to decorate (0 turns them off)
armada.notifications.onCapture true Notify when an entry is captured for the open repository's vessel

Commands

Command What it does
Armada: Connect Pick an Admiral found on this machine or enter a URL, and connect (asks for a key only when none works)
Armada: Reconnect Connect again to the current Admiral
Armada: Disconnect Drop the connection and remove a key entered for that Admiral
Armada: Connection Actions... The status bar's quick pick of connection actions
Armada: Show Output Open the Armada log
Armada: Open Settings Open ~/.armada/settings.json, Harbor's settings, the TUI profiles, or the extension's preferences
Armada: Open Dashboard Open the connected Admiral's dashboard in the browser
Armada: Refresh Failures Reload vessels and entries
Armada: Toggle Workspace Vessel Filter Switch between the open repository's vessel and every vessel
Armada: Open Black Box for Mission... Quick pick of recent failures, or paste a mission, voyage or entry id
Armada: Copy FIX THIS Copy the brief to the clipboard
Armada: Open FIX THIS in Editor Open the brief as an untitled Markdown document (save it as .md if you want to keep it)
Armada: Send FIX THIS to Chat Open the editor chat with the brief attached; copies it when the editor has no chat
Armada: Run Recovery Path... Dry run, show the plan, confirm, then run with the confirm token
Armada: Resolve Black Box Entry Set Resolved, Duplicate, WontFix or ArmadaFixed, with an optional note and link
Armada: Add Note Add a note to the entry
Armada: Ask Armada About This Failure Open the dashboard Ask page with the canonical prompt pre-filled
Armada: Show Black Box Timeline Open the entry's combined timeline as Markdown (100 events per page, with Next Page and Previous Page)
Armada: Compare Black Box Attempts Pick another attempt of the mission (or enter any entry id) and open the side-by-side diff
Armada: Draft Armada Fix Mission Copy the entry's top proposed Armada change as a mission brief and open it in the editor chat (copied only when the editor has no chat)
Armada: Show Resilience Gaps Open the Armada resilience gaps (handoff and landing failure modes triaged ArmadaDefect, most severe first) as Markdown, 25 per page with Next Page and Previous Page; filtered to the open repository's vessel when exactly one matches
Armada: Preview Mission Overlap For the open repository's vessel (or one you pick), enter a title and brief and see the overlap and brief lint warnings; nothing is dispatched

Every entry command works from the tree view's context menu, from the entry view, or from the Command Palette (where it asks which entry).

The Ask Armada prompt is: "Show me the pertinent details from the black box for mission {id} and give me your opinion on why it failed and what could have been done differently". The extension opens /dashboard/ask?prompt=<prompt>, which starts a new conversation with the prompt in the message box; if the browser cannot be opened, the prompt is copied to the clipboard instead.

Errors

The extension never crashes on server errors. It explains each one: no connection, an unreachable Admiral, an Admiral or extension that is too old, a rejected key (401), a forbidden action (403), a missing entry (404), a changed mission or expired confirm token (409), a missing black box object (410), and an unavailable black box store or action host (503). The Failures view shows the current error with a click-to-retry row.

How it is built

  • Thin client. The extension imports the dashboard's own API client, types and helpers (@dashboard/api/client, @dashboard/types/*, @dashboard/lib/*) through the @dashboard/* alias the mobile app uses (tsconfig.json paths and the esbuild alias in esbuild.mjs), so there is no second copy of any route or DTO. npm run lint:shared lints those shared modules against the same sharing contract as the mobile app (src/Armada.Mobile/sharing.config.js and eslint.shared.js) plus the Node host's rules, so a dashboard change that breaks a non-browser host fails here and in the mobile app.
  • Shared client gaps. src/transport/hostClient.ts holds the few things the shared client does not: pointing it at an Admiral with the extension's credential, a typed reading of the health response (the shared getHealth returns a plain record), the mission/voyage/entry id dispatch for black box lookups, and dashboard URL builders. src/transport/errors.ts turns the shared client's errors into messages.
  • Layout. src/connection/ (discovery, contract check, connection manager, status bar), src/transport/ (shared client host side, the /ws event bus), src/surfaces/nav/ and src/surfaces/blackbox/.
  • Parity. parity.json tracks every dashboard route, tab, client call, event and settings field, the TUI-only surfaces, Harbor's menu and windows, and the CLI commands in scope, with the status of each; it is generated by scripts/vscode/generate-parity-manifest.py and checked by the VsCode.Parity test suite.

Development

cd src/Armada.VSCode
npm ci
npm run build              # type check (src and tests) and bundle to dist/extension.js
npm run lint               # ESLint, then the shared-module contract (lint:shared)
npm test                   # unit tests (Node test runner, fake vscode module, no VS Code needed)
npm run test:integration   # @vscode/test-electron; skipped when offline or without a display
npm run package            # ../../vsix/armada-vscode-<version>.vsix

The integration tests never read your ~/.armada: they point ARMADA_DATA_DIR at an empty temporary directory. To run them against a throwaway Admiral, start one with its own data directory and set ARMADA_VSCODE_TEST_DATA_DIR to it and ARMADA_VSCODE_EXPECT_ADMIRAL=1; the suite then checks the connection, whoami, the role keys, the navigation tree, the black box store and the WebSocket subscription.

From the repository root, build-vscode.sh (or build-vscode.bat) runs install, build, lint, tests and packaging into vsix/, and the vscode-extension GitHub workflow does the same in CI, plus the integration tests and the parity check.

License

MIT. See LICENSE.md.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft