laurigates/kitty-session-persistence

Kitty Session Persistence (macOS)

When to Use This Skill

| Use this skill when... | Use something else when... | |------------------------|----------------------------| | Terminal sessions need to survive WindowServer hangs and force-reboots | The user's terminal is iTerm2 / Terminal.app / Ghostty / Wezterm — kitty-specific | | Configuring kitty's listen_on socket and a snapshot LaunchAgent | Cross-platform terminal config — this is macOS LaunchAgents | | Restoring a previous session after a crash | One-off "open these tabs" — kitty @ launch directly is enough | | Auditing whether snapshot capture is still running | General system diagnostics — see macos-incident-postmortem |

Platform Guard

This skill is macOS-only. All commands assume Darwin and launchctl-managed LaunchAgents. Refuse to act if uname -s is not Darwin.

test "$(uname -s)" = "Darwin" || { echo "macos-plugin: not Darwin, refusing"; exit 1; }

Core Expertise

Kitty exposes a remote control protocol via a Unix socket. With listen_on configured, kitten @ ls returns a JSON description of every OS window, tab, and window inside kitty — enough to reconstruct the layout from scratch.

The pattern this skill installs:

1. Always-listen socket — listen_on unix:/tmp/kitty-$USER in kitty.conf so the snapshot script can always reach the running instance.
2. Snapshot script — captures kitten @ ls output to a timestamped JSON file under ~/.local/state/kitty-sessions/, with a latest.json symlink.
3. LaunchAgent — runs the snapshot script every 5 minutes (default) so the worst-case loss is one window of work.
4. Restore command — reads latest.json and re-launches tabs with the recorded cwd and command.

Architectural notes

• Kitty's remote control requires allow_remote_control yes in kitty.conf or --allow-remote-control yes at launch.
• The socket path must match between listen_on and the kitten @ --to flag the snapshot script uses.
• LaunchAgent StandardOutPath and StandardErrorPath are essential — failing snapshots are otherwise silent.
• Use RunAtLoad: false and rely on StartInterval so a kitty restart doesn't spawn a backlog of immediate snapshots.

Setup

1. Configure kitty

Add to ~/.config/kitty/kitty.conf:

allow_remote_control yes
listen_on unix:/tmp/kitty-{kitty_pid}

Using {kitty_pid} makes each kitty instance addressable on its own socket. For the persistent-socket pattern this skill needs, use the user-stable form instead:

allow_remote_control yes
listen_on unix:/tmp/kitty-USER

Replace USER with the actual username. The snapshot LaunchAgent points at this exact path.

Reload kitty after editing:

kitty @ --to unix:/tmp/kitty-USER load-config

2. Install the snapshot script

Create ~/.local/bin/kitty-snapshot (mode 0755):

#!/usr/bin/env bash
set -uo pipefail

[ "$(uname -s)" = "Darwin" ] || exit 0

SOCKET="unix:/tmp/kitty-${USER}"
STATE_DIR="${HOME}/.local/state/kitty-sessions"
mkdir -p "$STATE_DIR"

ts="$(date -u +%Y%m%dT%H%M%SZ)"
out="${STATE_DIR}/${ts}.json"

if ! kitten @ --to "$SOCKET" ls >"$out" 2>>"${STATE_DIR}/snapshot.err"; then
  rm -f "$out"
  exit 0   # kitty not running — silent success
fi

ln -sfn "$out" "${STATE_DIR}/latest.json"

