The active account, always one glance away.

Principles

These four rules settle most design questions. When a proposal breaks one, the proposal changes.

• The CLI is the authority.The extension never reads credential files or the keyring, and never infers state the CLI didn't report. Every label comes from a JSON field named in this spec.
• Color means risk.The status bar item gets a warning background only when the wrong account could authenticate in this repo. Other problems use an icon and leave the background alone.
• One click per switch, never zero.Opening a workspace, focusing the window or changing settings can refresh the display, but only a user action can change accounts.
• Success is quiet, problems are specific.Confirmations go to the status bar for five seconds. Notifications are for problems, and each one names the cause and offers the fix as a button.

Status bar item

One item on the left (primary) side, because account state applies to the whole window. Its priority puts it right after the source control branch. The item's name is AISW Account, so users can hide it from the status bar context menu.

Tooltip

Installing aisw

Most people meet the extension right after installing it from the Marketplace, and at that moment aisw is usually missing. The extension never bundles or downloads the binary itself (ADR-0001). It finds an existing install, or runs the official installer the user picks in a visible terminal, then picks up the result without a restart.

• Find before asking.Check the setting, then PATH, then the places the official installers write to. Many “missing” binaries are installed, just not on the PATH VS Code started with.
• Install in plain sight.Install commands run in the AISW terminal, so the user can read exactly what runs. The extension only starts the command the user chose.
• Offer what works here.Methods are filtered by operating system and by the tools found on the machine. A Mac without Homebrew never sees a Homebrew command.
• No restart.When the install command ends, the extension finds the new binary itself, even if the new PATH only applies to new shells.

How the extension finds aisw

Step 3 checks only these fixed absolute paths, never a path inside the workspace. Every candidate must pass the version --json handshake before it is used. Detection runs again when an install command ends, when the AISW terminal closes, when aisw.binaryPath changes, and on window focus while aisw is missing.

First run

~ $ brew install burakdede/tap/aisw
==> Fetching burakdede/tap/aisw
==> Installing aisw from burakdede/tap
🍺  /opt/homebrew/Cellar/aisw/0.3.10
~ $

~ $ sh -c "curl -fsSL https://raw.githubusercontent.com/burakdede/aisw/main/install.sh | sh"
Installing aisw latest (aarch64-apple-darwin)
  Install dir:  /Users/you/.local/bin
  Downloading binary...
  Downloading checksum...
  Verifying checksum...

aisw latest installed to /Users/you/.local/bin/aisw

Note: /Users/you/.local/bin is not in your PATH.
~ $

After the install command

Wrong path and outdated versions

Switching

Both pickers use createQuickPick, so they can show busy while the list refreshes. A selected row runs exactly one CLI mutation. The status bar then switches to its spinner until the refresh and the scoped verify finish.

Empty states

After the switch

The adapter runs use or context use with --json, then re-reads status, then verifies only the tools listed in result.affected_tools. Tools the switch didn't touch never block a successful switch.

Notifications

Every notification names the problem in its first clause and puts the fix on the primary button. Remediation buttons come from the CLI's error.remediation when kind == "run_command" and safe == true. Clicking one opens the AISW terminal with that command.

Verify Active Accounts

[info] aisw 0.3.10 · CLI API 1 · schema 1 · progress 1
[info] status --context  exit 0  212 ms
[info] context use client-acme  exit 0  388 ms
[warn] verify  exit 1  301 ms
       codex  fail  tool binary not found on PATH
              → Install codex or run 'aisw doctor --json'

Profile lifecycle

Adding a profile can involve OAuth or an API key, so it runs in the integrated terminal and the CLI keeps its native prompts. Removing a profile handles no secrets, so it runs in the background behind a native confirmation, with Undo.

Add Profile

~/src/client-acme-api $ aisw add claude work
How do you want to authenticate Claude Code?
  › Sign in with browser (OAuth)
    Use an API key
Waiting for browser sign-in…
Saved Claude Code profile 'work'.
~/src/client-acme-api $

If shell integration hasn't activated within 3 s, the extension falls back to sendText with POSIX shell quoting, and refreshes when the terminal closes. That fallback can't read an exit code, so it shows no success notification.

Remove Profile

Commands and settings

All commands declare category: "AISW", so the palette shows “AISW: Switch Context” while menus show the short title. Context keys hide commands that can't run.

Context keys set via setContext: aisw.state (loading | ready | cliMissing | installing | binaryPathInvalid | incompatible | remote | error), aisw.cliInstalled, aisw.workspaceMismatch, aisw.hasProfiles, aisw.hasContexts. In remote windows every command, including Refresh, is a no-op. No default keybindings ship, to avoid conflicts; the README suggests one.

