Yonso VScode Claudes — Agent Handoff

This file is the canonical project context for coding agents working in this directory. Read it before changing the extension. CLAUDE.md imports this file so Claude Code and tools that support AGENTS.md receive the same instructions.

Project

Yonso VScode Claudes (display name; the internal id deliberately stays ai-agent-manager so installs update in place and persisted state survives — never change name/publisher) is a strict-mode TypeScript VS Code extension that presents Claude Code terminals as named, persistent agents. It supplements VS Code's integrated terminal; it does not replace it.

• Current extension version: 0.9.0
• VS Code engine: ^1.93.0
• Entry point: src/extension.ts
• Production bundle: dist/extension.js
• Tests: Vitest files under test/
• Package manager: npm; keep package-lock.json in sync

This project is a standalone Git repository. Do not stage, commit, or push unless the user explicitly asks.

Product decisions to preserve

These are deliberate UX decisions made with the user. Do not reverse them without an explicit request.

• Keep one flat, WhatsApp-style agent list. Do not restore groups, a native Agent Outline, or a redundant AGENTS section label.
• The sidebar header must read AI AGENTS with no colon: the view's name in package.json must equal the container title exactly, and nothing may assign webviewView.title at runtime. Any mismatch (the pre-0.6.0 state used a no-break-space name) makes VS Code render the merged single-view header as AI AGENTS: <name> (2026-08-06).
• The view title bar holds exactly one button: + New Agent. The Switch Agent and Refresh toolbar buttons were removed 2026-08-06 at the user's request; both commands stay available from the Command Palette. Do not add title-bar buttons back.
• No search bar in the sidebar (removed 2026-08-06 at the user's request, along with the filter toolbar buttons and the orphaned fuzzy utility). The Switch Agent quick pick is the keyboard path to an agent.
• Creating an agent is one click: launch Claude Code immediately, with no provider, name, command, group, or working-directory questions.
• Use the active project's workspace folder as the new agent's working directory.
• Ctrl+Shift+C creates an agent and always ends with a maximized Terminal panel. It must never toggle an already-maximized panel back to its normal size; the keybinding is split on the panelMaximized context key so the maximized case runs plain New Agent. The sidebar New Agent button creates one without forcing maximization.
• Ctrl+Tab / Ctrl+Shift+Tab cycle focus through agent terminals in sidebar order, wrapping at the ends (aiAgents.nextAgent / aiAgents.previousAgent), and must work no matter what is focused — including inside a terminal. Chosen by the user 2026-08-06 (superseding, same day, both the Ctrl+Alt+]/[ brackets and the Ctrl+Alt+Tab combos), deliberately shadowing VS Code's editor-history Ctrl+Tab; do not restore the older bindings.
• Terminal-focus reality: keystrokes inside a terminal go to the shell unless the resolved keybinding's command is in terminal.integrated.commandsToSkipShell, and extensions cannot contribute defaults to that list — this is why Ctrl+Alt+Tab was dead in terminals. ensureCommandsSkipShell() in extension.ts therefore merges the extension's keybound command ids into the user-level setting on activation (additive, idempotent, never removes entries). Keep that list in sync with contributes.keybindings.
• Close guard (2026-08-06): while any agent terminal exists (even idle) and aiAgents.confirmWindowClose is on, the aiAgents.closeGuardActive context key reroutes the close-window keyboard paths (Cmd+W/Ctrl+W with no editors open, Cmd+Shift+W/Ctrl+Shift+W) to aiAgents.confirmCloseWindow and quit (Cmd+Q, Ctrl+Q non-Windows) to aiAgents.confirmQuit: a blocking modal names the live agents, cancel is the safe default, confirm runs the stock workbench command. The guard must never fire with no live agents, must not intercept the kill-focused-agent Cmd+W case, and cannot cover mouse-initiated closes (no extension API). It replaces the pre-0.6.0 per-machine -workbench.action.closeWindow user-keybinding workaround.
• Cmd+W (Ctrl+W on Windows/Linux) kills the focused agent (aiAgents.killFocusedAgent) while an agent's terminal has focus — the user explicitly wants it to replace VS Code's default close-a-tab / close-the-window chain there (2026-08-06). The keybinding is scoped by terminalFocus && aiAgents.activeTerminalIsAgent; extension.ts maintains that context key from active-terminal and agent-list changes. The kill is guarded by an are-you-sure modal naming the agent (user request 2026-08-06, superseding the same-day no-confirmation decision — Cmd+W is close-tab muscle memory and was killing agents by mistake); Cancel/Esc is the safe default, and confirming closes the terminal and removes the record. The sidebar's right-click red Kill agent action stays confirmation-free (a right-click menu choice is already deliberate). Outside agent terminals Cmd+W must keep stock VS Code behavior — never widen this binding.
• New Claude agents start with auto mode on: ClaudeProvider appends --permission-mode auto at launch unless the configured command already sets a permission mode or skips permissions. The flag lives in the launch command, not the stored agent command.
• No unread counter is displayed anywhere: neither a number badge on the Activity Bar icon (do not set WebviewView.badge) nor a pill on list rows. The internal unread tracking stays, but nothing renders it.
• Popup notifications are off by default (aiAgents.showNotifications: false, user request 2026-08-06). The sidebar is the status surface; do not add new popups.
• The list webview reconciles rows in place, keyed by agent id. Never rebuild the row list on a state update (replaceChildren + recreate): streaming agents refresh the list continuously, and a rebuild landing between mousedown and mouseup destroys the pressed row so its click never fires — that regression made opening an agent take several clicks. (The preview subtree is re-rendered only when its text actually changes; that in-place swap is fine.)
• Use the pixel Clawd character in media/clawd.svg, not a robot, initials, or the Anthropic starburst.
• Each row shows the name, status, model, 24-hour timestamp, and latest human-visible message preview. Do not show the working directory or the redundant words Claude Code in the row.
• The model chip sits beside the status label as a quiet monospace pill (Opus 5, Fable 5, Haiku 4.5) and is hidden entirely when no model is known — never show a placeholder there (user request 2026-08-08). It is read from the transcript's assistant rows (message.model), not from the launch command or a config file, because that is the only source that reflects a mid-session /model switch. Sidechain (sub-agent) rows and Claude Code's <synthetic> placeholder rows must stay excluded so a helper model never replaces the session's own. formatModelLabel() in src/util/model.ts owns id → label mapping (current claude-opus-5 ids, legacy claude-3-5-sonnet-…, and Bedrock/Vertex decorations); unknown ids degrade to a trimmed id rather than disappearing.
• The agent name renders as a terminal-style tag — dark text (--vscode-terminal-background) on --vscode-terminal-ansiCyan, monospace — matching the session-name statusline tag Claude Code prints in the terminal (user request 2026-08-06).
• The latest-message preview spans the row's available width, wraps to at most 15 lines, and stores at most 1,500 characters. It preserves line structure and renders minimal markdown (bold, inline code, code fences, lists, headings, quotes) through DOM-safe createElement/textContent building only — never innerHTML. Slash-command transcript rows (<command-name> …) and hook-injected <system-reminder> content never become previews, and a /clear resets the stored preview.
• The preview shows only runtime.messagePreview. Lifecycle placeholder strings (Output received, Command running, Waiting for input…) must never render in the row — a ready agent with no message shows an empty preview (user request 2026-08-06; runtime.activity is still written and persisted, just not displayed).
• Claude usage meters render at the bottom of the sidebar styled like the CLI's /usage screen (user request 2026-08-06): per meter a bold title (Current session, Current week (all models), Current week (Fable)…), a periwinkle #b1b9f9 bar — the CLI's own bar color, sampled from its output; keep the 70%/90% warn/hot recolors — with N% used beside it and a CLI-phrased Resets 6pm (Asia/Jerusalem) line under it. Meters parse the usage payload's limits array first (session / weekly_all / weekly_scoped with scope.model.display_name, e.g. Fable) because the legacy top-level seven_day_opus-style buckets are null on current responses — that was exactly the bug that hid the Fable meter; the legacy buckets remain as a fallback for older payloads. Fed by ClaudeUsageService, which reads the local Claude Code sign-in read-only and calls the same endpoint the CLI's /usage screen uses. Credential sources: ~/.claude/.credentials.json and the macOS Keychain are both read every fetch and tried freshest-first (orderCredentials), with 401/403 falling through to the next token — a stale credentials file beside a live Keychain sign-in was exactly the bug that hid the meters until 0.6.0. When no meters can be fetched the strip shows the reason (Usage unavailable: …) instead of hiding (user request 2026-08-06 — the user may ask to remove that diagnostic line later); only aiAgents.showUsage: false hides the strip entirely. The service must never write, refresh, or log credentials.
• The sidebar's bottom holds exactly one button — Resume a closed session — between the agent list and the usage meters (user request 2026-08-08). Pressing it unfolds an in-sidebar list (deliberately not a quick pick, chosen by the user) of this workspace folder's stored Claude sessions, newest first: title, last-active time, model chip, git branch. Clicking one starts a new agent whose command is claude --resume <id>, which keeps the never-revive-a-record rule intact — the old agent record is gone for good; only the conversation comes back. The stored command keeps --resume so a later Restart returns to the same conversation. Session ids reach a shell command line, so isSessionId() shape-validates them before launch.
• The closed-session list reads Claude Code's own transcripts under ~/.claude/projects/<encoded cwd>/, so sessions this extension never managed appear too. It must stay read-only (never write, rename, or delete under ~/.claude), stay lazy (loaded only while the panel is open — these files reach tens of megabytes), and stay bounded (48 KB head + 48 KB tail per file, newest 60 files; ~20 ms for 87 sessions). Sessions already open as live agents are filtered out via runtime.sessionId, and sessions with no non-sidechain assistant answer are treated as stubs and hidden.
• Rows have no hover actions. Right-clicking a row opens a one-item context menu whose red Kill agent action closes the terminal and removes the agent, with no extra confirmation. Do not restore the hover X, the overflow/action menu, or separate terminal/stop hover buttons.
• An agent record exists only while its terminal exists. Never relaunch an existing agent: clicking a row, Open Terminal, and Switch Agent only reveal. When an agent's terminal closes, its process exits, or its launch fails, the record is removed immediately — a terminal-less agent must never be listed. Explicit relaunch exists only as the Restart command on a live agent and the off-by-default restoreOnStartup/autoRestart settings.
• Startup reattachment is PID-verified (2026-08-06): a name-matching terminal is adopted only when its processId equals the agent's persisted runtime.processId. A window reload keeps the pty process, so reattachment still works; after a full VS Code close the process is dead even when VS Code "revives" the pane with a fresh shell — those revived look-alike panes are disposed (claimRestored in TerminalController, mirrored in handleOpenedTerminal) and the record is dropped, because a row pointing at a dead, empty terminal is worse than no row. Never adopt or dispose a terminal whose PID cannot be read.
• When the agent's process exits cleanly on its own (the user typed exit in Claude — shell integration reports exit code 0/unknown, or a SessionEnd reason that exits the CLI: prompt_input_exit, logout, exit), the terminal closes together with the record (user request 2026-08-06, reversing the earlier keep-the-shell decision). A non-zero exit keeps the terminal open so the error stays readable, and a session end that leaves the CLI running (/clear, unknown reasons) must never close the terminal.
• Keep provider-specific behavior out of the view. New providers belong behind AgentProvider and monitoring implementations behind AgentMonitor.
• Never scrape terminal buffers or patch a user's Claude configuration. Claude state, /rename, and the latest-message preview come from the bundled per-terminal Claude plugin and hook bridge.
• Claude lifecycle hook events are authoritative. Terminal redraw or shell output must not change an already completed response from Idle back to Executing.
• Continue using the built-in VS Code terminal and supported APIs. Degrade gracefully when shell integration or Claude hooks are unavailable.

Architecture map

• src/agent/: durable agent model and lifecycle orchestration
• src/providers/: provider interface, Claude provider, and generic provider
• src/monitor/: shell integration, Claude hook file source, and future monitor adapters
• src/terminal/: integrated-terminal creation and control
• src/sessions/: stored Claude sessions for the closed-session list (ClaudeSessionRecords is pure/testable; ClaudeSessionHistory holds the filesystem side)
• src/usage/: Claude plan usage meters (ClaudeUsageRecords is pure/testable; ClaudeUsageService holds the vscode/network side)
• src/views/: rich sidebar webview and status bar
• src/storage/: versioned persistence codec
• src/commands/: command workflows and registration
• claude-plugin/: bundled hook manifest and event bridge used only by managed Claude terminals

src/extension.ts is the dependency-composition root. Avoid global mutable state. Keep agent-provided text escaped or assigned through DOM text properties, retain the webview content-security policy, and never persist VS Code Terminal handles.

Required checks

On a new machine, install Node.js 20 or newer, clone this repository, and initialize the project with:

cd yonso-claude-vscode
npm ci

Use npm ci, not a copied node_modules directory, to reproduce the dependencies locked in package-lock.json. Make changes in src/, test/, claude-plugin/, or the project documentation; do not hand-edit generated dist/extension.js.

Run this before handing off a code change:

npm run check

For a production bundle and VSIX:

npm run package

The package command performs type checking, linting, tests, and a production build before creating ai-agent-manager-<version>.vsix in this directory. Verify the artifact with unzip -t. For a release change, update package.json, package-lock.json, and CHANGELOG.md consistently before packaging.

Current implemented behavior

Version 0.9.0 includes the flat rich list with in-place row reconciliation (single-click open even while agents stream), drag reordering, quick-pick switching plus Ctrl+Tab/Ctrl+Shift+Tab cycling that works even with a terminal focused (commands auto-added to terminal.integrated.commandsToSkipShell), Cmd+W killing the focused agent behind an are-you-sure modal while an agent terminal has focus, the close guard modal on the close-window/quit keyboard shortcuts while agents are alive, a colon-free AI AGENTS header, a title bar with only the New Agent button, persistence with PID-verified terminal reattachment across window reloads (dead revived terminals are disposed and their records dropped after a full VS Code close), Claude hook-driven lifecycle status, /rename synchronization, bounded last-message previews rendered with Claude-terminal-like markdown formatting (slash-command rows filtered, /clear resets the preview, lifecycle placeholders like Output received never shown), cyan terminal-style name tags, per-row model chips read from the transcript, the bottom Resume-a-closed-session panel listing this folder's stored Claude sessions, 24-hour row timestamps, Claude-style usage meters at the sidebar bottom mirroring the CLI /usage screen — titled periwinkle bars with N% used and Resets … lines, parsed from the payload's limits array so the Fable weekly meter shows (multi-source freshest-first sign-in reads, visible failure reasons) — no search bar, no visible unread counters, popup notifications off by default, the Clawd artwork, one-click agent creation, Claude launches with auto mode on, the Ctrl+Shift+C always-maximized flow, the red Kill agent right-click action, and automatic removal of any agent whose process exits, whose terminal closes, or whose launch fails — a clean self-exit also closes the terminal, and clicking a row never relaunches an agent. Read README.md and CHANGELOG.md for the public behavior and release history before making substantial changes.