fireworks-terminal-sessions

---
name: fireworks-terminal-sessions
description: "Capture exact named tmux-to-Codex/Claude Code/Kimi Code/Pi session mappings and safely restore missing windows using native resume IDs."
---

# Fireworks Terminal Sessions

Use when the user asks to preserve, inspect, or recover AI CLI conversations in named tmux sessions. The tool operates locally and does not need a model API key.

## Install

If the CLI is absent, clone this repository to a user-chosen local directory and run `./install.sh`. Run `~/.local/bin/terminal-sessions doctor`; ensure the installed directory is on `PATH` before relying on the short command. `./install.sh --force` preserves a backup when upgrading a different existing binary. Never replace a user file without the installer backup.

## Find the tmux server

Inspect `tmux list-sessions` for the default server and known named servers with `tmux -L NAME list-sessions`. A tmux `-L` server is distinct from a session/window name. Ask for the server name only when it cannot be determined from the current shell, task context, or a narrow read-only check. Keep `--server NAME` consistent across capture, plan, bind, restore, and auto-install.

## Capture and restore

1. Run `terminal-sessions doctor` and `terminal-sessions capture --server NAME` while the relevant CLI sessions are still running. Report unresolved mappings; never invent an ID from the window name or a “recent session” list.
2. For automatic macOS capture, opt in with `terminal-sessions auto-install --server NAME`, then check `terminal-sessions auto-status --server NAME`. It uses the already-running tmux server. Linux capture scheduling is user-managed.
3. Before recovery, run `terminal-sessions server-health --server NAME`. The write probe must report `ok`. A `context-stale` result means a fossil server (stale security context): restored windows would still fail with EPERM, so recover with `terminal-sessions restore --fresh-server --server NAME` instead, adding `--force` only after reviewing the listed active sessions.
4. Then run `terminal-sessions plan --server NAME`; its header repeats the server start time, PID, and probe result. Show the exact window, tool, ID, and `ready` / `already-running` / `blocked` status. If blocked, investigate the specific cause.
5. Run `terminal-sessions restore --server NAME` only for a coherent verified plan. Use `--only WINDOW` to recover a subset. Read the CLI result back; a launched but unverified process is not a confirmed native conversation.
6. Attach from outside tmux with `tmux -L NAME attach -t WINDOW`; when already in tmux, use `TMUX= tmux -L NAME attach -t WINDOW` or another terminal. Do not submit a prompt to the restored CLI unless the user has separately asked for work there.

For an unresolved window, verify an exact ID in that provider's own session list or transcript, then run `terminal-sessions bind --server NAME --name WINDOW --tool codex|claude|kimi|pi --session-id ID --cwd DIR` and repeat `plan`. Pi rewrites its command line and holds no session file open, so capture matches at most one session file per working directory; a directory with several Pi conversations must be bound by exact ID. A manually supplied ID is a binding request, not proof that the native record exists.

## Common scenarios

- Morning check: `terminal-sessions status` lists every journal-known server with snapshot age, per-window live/missing state, auto-capture job state, and a server health line. Use `--server NAME` for one server.
- Incident recovery: confirm `server-health`, review `plan`, then `restore`. A blocked plan is a finding, not a failure to force past. For Wave Terminal users, `terminal-sessions reopen --server NAME` is the single command after `server-health`: it restores missing sessions and recreates Wave windows via `wsh`, skipping already-open ones. Plain `restore` is tmux-level recovery; use `reopen --print` for other terminal emulators.
- Fossil server recovery: after a macOS privacy-permission event, an old tmux server can keep running with a stale security context. `server-health` reports `context-stale (probe write denied)`; recover with `restore --fresh-server` (add `--force` only after reviewing the sessions it would kill).
- Routine cleanup: `terminal-sessions clean` dry-runs stale tmux sockets left by dead servers; rerun with `--apply` to remove them.

## Safety

- Do not kill, replace, or rename active tmux or native CLI sessions during routine recovery. `restore --fresh-server` kills the whole tmux server; it refuses while any mapped window is already running or other sessions exist unless `--force` is given after review.
- Do not use `resume --last`, a fuzzy picker, or a guessed ID as an automatic substitute for exact mapping.
- A blocked plan needs evidence or a corrected mapping. `forget` removes only the current mapping and retains journal history; use it only when the user intends to retire that window.
- The private journal contains IDs and local paths. Do not paste its full contents into public issues, logs, prompts, or repositories.
- See [how it works](docs/how-it-works.md) and [security](SECURITY.md) for trust boundaries and known verification limits.