Settings

Get Started walkthrough

Contributed through contributes.walkthroughs. Its steps complete on real state, not on clicks:

1. Install the aisw CLI. Buttons run aisw.installCli and aisw.locateCli. Completes on onContext:aisw.cliInstalled.
2. Import the accounts you're signed into. Runs aisw init --no-shell-hook in the AISW terminal, with Add Profile as the alternative. Completes on onContext:aisw.hasProfiles.
3. Group profiles into a context. Completes on onContext:aisw.hasContexts.
4. Bind this repository. Types aisw workspace bind . --context into the AISW terminal.

Icons and assets

// integrations/vscode/package.json
"icon": "media/icon.png",
"galleryBanner": { "color": "#001436", "theme": "dark" },
"keywords": ["claude code", "codex", "gemini", "account switcher", "profiles"],
"engines": { "vscode": "^1.93.0" },
"capabilities": {
  "virtualWorkspaces": false,
  "untrustedWorkspaces": { "supported": "limited", "restrictedConfigurations": ["aisw.binaryPath"] }
}

Pin @types/vscode to the engines minimum (~1.93.0). The lockfile currently resolves 1.140, which lets code compile against APIs that older VS Code and Cursor builds don't have.

Codicon map

Implementation

The current extension.ts mixes state, rendering and commands in one class. Split it so each state in this spec is a pure function of CLI JSON and can be tested from fixtures without VS Code.

src/
  cliAdapter.ts      spawn, envelope parsing, verify-report parsing, timeouts
  contract.ts        payload types, version and feature checks
  state.ts           deriveViewState(status, list, contexts, workspace) → ViewState  (pure)
  statusBar.ts       render(ViewState) → text, icon, background, tooltip, a11y label
  pickers.ts         Switch Context, Switch Profile, Add, Remove Quick Picks
  terminalFlows.ts   AISW terminal, shell-integration execution, exit handling
  notifications.ts   copy deck plus remediation-to-button mapping
  refresh.ts         scheduler: handshake cache, sequence guard, mutation queue
  extension.ts       activation and wiring only

Refresh lifecycle

stateDiagram-v2
  [*] --> Loading: activate
  Loading --> Remote: env.remoteName set
  Loading --> CliMissing: ENOENT
  Loading --> Incompatible: version or feature check fails
  Loading --> Ready: handshake ok and reads ok
  Ready --> Ready: focus (debounced): status --context + workspace status
  Ready --> Switching: user picks a context or profile
  Switching --> Ready: refresh + verify affected_tools
  Switching --> Ready: ok false (rollback), error toast
  CliMissing --> Loading: binaryPath changed or Refresh
  Incompatible --> Loading: binaryPath changed or Refresh

• Handshake cache. Run version and capabilities once per binaryPath. Run them again only after a setting change, an explicit Refresh, or an unsupported_command error. A focus refresh then costs two processes instead of six.
• Sequence guard. Each refresh takes a sequence number. A result is rendered only if no newer refresh has started.
• Mutation queue. One mutation at a time. While one runs, focus refreshes are skipped.
• Scoped verify. Parse the report on exit 1, then check only tools[] entries whose tool is in affected_tools.

Fixture matrix

One fixture directory per state in the status bar table. Each holds the JSON for status --context, list, context list and workspace status. deriveViewState is tested against every fixture, and the real-CLI compatibility test seeds an isolated AISW_HOME to produce at least the exact, none, mismatch and verify-fail states.

Checklist

Ordered by dependency. The first four items unblock everything else.

• #257Parse the verify report on a non-zero exit, and scope verification after a switch to affected_tools.
• #257Make aisw.binaryPath machine-scoped and declare limited support for untrusted workspaces.
• #257Apply the remote guard in createAdapter() so no command starts a CLI process remotely.
• #257Binary detection order, install and update picker, Locate, and post-install import, as in Installing aisw.
• #256Add the fixture matrix and deriveViewState tests.
• #258Status bar states, tooltip and accessibility label, as specified above.
• #258Grouped Quick Picks, empty states, the workspace row, and aisw.switchToWorkspaceContext.
• #258Mismatch notification with once-per-window logic and the notify setting.
• #258Handshake cache, sequence guard, mutation queue.
• #259Shell-integration terminal flow with exit handling and the sendText fallback; bump engines to ^1.93.
• #259Background remove with a modal confirmation and Undo through backup restore.
• #260Icon, gallery banner, keywords, walkthrough, and pinned @types/vscode.
• #260Screenshots of every state in VS Code and Cursor, light and dark, attached to the PR.