AGENTS.md

1# src/features/tmux-subagent/ — Tmux Pane Management
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7This module provides state-first tmux integration for background agent sessions. It handles split decisions, grid planning, polling, and lifecycle events. Reusable tmux command, layout, and pane primitives are extracted to [`packages/tmux-core/`](../../../../../packages/tmux-core); this directory is the OpenCode session adapter.
8 
9## CORE ARCHITECTURE
10 
11```
12TmuxSessionManager (manager.ts)
13  ├─→ DecisionEngine: Should we spawn/close panes?
14  ├─→ ActionExecutor: Execute spawn/close/replace actions
15  ├─→ PollingManager: Monitor pane health
16  └─→ EventHandlers: React to session create/delete
17```
18 
19All tmux command execution is centralized through the shared `runTmuxCommand` runner (via the local adapter shim). Do NOT add direct `Bun.spawn([tmux,...])` calls in this module. They will drift from the retry/timeout/terminal-error discipline.
20 
21## KEY FILES
22 
23| File | Purpose |
24|------|---------|
25| `manager.ts` | `TmuxSessionManager` — main class, session tracking, event routing |
26| `decision-engine.ts` | Evaluate window state → produce `SpawnDecision` with actions |
27| `action-executor.ts` | Execute `PaneAction[]` (close, spawn, replace) |
28| `grid-planning.ts` | Calculate pane layout given window dimensions |
29| `spawn-action-decider.ts` | Decide spawn vs replace vs skip |
30| `spawn-target-finder.ts` | Find best pane to split or replace |
31| `polling-manager.ts` | Health polling for tracked sessions |
32| `types.ts` | `TrackedSession`, `WindowState`, `PaneAction`, `SpawnDecision` |
33 
34## PANE LIFECYCLE
35 
36```
37session.created → spawn-action-decider → grid-planning → action-executor → track session
38session.deleted → cleanup tracked session → close pane if empty
39```
40 
41## LAYOUT CONSTRAINTS
42 
43- `MIN_PANE_WIDTH`: 52 chars
44- `MIN_PANE_HEIGHT`: 11 lines
45- Main pane preserved (never split below minimum)
46- Agent panes split from remaining space
47 
48## EVENT HANDLERS
49 
50| File | Event |
51|------|-------|
52| `session-created-handler.ts` | New background session → spawn pane |
53| `session-deleted-handler.ts` | Session ended → close pane |
54| `session-created-event.ts` | Event type definition |
55