copilot-session-manager (csm)

List, identify, and one-click restore your GitHub Copilot CLI chat sessions after a crash, reboot, or accidental close.

When the GitHub Copilot CLI closes unexpectedly, recovering your in-progress sessions means digging through ~/.copilot/session-state and resuming each one by hand. csm turns that into a single command.

$ csm restore --all
✔ Fix flaky auth test       — Opened in Windows Terminal tab.
✔ Refactor billing module   — Opened in Windows Terminal tab.
Restored 2/2 session(s).

Features

• Status at a glance — every session is classified as running, crashed (recoverable — a stale lock left by a crashed process), or idle (cleanly/accidentally closed).
• One-click restore — csm restore --all reopens every crashed and idle session in its own terminal tab/window, each resumed in its original working directory.
• Interactive picker — csm restore lets you multi-select which sessions to reopen (crashed and idle are pre-selected).
• Reopen the last N — csm last 10 quickly reopens your 10 most recent sessions, no picker.
• Never double-opens — sessions that are already running are skipped, so you never get a duplicate.
• Load a single session — by id, id prefix, or name.
• Live watch — csm watch shows a continuously-updating view of running & crashed sessions.
• Configurable retention — hide/skip sessions older than N days (default 7, by last activity).
• Cross-platform — Windows (Windows Terminal / console), macOS (Terminal / iTerm), Linux (gnome-terminal / konsole / xterm). Falls back to printing a copy-paste command when no terminal is available.
• No daemon, crash-proof — state is read directly from the filesystem on every run.
• Privacy-first — reads only your local ~/.copilot files; no telemetry, no network.

Install

npm install -g copilot-session-manager

Requires Node.js >= 18 and the GitHub Copilot CLI (copilot) on your PATH.

Usage

csm list                      # all sessions within the retention window
csm list --crashed            # only crashed (recoverable) sessions
csm list --running            # only live sessions
csm list --repo myrepo        # filter by repository
csm list --search auth        # search name/summary/cwd/branch/id
csm list --all                # ignore the retention window
csm list --days 14            # widen to the last 14 days
csm list --json               # machine-readable output
csm list --group-by-repo      # group sessions by repository

csm restore                   # interactive picker (crashed + idle pre-selected)
csm restore --all             # reopen all crashed + idle sessions, one terminal each
csm restore --all --include-running   # also reopen running sessions
csm restore --here            # resume in the current terminal instead of new ones

csm last 10                   # reopen the 10 most recent sessions (skips running), no picker
csm last 5 --here             # reopen the last 5 in the current terminal

# Sessions are listed in a numbered, aligned table. Titles taken from an unnamed
# session's first message are flattened to a single line and truncated for readability.

csm load <id|prefix|name>     # open one session in a new terminal
csm load 0cb916d              # by 7+ char id prefix
csm load "my feature" --here  # resume by name in the current terminal

csm watch                     # live view of running & crashed sessions
csm watch --interval 5        # refresh every 5 seconds

csm clean                     # remove stale lock files from crashed sessions
csm clean --older-than 30           # dry-run: list idle sessions older than 30 days
csm clean --older-than 30 --apply   # delete those session folders (asks to confirm)

csm doctor                    # check environment (copilot, session-state, terminal)
csm open-folder <id>          # reveal a session's folder in your file manager

Configuration

Settings live in ~/.copilot/csm-config.json.

csm config list
csm config get retentionDays
csm config set retentionDays 14
csm config set terminal wt
csm config reset

| Key | Default | Description | | --- | --- | --- | | retentionDays | 7 | Hide sessions whose last activity is older than this many days. | | terminal | auto | Terminal launcher: auto, wt, iterm, terminal-app, gnome-terminal, konsole, xterm, none. | | terminalCommand | — | Custom launcher template. Use {cwd} and {cmd} placeholders. | | restoreAllIncludesRunning | false | Whether restore --all also reopens running sessions. | | maxRestoreTabs | 10 | Confirm before opening more than this many terminals at once. | | pruneStaleLocksOnRun | true | Reserved for auto-pruning stale locks. | | defaultSort | updated_desc | Default list order: updated_desc, created_desc, repo. | | copilotCommand | copilot | Command/path used to launch the Copilot CLI. |

Global flags

• --home <dir> — override the Copilot home directory (default ~/.copilot; also honors COPILOT_HOME).
• --no-color — disable colored output.

How it works

The Copilot CLI persists each session under ~/.copilot/session-state/<id>/:

• workspace.yaml holds the session's cwd, repository, branch, name, and timestamps.
• An inuse.<pid>.lock file marks a session as in use. If that PID is no longer a live Copilot process (e.g. after a crash or reboot), the lock is stale — that's a recoverable, "crashed" session.

csm reconciles this state on every run, so there is no background process to keep alive and nothing to lose if csm itself is interrupted. Restoring a session simply runs copilot --resume=<id> from the session's original working directory.

Development

npm install
npm run build      # bundle to dist/ with tsup
npm test           # node:test suite
npm run lint       # eslint
npm run typecheck  # tsc --noEmit

Publishing

This package publishes to the public npm registry as the unscoped name copilot-session-manager.

npm login                 # authenticate (interactive: browser/OTP)
npm whoami                # confirm you are logged in
npm publish --dry-run     # validate the tarball contents
npm publish               # publish (runs the build via prepublishOnly)

prepublishOnly rebuilds dist/ automatically, and the files allowlist ensures only dist/, README.md, and LICENSE ship in the tarball.

Update the repository, homepage, bugs, and author fields in package.json to point at the actual hosting location before the first publish.

License

MIT