AGENTS.md

1# tmux-core — Tmux Primitives (Core)
2 
3**Generated:** 2026-06-16
4 
5## OVERVIEW
6 
7Harness-neutral tmux primitives consumed by the OpenCode adapter (`omo-opencode`), team-mode visualization (`team-core`), OpenClaw injection (`openclaw-core`), and the `interactive_bash` tool. Every function is dependency-injected so adapters supply `getTmuxPath()`, `log`, and server-health checks. Package: `@oh-my-opencode/tmux-core`.
8 
9## CATEGORY MAP
10 
11| Area | Key Files | Key Exports |
12|------|-----------|-------------|
13| **Runner** | `src/runner.ts` | `runTmuxCommand()`, `TmuxCommandResult` — retry, timeout, cmux compat |
14| **Types / Config** | `src/types.ts`, `src/constants.ts` | `TmuxConfig`, `TmuxLayout`, `TmuxIsolation`, `SpawnPaneResult`, polling constants |
15| **Pane Lifecycle** | `src/tmux-utils/pane-spawn.ts`, `pane-close.ts`, `pane-replace.ts`, `pane-activate.ts`, `pane-command.ts` | `spawnTmuxPane()`, `closeTmuxPane()`, `replaceTmuxPane()`, `activateTmuxPane()`, `buildTmuxAttachCommand()`, `buildTmuxPlaceholderCommand()` |
16| **Session Lifecycle** | `src/tmux-utils/session-spawn.ts`, `session-kill.ts`, `stale-session-sweep.ts` | `spawnTmuxSession()`, `killTmuxSessionIfExists()`, `sweepStaleOmoAgentSessions()` |
17| **Window / Layout** | `src/tmux-utils/window-spawn.ts`, `layout.ts`, `pane-dimensions.ts` | `spawnTmuxWindow()`, `applyLayout()`, `enforceMainPaneWidth()`, `getPaneDimensions()` |
18| **Environment / Health** | `src/tmux-utils/environment.ts`, `server-health.ts`, `src/cmux-detect.ts` | `isInsideTmux()`, `getCurrentPaneId()`, `isServerRunning()`, `isCmuxCompatEnvironment()` |
19 
20## FLOW
21 
22```
23spawnTmuxPane / spawnTmuxSession / spawnTmuxWindow
24  ├─ guard: config.enabled
25  ├─ guard: isInsideTmux()
26  ├─ guard: isServerRunning(serverUrl)
27  ├─ resolve tmux binary (or cmux compat shim)
28  └─ tmux split-window / new-session / new-window + placeholder command
29```
30 
31## NOTES
32 
33- **Cmux compatibility:** `cmux-detect.ts` redirects tmux commands to `cmux __tmux-compat` when `CMUX_SOCKET_PATH` or `cmuxterm` is detected.
34- **Isolation levels:** `TmuxIsolation` (`inline`, `window`, `session`) controls whether subagent panes split inline, spawn a named window (`omo-agents`), or an isolated session (`omo-agents-<pid>`).
35- **Adapter shim pattern:** `omo-opencode/src/shared/tmux/` re-exports `runTmuxCommand` and wires `getTmuxPath` from `interactive-bash/tmux-path-resolver` into DI deps (`adapter-deps.ts`). `team-core` consumes the same primitives directly for team-mode tmux layouts.
36- **Stale session sweep:** `stale-session-sweep.ts` matches `omo-agents-<pid>` sessions, skips the current PID, and kills sessions whose owner process is dead.
37 
38Parent: [packages/AGENTS.md](../AGENTS.md)
39