feat: global agent discovery — show all Claude sessions across the machine

[Commandershadow9]

Motivation

Today, Pixel Agents only shows Claude sessions that are either started via the extension's "+" button or detected in the current workspace's project directory. But Claude Code sessions can run in many places:

• Other terminals — users often have multiple VS Code terminals or external terminal sessions
• Subprocess calls — claude -p "..." invocations from scripts, CI/CD, or automation tools
• Agent tool sub-agents — when Claude spawns sub-agents via the Agent tool, each gets its own JSONL in a subagents/ subdirectory
• Other workspaces — Claude sessions running in a different VS Code window or project

All of these sessions write JSONL transcripts under ~/.claude/projects/, but only the current workspace's directory is scanned. The result: the office feels empty even when multiple Claude sessions are actively working.

This PR makes one VS Code window show ALL active Claude sessions across the entire machine. Agents spawn when sessions start, animate when tools execute, and despawn when sessions end — the office becomes a live dashboard of everything Claude is doing.

Design decisions

Headless agents

Sessions without a VS Code terminal (e.g., claude -p subprocess calls, sessions from other windows) are represented as "headless" agents. They behave identically to regular agents in the UI — same animations, same tool status bubbles — but:

• Click → opens JSONL transcript in the editor (instead of focusing a terminal)
• Close → clean removal (instead of disposing a terminal)
• terminalRef is undefined (guarded with optional chaining throughout)

Activity-based lifecycle

Not every JSONL file represents an active session. To prevent the office from filling up with stale agents:

• Discovery filter: Only files >3KB and modified within the last 10 minutes are considered active
• Subagent filter: Files >2KB and modified within the last 5 minutes (subagents are typically shorter-lived)
• Auto-despawn: Headless agents whose JSONL hasn't been modified for 5 minutes are automatically removed
• Scan interval: Global scan runs every 2 seconds; headless activity check every 30 seconds

Subagent discovery

The Agent tool creates JSONL files in <session-uuid>/subagents/agent-*.jsonl. The global scan recursively checks these directories for active subagent files and creates headless agents for them, labeled with "(sub)" in the folder name.

Technical changes

File	Changes
src/types.ts	terminalRef now optional (vscode.Terminal | undefined), added isHeadless?: boolean and lastActivityMs?: number
src/constants.ts	New constants: GLOBAL_SCAN_INTERVAL_MS, HEADLESS_INACTIVITY_TIMEOUT_MS, HEADLESS_ACTIVITY_CHECK_INTERVAL_MS, ACTIVE_JSONL_MIN_SIZE, ACTIVE_JSONL_MAX_AGE_MS
src/fileWatcher.ts	New functions: globalScanForAgents() (recursive scan of all project dirs + subagent dirs), createHeadlessAgent(), checkHeadlessActivity(), helper functions isActiveJsonl(), isTrackedByAgent(), folderNameFromProjectDir()
src/agentManager.ts	persistAgents: terminalRef?.name (optional chaining). restoreAgents: skip terminal lookup for headless agents, restore isHeadless flag and lastActivityMs
src/PixelAgentsViewProvider.ts	New timers: globalScanTimer, headlessCheckTimer. startGlobalScan() method with 3s initial delay. focusAgent: headless → opens JSONL in editor. closeAgent: headless → calls removeAgent directly. dispose(): cleans up new timers

What users will see

1. Open VS Code with Pixel Agents
2. Start Claude Code in another terminal window, or run claude -p "..." from a script
3. Within ~3 seconds, a new character spawns in the office
4. The character animates when the session uses tools, shows status bubbles
5. When the session ends, the character despawns after ~5 minutes of inactivity
6. Sub-agents from the Agent tool appear as additional characters labeled "(sub)"

Relationship to other PRs

This PR builds on similar ideas as #101 (better detection) and #102 (multi-workspace), but goes further:

• fix: detect Claude sessions started outside of Pixel Agents #101 fixes detection of sessions in the current workspace → this PR discovers sessions in all project directories
• feat: detect agents across all workspace folders in multi-root workspaces #102 adds multi-root workspace support → this PR makes workspace boundaries irrelevant by scanning globally
• All three PRs can be merged independently without conflicts

Test plan

• Open VS Code, verify existing terminal-based agents still work normally
• Start claude -p "do something" in an external terminal — verify a headless agent spawns within ~3s
• Use the Agent tool in a Claude session — verify subagent character appears
• Wait 5+ minutes after a headless session ends — verify auto-despawn
• Click on a headless agent in the panel — verify JSONL file opens in the editor
• Close a headless agent via the UI close button — verify clean removal without errors
• Open a second VS Code window with a different project, start Claude there — verify it appears in the first window's office
• Verify no performance impact with many old JSONL files (the scan should skip inactive files quickly)

🤖 Generated with Claude Code