Auto-detect existing CLI agent sessions on startup

[dbromkish]

Summary

Termix currently only shows sessions created within its own interface. Users who already have Claude Code, Gemini CLI, Codex, or OpenCode sessions running in separate terminals see an empty dashboard when they first open Termix.

This feature would prompt the user on first launch (or when no sessions exist) asking whether they'd like Termix to scan for existing agent sessions. Sessions are only fetched if the user opts in — no automatic scanning without consent.

User Flow

1. User opens Termix with an empty dashboard (no active sessions)
2. A prompt/banner appears: "We detected CLI agents on your system. Would you like to import existing sessions from Claude Code, Gemini CLI, Codex, and OpenCode?"
3. User clicks "Import Sessions" → Termix scans local agent data and populates the sidebar with detected sessions
4. User clicks "No thanks" → prompt is dismissed; preference saved so it doesn't ask again
5. A manual "Scan for sessions" button remains available in settings or sidebar for later use
6. The preference can be toggled in Settings (e.g., "Auto-import external sessions on startup")

Agent Session Storage

Each supported agent stores session data locally that can be scanned:

Agent	Storage Location	Format	Session ID Pattern
Claude Code	~/.claude/history.jsonl	JSONL entries with sessionId, project, timestamp, display	UUID
Gemini CLI	~/.gemini/tmp/[hash]/chats/session-*.json	JSON with sessionId, lastUpdated, messages[]	UUID
Codex	~/.codex/sessions/YYYY/MM/DD/*.jsonl	JSONL with session metadata in first line	UUID
OpenCode	~/.local/share/opencode/storage/session/[hash]/ses_*.json	JSON files with session ID in filename	ses_[a-zA-Z0-9]{10,}

Proposed Implementation

New file: session-detector.js

Server-side module with per-agent scanner functions:

• scanClaude() — reads ~/.claude/history.jsonl, groups by sessionId, filters by recency (default 48h)
• scanGemini() — lists session JSON files, checks mtime + lastUpdated
• scanCodex() — lists JSONL files recursively, reads first line for metadata
• scanOpenCode() — lists session JSON files, extracts session ID from filename
• scan() — combines all scanners, excludes already-known Termix sessions, sorts by most recent
• Dismissed sessions persisted to ~/.termix/dismissed-detected.json

All scanners wrapped in try/catch so missing directories (agent not installed) are silently skipped.

Server integration

• Scan is not run automatically on startup
• Scan only runs when triggered by the user via a WebSocket message (sessions.scan)
• New WebSocket message types: sessions.detected, session.resumeDetected, session.dismissDetected, sessions.scan
• Server checks which agents are installed (directories exist) and reports available agents to the frontend on connection via sessions.agentsAvailable

Frontend UI — Opt-in prompt

• On connection, if no active sessions and no resumable sessions exist, and the user hasn't previously dismissed the prompt, show a banner/modal:
  • Lists which agents were found installed on the system
  • "Import Sessions" button → triggers sessions.scan, shows results
  • "No thanks" button → dismisses, saves preference to config
• Preference stored in config as detectExternalSessions: 'ask' | 'always' | 'never'
  • 'ask' (default) — show prompt when dashboard is empty
  • 'always' — scan automatically on startup (user opted in)
  • 'never' — never prompt or scan

Frontend UI — Detected sessions list

• After user opts in and scan completes, a "Detected Sessions" section appears in the sidebar
• Each row shows: agent icon (faded), agent name, project path, time ago, first message preview
• "Resume" button on hover — spawns a new PTY with the agent's resume command
• Dismiss (X) button on hover — hides the session permanently
• Rescan button in the section header
• Integrates with existing search/filter system

Settings integration

• New toggle in Settings → General: "Import external agent sessions"
  • Options: Ask when empty / Always on startup / Never
• Manual "Scan now" button in settings

Files to modify

• sessions.js — add detected state, export spawnSession
• server.js — detect which agent directories exist on startup, send availability info
• handlers.js — add WebSocket handlers for scan/resume/dismiss
• config.js — add detectExternalSessions preference
• public/js/state.js — add detected: [] and agentsAvailable: [] to state
• public/js/terminals.js — add buildDetectedRow(), integrate into regroupSessions() and applyFilter()
• public/js/app.js — add opt-in prompt, message handlers, click delegation
• public/js/settings.js — add import preference toggle

[rustykuntz]

Done