ResumerAgent
Menu

Docs

Install

Install ResumerAgent with Node 18 or newer, start the local dashboard, and set up a desktop shortcut.

ResumerAgent’s source code isn’t public yet. These pages describe how it works once it is.

Requirements

  • Node.js 18 or newer.
  • Claude Code installed, with at least one session on disk.
  • Windows, macOS or Linux. See Platform support for what has been tested where.

ResumerAgent has zero runtime dependencies, so there is nothing else to install.

Quickstart

git clone https://github.com/Arman-no/ResumerAgent.git
cd ResumerAgent
npm install             # no-op: zero runtime dependencies, just confirms Node works
cp .env.example .env    # optional: only needed if your setup isn't a default native install
npm start

npm start runs a server on http://127.0.0.1:4317 and opens the dashboard in your browser. Press Ctrl+C to stop it. Nothing runs while you aren’t using it.

pnpm works for every command above if you prefer it.

If your Claude Code setup isn’t a default native install (a custom config directory, Docker, a different port), see Configuration.

Desktop shortcut

Point the shortcut at npm run launch, not npm start. Use npm here even if you use pnpm everywhere else.

launch stops any earlier ResumerAgent instance still bound to the port, then starts a fresh one. Plain start keeps an old instance running without telling you if one is already there.

Platform support

Resume and Attach open a terminal window the way each OS supports:

OS Terminal
Windows cmd.exe through start
macOS Terminal.app through osascript
Linux The first installed of x-terminal-emulator, gnome-terminal, konsole, xfce4-terminal, alacritty, kitty, xterm

Want a different terminal (iTerm, WezTerm, Warp, tmux), or none of the Linux emulators above is installed? Set TERMINAL_COMMAND. See Configuration.

Every session row also has a copy button that puts the resume command on your clipboard. It works everywhere, including over SSH, inside tmux, and in terminals ResumerAgent can’t drive.

The Windows path has run on real hardware. The macOS and Linux paths are covered by unit tests and a CI matrix (Ubuntu, macOS and Windows runners on Node 18 and 22), but haven’t been run on real machines yet.

Troubleshooting

The product repo’s AGENT_SETUP.md has a symptom, cause and fix table for problems hit on real machines, including:

  • AppLocker or corepack blocking pnpm on locked-down Windows machines.
  • An empty or wrong session list because SESSIONS_ROOT resolved to the wrong directory.
  • EADDRINUSE when running npm start.
  • Resume opening nothing on macOS or Linux.