# Keep ~7 days of 5-min snapshots = 2016 files; cap at 4032 (14 days)
ls -1t "$STATE_DIR"/*.json 2>/dev/null | tail -n +4033 | xargs -r rm -f

The exit 0 on kitten @ ls failure is intentional — the LaunchAgent fires every 5 minutes regardless of whether kitty is running.

3. Install the LaunchAgent

Write ~/Library/LaunchAgents/com.<reverse-dns>.kitty-snapshot.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.kitty-snapshot</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/USER/.local/bin/kitty-snapshot</string>
  </array>
  <key>StartInterval</key>
  <integer>300</integer>
  <key>RunAtLoad</key>
  <false/>
  <key>StandardOutPath</key>
  <string>/Users/USER/.local/state/kitty-sessions/launchd.out</string>
  <key>StandardErrorPath</key>
  <string>/Users/USER/.local/state/kitty-sessions/launchd.err</string>
</dict>
</plist>

Replace com.example with a stable reverse-DNS prefix and USER with the literal username (LaunchAgents do not expand $HOME).

Validate, load, and verify:

plutil -lint ~/Library/LaunchAgents/com.example.kitty-snapshot.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.example.kitty-snapshot.plist
launchctl print "gui/$(id -u)/com.example.kitty-snapshot" | grep -E 'state|last exit'

bootstrap replaces the deprecated launchctl load; on macOS 11+ prefer it.

4. Confirm capture is working

After ~5 minutes:

ls -lt ~/.local/state/kitty-sessions/*.json | head -3

There should be JSON files newer than the LaunchAgent install time. The newest file's content should match what kitty has open right now.

Restore

Read latest.json and re-launch each window/tab. A minimal restore script:

#!/usr/bin/env bash
set -euo pipefail

[ "$(uname -s)" = "Darwin" ] || exit 1

LATEST="${HOME}/.local/state/kitty-sessions/latest.json"
SOCKET="unix:/tmp/kitty-${USER}"

[ -L "$LATEST" ] || { echo "no snapshot found"; exit 1; }

jq -c '.[] | .tabs[] | .windows[] | {cwd, foreground_processes}' "$LATEST" |
while IFS= read -r win; do
  cwd=$(printf '%s' "$win" | jq -r '.cwd')
  cmd=$(printf '%s' "$win" | jq -r '.foreground_processes[0].cmdline | join(" ")')
  kitten @ --to "$SOCKET" launch --type=tab --cwd="$cwd" "$cmd"
done

The shape of kitten @ ls output is [{tabs:[{windows:[{cwd, foreground_processes:[{cmdline}]}]}]}]. Adjust the jq query if a future kitty release changes it.

Common Patterns

Audit recent snapshots

ls -1t ~/.local/state/kitty-sessions/*.json | head -10
jq '. | length, [.[].tabs | length] | add' ~/.local/state/kitty-sessions/latest.json
# → window count, tab count

Confirm LaunchAgent is healthy

launchctl print "gui/$(id -u)/com.example.kitty-snapshot" | \
  grep -E 'state|last exit|on demand'

state = running (briefly, every 5 minutes) and last exit code = 0 indicate health. Persistent non-zero exit means something is broken — check launchd.err.

Disable / unload temporarily

launchctl bootout "gui/$(id -u)/com.example.kitty-snapshot"

bootout is the modern equivalent of launchctl unload.

Snapshot interval tuning

| Interval | When to use | |----------|-------------| | 60s (StartInterval=60) | Heavy editing days — minimum loss-on-crash | | 300s (default) | Balanced — typical workflow | | 900s (15 min) | Stable, low-edit days — less noise in ls -lt |

Reload after editing the plist:

launchctl bootout "gui/$(id -u)/com.example.kitty-snapshot"
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.example.kitty-snapshot.plist

Agentic Optimizations

| Context | Command | |---------|---------| | Snapshot count last hour | find ~/.local/state/kitty-sessions -name '*.json' -newermt '1 hour ago' \| wc -l | | Most recent snapshot age | stat -f '%Sm %N' ~/.local/state/kitty-sessions/latest.json | | Validate a plist | plutil -lint ~/Library/LaunchAgents/com.example.kitty-snapshot.plist | | Last exit code | launchctl print "gui/$(id -u)/com.example.kitty-snapshot" \| awk '/last exit code/{print $NF}' | | Live socket reachable | kitten @ --to unix:/tmp/kitty-$USER ls \| jq '. \| length' |

Quick Reference

LaunchAgent commands (macOS 11+)

| Operation | Command | |-----------|---------| | Load (modern) | launchctl bootstrap "gui/$(id -u)" <plist> | | Unload (modern) | launchctl bootout "gui/$(id -u)/<label>" | | Inspect | launchctl print "gui/$(id -u)/<label>" | | Run now | launchctl kickstart -k "gui/$(id -u)/<label>" | | List user agents | launchctl print-disabled "gui/$(id -u)" |

Kitty remote control

| Operation | Command | |-----------|---------| | List sessions | kitten @ --to <socket> ls | | Launch tab | kitten @ --to <socket> launch --type=tab --cwd=<path> <cmd> | | Reload config | kitten @ --to <socket> load-config | | Send text | kitten @ --to <socket> send-text --match "title:foo" "ls\n" |

Snapshot file structure

~/.local/state/kitty-sessions/
├── 20260503T120000Z.json
├── 20260503T120500Z.json
├── ...
├── latest.json -> 20260503T143000Z.json
├── snapshot.err
├── launchd.out
└── launchd.err

Error Handling

| Symptom | Cause | Fix | |---------|-------|-----| | kitten @ ls fails with "remote control not allowed" | allow_remote_control no in kitty.conf | Set to yes, reload config | | LaunchAgent loads but last exit code = 78 | Script not executable | chmod +x ~/.local/bin/kitty-snapshot | | LaunchAgent loads but never fires | StartInterval missing or zero | Set to a positive integer (seconds) | | All snapshots empty [] | No kitty windows running, or wrong socket path | Check listen_on path matches --to | | bootstrap fails with "already loaded" | Old load form still active | launchctl bootout first, then bootstrap | | Restore opens windows with wrong shell | cmdline[0] is the shell, not the user command | Use cwd only and let the user re-run |