Feature Request: Attach to Claude Code sessions running in tmux (remote/headless support)

Problem

Currently, Pixel Agents only tracks Claude Code instances that are spawned directly from VS Code's integrated terminal. Each character is tied to a terminal created by the extension via the + Agent button.

This means there's no way to visualize Claude Code agents that are already running outside VS Code — specifically in tmux sessions, which is becoming the standard way to run long-lived Claude Code workflows (headless, remote servers, agent teams, etc.).

With the rise of tools like agent-deck, agent-of-empires, and Claude Code's own --teammate-mode tmux, a significant portion of users now run multiple Claude Code instances in persistent tmux sessions — often on remote servers accessed via SSH — and would love to see them represented in the pixel office.

Use case

• I run 3-5 Claude Code agents on a remote server via tmux (persistent sessions that survive disconnects)
• I SSH into the server and manage them via agent-deck or raw tmux
• I want to open VS Code, connect via Remote-SSH, and see all my running tmux Claude agents appear as characters in the Pixel Agents office — walking, typing, waiting — just like locally spawned agents
• When I click a character, I'd like the option to attach to that tmux session in VS Code's terminal

Proposed solution

1. JSONL transcript discovery (no VS Code terminal needed)

Pixel Agents already watches JSONL transcript files to detect agent activity. The key insight is that these transcript files exist regardless of how Claude Code was launched — tmux, raw terminal, SSH, etc.

Instead of only monitoring transcripts tied to VS Code terminal instances, the extension could scan a configurable path for all active Claude Code JSONL transcripts:

~/.claude/projects/**/claude_*.jsonl

Or, for custom config dirs:

$CLAUDE_CONFIG_DIR/projects/**/claude_*.jsonl

Each active transcript file = one character in the office. The existing heuristic-based status detection (tool calls, file writes, reads) already works on these files — no changes needed to the state machine.

2. tmux session mapping

To enable "click to attach", the extension could map transcript files back to tmux sessions:

# List tmux sessions running Claude Code
tmux list-panes -a -F '#{session_name}:#{pane_pid}' | while read line; do
  session=$(echo "$line" | cut -d: -f1)
  pid=$(echo "$line" | cut -d: -f2)
  # Check if this pane is running claude
  if pgrep -P "$pid" -f "claude" > /dev/null 2>&1; then
    echo "$session"
  fi
done

Then when clicking a character, VS Code can:

const terminal = vscode.window.createTerminal({
  name: `Claude: ${sessionName}`,
  shellPath: 'tmux',
  shellArgs: ['attach-session', '-t', sessionName]
});
terminal.show();

3. Configuration

In the extension settings:

{
  // Enable scanning for Claude sessions outside VS Code terminals
  "pixelAgents.watchExternalSessions": true,

  // Enable tmux session discovery and attach
  "pixelAgents.tmux.enabled": true,

  // For Remote-SSH: scan transcripts on the remote host
  "pixelAgents.transcriptPaths": [
    "~/.claude/projects"
  ],

  // Custom Claude config directory (for dual-account setups)
  "pixelAgents.claudeConfigDir": "~/.claude"
}

How this fits the existing architecture

Looking at the current codebase:

• Character spawning: Currently tied to onDidOpenTerminal. This would add a second spawning path: file watcher on transcript directories. Both paths feed into the same character system.
• Status detection: Already works by parsing JSONL transcripts — fully reusable as-is. The idle → walk → type/read state machine doesn't need changes.
• Webview rendering: No changes needed. Characters from external sessions render identically.
• Agent-terminal sync (listed as a known limitation): This actually gets better with file-based discovery, since we're reading transcripts directly instead of trying to match terminals to sessions heuristically.

Visual indicators

External/tmux agents could have a small visual differentiator:

• A tiny tmux icon or SSH badge on the character's name tag (e.g., Claude [tmux])
• A different desk style or area of the office ("Remote Wing")
• Speech bubble showing the tmux session name

Scope and incremental approach

This could be implemented incrementally:

1. Phase 1: Watch external JSONL transcripts → spawn read-only characters (no attach, just visualization). Minimal code change.
2. Phase 2: Add tmux session discovery → enable "click to attach" via VS Code terminal.
3. Phase 3: Remote-SSH support → scan transcripts on remote hosts when connected via Remote-SSH extension.

Phase 1 alone would already be very valuable and should be relatively straightforward given the existing transcript parsing infrastructure.

Related context

• Claude Code's agent teams natively use tmux for split-pane mode (--teammate-mode tmux)
• Tools like agent-deck manage Claude sessions as tmux sessions with status detection
• The roadmap already mentions "Support for other agentic frameworks" — this is a step in that direction
• Many users run Claude Code on headless servers (Mac Minis, cloud VMs) and access via SSH

Environment

• Pixel Agents: latest from marketplace
• VS Code: 1.109+
• Claude Code: latest
• OS: macOS / Linux
• tmux: 3.x+

Would love to hear thoughts on this approach. Happy to contribute a PR for Phase 1 if there's interest!