Skip to main content

tmux-llm-rescue

A command-line tool for recovering Claude Code, Codex and Kimi sessions after a tmux crash.

한국어 · Python 3.9+ · macOS and Linux

license

Install · Quick start · Reference · Limits

A recorded Claude Code pane in the numbered scan and restore preview

Install

pipx install tmux-llm-rescue
uv tool install tmux-llm-rescue

Choose either command. You need tmux and the assistant CLI whose sessions you want to recover. The recovery tool reads local files and uses the CLI you already have. It needs no account, API key or network connection of its own.

Quick start

Run this inside a tmux server while your assistant panes are open. The example server has two panes.

$ tmux-llm-rescue record
Recorded 2 pane(s).

To record periodically, append this line to ~/.tmux.conf. It uses your existing status interval while a tmux client is attached. Use the full path to your executable if the tmux server's PATH differs from your shell's.

set -ag status-right '#(TMUX=#{q:socket_path},0,0 tmux-llm-rescue record >/dev/null)'

After a crash, run these commands for the same socket. Drop -L work for the default socket.

tmux-llm-rescue -L work
tmux-llm-rescue restore -L work --dry-run
tmux-llm-rescue restore -L work --only 1,2

The first command prints numbered sessions and resume commands you can paste. The second previews the new sessions, windows, working directories and commands. The third launches just rows 1 and 2. Running sessions and ambiguous matches are skipped.

Reference

Command Behavior
tmux-llm-rescue [--json] Scan local session stores. JSON includes row numbers, resume commands and recorded pane matches.
tmux-llm-rescue record Save the selected server's session, window, pane, working directory, command name and time.
tmux-llm-rescue restore [--dry-run] [--only N,M] Create new windows for matched sessions. Multiple recovered panes from a window share a new tiled window.
-L NAME Select a named socket for any command. Inside tmux, the caller's socket is used by default. Outside tmux, the default socket is used.
--since TIME, --lookback 12h Set a crash time (ISO time or an offset such as 30m) and the activity window for scan or restore.

Snapshots are kept per socket under ~/.local/state/tmux-llm-rescue/, or under $XDG_STATE_HOME/tmux-llm-rescue/. When a server has restarted, recovery selects the last recording from before its startup. Without a snapshot, scan still lists local candidates.

The built-in homes are:

CLI Session root Resume command
Claude Code ~/.claude (CLAUDE_CONFIG_DIR) claude --resume {sid}
Codex ~/.codex (CODEX_HOME) codex resume {sid}
Kimi CLI ~/.kimi (KIMI_SHARE_DIR) kimi --resume {sid}
Kimi Code CLI ~/.kimi-code kimi-code --session {sid}

To replace the defaults, create ~/.config/tmux-llm-rescue/config.toml or $XDG_CONFIG_HOME/tmux-llm-rescue/config.toml. List every home to scan. Use one [[homes]] block per home and quote each field. Put {sid} wherever the CLI expects its ID. The tool passes the template as arguments and accepts an executable or an env prefix.

[[homes]]
family = "codex"
root = "~/.codex-work"
resume_command = 'env CODEX_HOME=/home/you/.codex-work codex resume {sid}'

Limits

  • Restore uses the recorded ID when present. Otherwise it requires one matching CLI and working directory on each side. Older, missing or ambiguous session data can leave a pane unmatched.
  • An explicit session ID in a process's command line marks it as running. On the target server, a live assistant pane with an unknown ID blocks restore of a matching CLI and directory. A fresh CLI on another server may have no ID visible to this tool.
  • Restore creates new windows or sessions. It recovers the recorded names and directories. It skips ordinary shell panes and uses a fresh tiled arrangement for multiple recovered panes in a window.
  • The Kimi CLI's hashed layout needs a working-directory entry in kimi.json or a matching recorded pane. The scanners cover local storage. Antigravity and remote conversation stores are outside the package.
  • The recorder needs a running source server. The status-line job runs while a client displays the status line. For detached servers, invoke record -L NAME from your scheduler.

tmux-resurrect covers exact pane layouts and general programs. tmux-continuum adds periodic saving and automatic startup. tmuxinator starts repeatable workspaces from a configuration file. This tool reads assistant session IDs from local CLI stores and offers an explicit restore command.

Contributions are welcome. Run python -m unittest discover -s tests -v. Contributing

MIT license. License

This project is independent of Anthropic, OpenAI and Moonshot AI.

Metadata

Release files for tmux-llm-rescue 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tmux-llm-rescue 0.1.1
File Size Uploaded Provenance Actions
tmux_llm_rescue-0.1.1.tar.gz 26.3 kB Without provenance Details for tmux_llm_rescue-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tmux-llm-rescue 0.1.1
File Interpreter ABI Platform Actions
tmux_llm_rescue-0.1.1-py3-none-any.whl Python 3 none any Details for tmux_llm_rescue-0.1.1-py3-none-any.whl

Total release size: 51.3 kB

Release files / tmux_llm_rescue-0.1.1.tar.gz

Download URL tmux_llm_rescue-0.1.1.tar.gz
Size 26.3 kB
Tags Source
SHA-256 checksum
How to use checksums
730acc62132ce32a4de905a667918a146ee0b046e2e0c962033b2cb0c70c4aa7
BLAKE2b-256 checksum
How to use checksums
18781a72888713cc08bb41d92bff456fc7d6c1120ac9222b147f66589f582953
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / tmux_llm_rescue-0.1.1-py3-none-any.whl

Download URL tmux_llm_rescue-0.1.1-py3-none-any.whl
Size 25.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
585e14ea135de2fa51049069f061d7dc203352a5be7da4186451c07fb01ccc5a
BLAKE2b-256 checksum
How to use checksums
01ed8e2054b51989d0c333f74dfcbe7c15ddcd2db3d12f3a0d289bb94be8e605
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for tmux-llm-rescue 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page