# agent-session-recovery

**A tool-independent recovery layer for AI-agent workspaces.** It reads every live
agent's own transcript to recover the exact *resume command* — so a session survives a
reboot, a crash, or the window you closed by mistake.

---

## Why this exists

Real situation that created it (2026-07): a workstation running **5 Claude Code +
2 Codex agents** across many terminals, plus dev servers. The machine needed a reboot,
and rebooting felt dangerous — *"I'll lose all my agent progress."*

That fear is the actual problem. It defers maintenance the machine genuinely needs, and
it makes every accidental close — a stray keystroke, the wrong window — cost far more
than it should.

**The key insight this project is built on:** your agent *progress isn't in the
terminals*. Claude Code and Codex each persist their **entire conversation to disk,
live**, independent of any terminal or multiplexer:

- Claude Code → `~/.claude/projects/<slug>/<sessionId>.jsonl`
- Codex → `~/.codex/sessions/…`

So nothing that kills a terminal ever destroys the conversation — it only scatters the
*workspace* (which agent was open where, plus dev servers). The missing piece is a
**reliable, tool-independent way to find a session again and resume it**, one that keeps
working when your multiplexer is down. That is this project.

## What it does

```
sessions.ps1   → every session on the machine, labelled with the first thing you said
                 in it, graded by how alive it looks. Reopen any one of them.
                 (no snapshot, no reboot, no manifest — the accidental-close case)
watch.ps1      → keeps a snapshot current, and tells you when it has gone stale
prepare-reboot → about to reboot on purpose? capture, check the record is complete,
                 and say plainly what the reboot will and will not cost
snapshot.ps1   → records what is open now: sessions, the exact live-session count,
                 the terminal pane layout, dev servers → JSON + restore.md
recover.ps1    → too late for a snapshot? reconstructs the same manifest AFTER a
                 reboot, from the transcripts alone
restore.ps1    → reads a manifest, reopens a terminal per agent in the right
                 directory running its exact resume command — then verifies it
```

Because the manifest is derived from the agents' *own* session files, it is correct
regardless of whether a multiplexer is healthy.

## What it can and cannot know

Recovery is only as good as its evidence, so the tools say which kind they have:

| | Evidence | Verdict |
|---|---|---|
| Codex session | holds its rollout open — an exclusive open fails while it lives | **fact** |
| Claude session, writing now | just appended to its transcript | **fact** |
| Claude session, idle | one `claude.exe` and one named pipe exist per session, so the *total* is exact — but neither says which | **ranked inference**, marked `live?` |
| Anything, after the machine is down | the count died with the machine | **unknowable** — an idle session and a closed one are identical on disk |

That last row is the whole reason `watch.ps1` exists. An idle agent writes nothing at all
— there is no heartbeat, and it was measured, not assumed ([RESEARCH §3.2](docs/RESEARCH.md))
— so **recovery quality is decided before the loss, not after**. A snapshot costs about a
second.

A snapshot is not omniscience either: it is ground truth for the moment it was taken, and
says nothing about a session opened after it. The interval bounds that error; it does not
remove it.

## Snapshots are private

`snapshots/` holds absolute working directories, session ids, git branches, and the first
thing you typed in each conversation. It is git-ignored here, and that is not enough on its
own — **do not commit it, paste it into an issue, or attach `restore.md` to a bug report.**
Captured dev-server command lines are redacted for the obvious secret shapes
(`--api-key=`, `TOKEN=`, `user:password@host`), which is a seatbelt, not a guarantee.

## Quick start

**"I just closed something I wanted back."**

```powershell
pwsh -File .\scripts\sessions.ps1            # everything, newest first, with labels
pwsh -File .\scripts\sessions.ps1 -Closed    # just the recently-closed candidates
pwsh -File .\scripts\sessions.ps1 -Reopen 3  # reopen row 3 (-DryRun to see the command)
```

**"Don't let a reboot cost me anything."**

```powershell
pwsh -File .\scripts\watch.ps1 -Install -FromManifest   # every 5 min (-DryRun to preview)
pwsh -File .\scripts\watch.ps1 -Status                  # ...and is that record still fresh?

# ...reboot...
pwsh -File .\scripts\restore.ps1 -DryRun     # preview the plan
pwsh -File .\scripts\restore.ps1             # reopen, then verify each one came back
```

**"I need to reboot and I don't want to lose anything."**

```powershell
pwsh -File .\scripts\prepare-reboot.ps1      # capture, then say what the reboot costs
```

It captures, checks the record is *complete* against the exact live-session count, lists
uncommitted work in the directories those sessions are in, names what will simply die
(dev servers, in-flight tool calls, scrollback), and prints what to run afterwards. It
never reboots anything.

**"It already rebooted and I captured nothing."**

```powershell
pwsh -File .\scripts\recover.ps1             # -DryRun to preview, -IncludeMaybeOpen to widen
pwsh -File .\scripts\restore.ps1 -DryRun
```

Restoring only part of a sheet: `restore.ps1 -Only checkout,3,cccccccc` — a row number, a
session-id prefix, or any substring of the working directory.

Running it from an **elevated** shell is fine: the sessions are opened through Explorer at
standard-user privilege, because Codex refuses to start elevated. `-AllowElevated` keeps
the elevation. A terminal whose window has frozen is treated as absent, so the restore
goes to another one instead of waiting on it.

Running several agent accounts through a launcher? Add `-FromManifest`. Without it every
routed account looks empty, because its transcripts do not live in `~/.claude` at all.

## Status

Phases 1, 1.5, 2 and most of 3 are in: list and reopen any session, keep a live record so
a reboot costs nothing, reconstruct one afterwards when no record exists, and verify that a
restore actually took. Design and the full phased plan live in [`docs/`](docs/):

- [`docs/RESEARCH.md`](docs/RESEARCH.md) — how agent persistence & resume actually work, and what is recoverable.
- [`docs/DESIGN.md`](docs/DESIGN.md) — architecture, data model, restore strategies, safety.
- [`docs/ROADMAP.md`](docs/ROADMAP.md) — phases from seed → automatic, verified recovery.

## Non-goals

- Not a terminal multiplexer, and not a replacement for one — it *complements* whatever
  you use, and stands in as the safety net when that layer is down or stale.
- Not a memory/state serializer for the agents — it relies on each agent's own
  first-class `--resume`. It restores *which conversations to reopen*, not their bytes.

## License

MIT — see [`LICENSE`](LICENSE).