2.9 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | |||
|---|---|---|---|---|---|---|---|---|---|
| 0036 | 2026-07-13 | Accepted |
|
|
0036 — tmux session convention for AI-run sessions: cc--
Context
Issue #28 chose tmux (not headless claude -p / Agent SDK) as the execution surface for issue-triggered wakeup (ADR-0035), because the human must be able to discover, inspect, and take over an AI-run session. The naming/lifecycle convention is useful beyond wakeup — any long-running or unattended AI session benefits — so it is recorded as its own ADR. No existing tmux naming habit to preserve (no tmux server was running at spike time).
Decision
(1) Naming: AI-run sessions are named cc-<project>-<purpose>[-<n>] — cc- prefix marks Claude-operated sessions, <project> is the index-row project name (ADR-0034), <purpose> is short kebab-case (wakeup sessions use issue<N>, e.g. cc-llf-schema-issue12), -<n> only disambiguates collisions. Human personal sessions never take the cc- prefix. (2) Creation: whoever needs the session creates it — the wakeup poller (ADR-0035) for issue wakeups, a human for anything else — via tmux new-session -d -s <name> -c <project-root> ... so the pane starts in the project. (3) Lifecycle: a session is killed after clean completion once its closing artifact exists (for wakeups: the triage/summary comment posted on the issue); it is kept alive on error or whenever hitl input is needed, so the evidence and the takeover point are the same pane. Discovery is tmux ls — the cc- prefix makes AI sessions self-listing; an os-backlog-adjacent listing command is an explicit non-goal for now. (4) Attach/takeover: attaching pauses nothing — the pane runs an interactive Claude Code session, so a human who attaches can simply type into it; there is no separate handover protocol.
Consequences
Easier: one glanceable namespace (tmux ls | grep ^cc-) for everything the AI is running on a machine; takeover is native tmux attach, no tooling. Harder: kill-on-clean-completion means a successful session leaves no scrollback — the issue comment is the record, so sessions must actually post it before exiting (the wakeup prompt makes this the final required step); session names carry no timestamp, so a stale kept-alive session must be triaged by attaching, not by name.
Alternatives rejected
- Headless execution (claude -p / Agent SDK) — rejected by the human for this stage: no inspection or takeover surface; may return later for pure afk-ready work once trust is established. 2) Timestamped session names (cc--20260713-...) — rejected: names become unreadable in tmux ls and collisions are rare enough for -. 3) Keep every completed session for audit — rejected: the durable record belongs on the issue/card (ADR-0033 spirit), and dead sessions accumulate into noise.