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
Install · Quick start · Reference · Limits
Install
From the source checkout:
pipx install .
uv tool install .
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.jsonor 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 NAMEfrom 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tmux_llm_rescue-0.1.0.tar.gz | 26.3 kB | Without provenance | Details for tmux_llm_rescue-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tmux_llm_rescue-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for tmux_llm_rescue-0.1.0-py3-none-any.whl |
Total release size: 51.4 kB
Release files / tmux_llm_rescue-0.1.0.tar.gz
| Download URL | tmux_llm_rescue-0.1.0.tar.gz |
|---|---|
| Size | 26.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9735451f0d9eaa70228af7e176bf9002bd6462b074a17939c2c8f227b9ce9fc
|
|
BLAKE2b-256 checksum How to use checksums |
dce10ce512c54fcfe53c8ee61dd617712249d71323b78c71bfe911747eea612f
|
| 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.0-py3-none-any.whl
| Download URL | tmux_llm_rescue-0.1.0-py3-none-any.whl |
|---|---|
| Size | 25.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
54014ce79a15a27f8a571dccc3df6da23534999b33a4cd0b370e7d4abfa5d1f5
|
|
BLAKE2b-256 checksum How to use checksums |
257166ced58849d3cfb233da92e462e6bca7ff107b8e34e4cb5f492db30d78f4
|
| 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.0
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.