2026-02-18 01:26:19 +09:00
|
|
|
# src/features/tmux-subagent/ — Tmux Pane Management
|
|
|
|
|
|
2026-04-05 14:04:42 +09:00
|
|
|
**Generated:** 2026-04-05
|
2026-02-18 01:26:19 +09:00
|
|
|
|
|
|
|
|
## OVERVIEW
|
|
|
|
|
|
|
|
|
|
28 files. State-first tmux integration managing panes for background agent sessions. Handles split decisions, grid planning, polling, and lifecycle events.
|
|
|
|
|
|
|
|
|
|
## CORE ARCHITECTURE
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
TmuxSessionManager (manager.ts)
|
|
|
|
|
├─→ DecisionEngine: Should we spawn/close panes?
|
|
|
|
|
├─→ ActionExecutor: Execute spawn/close/replace actions
|
|
|
|
|
├─→ PollingManager: Monitor pane health
|
|
|
|
|
└─→ EventHandlers: React to session create/delete
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## KEY FILES
|
|
|
|
|
|
|
|
|
|
| File | Purpose |
|
|
|
|
|
|------|---------|
|
|
|
|
|
| `manager.ts` | `TmuxSessionManager` — main class, session tracking, event routing |
|
|
|
|
|
| `decision-engine.ts` | Evaluate window state → produce `SpawnDecision` with actions |
|
|
|
|
|
| `action-executor.ts` | Execute `PaneAction[]` (close, spawn, replace) |
|
|
|
|
|
| `grid-planning.ts` | Calculate pane layout given window dimensions |
|
|
|
|
|
| `spawn-action-decider.ts` | Decide spawn vs replace vs skip |
|
|
|
|
|
| `spawn-target-finder.ts` | Find best pane to split or replace |
|
|
|
|
|
| `polling-manager.ts` | Health polling for tracked sessions |
|
|
|
|
|
| `types.ts` | `TrackedSession`, `WindowState`, `PaneAction`, `SpawnDecision` |
|
|
|
|
|
|
|
|
|
|
## PANE LIFECYCLE
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
session.created → spawn-action-decider → grid-planning → action-executor → track session
|
|
|
|
|
session.deleted → cleanup tracked session → close pane if empty
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## LAYOUT CONSTRAINTS
|
|
|
|
|
|
|
|
|
|
- `MIN_PANE_WIDTH`: 52 chars
|
|
|
|
|
- `MIN_PANE_HEIGHT`: 11 lines
|
|
|
|
|
- Main pane preserved (never split below minimum)
|
|
|
|
|
- Agent panes split from remaining space
|
|
|
|
|
|
|
|
|
|
## EVENT HANDLERS
|
|
|
|
|
|
|
|
|
|
| File | Event |
|
|
|
|
|
|------|-------|
|
|
|
|
|
| `session-created-handler.ts` | New background session → spawn pane |
|
|
|
|
|
| `session-deleted-handler.ts` | Session ended → close pane |
|
|
|
|
|
| `session-created-event.ts` | Event type definition |
|
