Resume a Session

specstory resume opens an interactive picker over every session SpecStory has captured for your current project — across all terminal agents at once. Pick one, choose which installed agent to continue it in, and go.

You don't need to remember which agent you used, which project you were in, or even which machine you were on. Resume handles four kinds of handoffs:

Same agent, same project — pick up right where you left off.
Different agent, same project — continue a Claude Code session in Codex, a Codex session in Droid, and so on.
Different project — resume a session that started in another repo.
Different machine — resume a session synced from another laptop via SpecStory Cloud.

Tip

resume and search share the same picker. The only difference is the entry point: resume opens on the current project's session list; search opens straight into cross-project full-text search. Everything below about browsing, filtering, and resuming applies to both.

Before you start

Install the SpecStory CLI and at least one terminal agent (Claude Code, Codex CLI, Droid CLI, Cursor CLI, or Gemini CLI). See the Terminal Coding Agents overview.
Run specstory resume from inside the project you want to resume into. That project's sessions are listed first; everything else is one tab away.
The first time you resume in a project, SpecStory builds a local index of your sessions (~/.specstory/sessions.db). This happens automatically and only once per project.

specstory resume

The picker at a glance

The picker is a keyboard-driven TUI. Sessions are listed newest-first, each row tagged with its agent (Claude, Codex, Droid, Cursor, Gemini). Cloud sessions from your other machines are marked with a cloud icon.

Key	Action
`↑` `↓` / `j` `k`	Move selection
`r`	Resume the highlighted session
`space`	Preview the session in a scrollable, rendered reader
`/`	Full-text search (scoped to the current project; global in the all-projects view)
`tab`	Toggle between the current project and the all-projects browser
`a`	Cycle the agent filter (all → each agent present)
`m`	Cycle the machine filter (all → local only → each remote machine)
`v`	Toggle dense / sparse row layout
`d`	Soft-delete the highlighted session (or project) — confirmed with `y`
`p`	Filter the project list by name (all-projects browser only)
`enter`	Confirm at the final target-agent step (inert in the lists)
`q` / `esc`	Quit (or step back out of a view)

Note

Resuming launches an agent, so it's bound to an explicit r keystroke. A stray enter can't accidentally start a session. The one place enter commits is the final target-agent confirmation.

Browse sessions

When you run specstory resume, you land on the current project's session list — every session SpecStory has captured for this repo, across every agent, newest first.

Press tab to switch to the all-projects browser. Projects are grouped by relative date (Today · Yesterday · Previous 7 days · Previous 30 days · Older) and each shows per-agent session counts. Press enter on a project to drill into its session list; esc or tab to go back.

If your current project has no sessions yet, the picker opens directly in the all-projects browser so you can pick from elsewhere.

Tip

Use a to filter by agent and v to switch between dense (more rows, less detail) and sparse (more detail, fewer rows) layouts. Your layout choice is remembered across runs.

Search sessions

Press / to search. Search is full-text and runs instantly as you type.

In a project session list, / searches within that project.
In the all-projects browser, / searches across all your projects at once — a flat results list with the project shown per row.

Each result shows a highlighted snippet of the matched text so you can see why it matched. Press space to preview a hit, or r to resume it directly from the results.

You can also start in search mode directly:

specstory search

This opens the same picker, focused on the global search input.

Choose a target agent

After you press r on a session (if you didn't already pass a target on the command line), the picker asks which agent to resume into. Your last-resumed agent is the default; otherwise the session's original agent is.

To skip this step and resume straight into a specific agent, pass it as an argument:

specstory resume codex      # resume into Codex CLI
specstory resume claude     # resume into Claude Code
specstory resume droid      # resume into Droid CLI
specstory resume cursor     # resume into Cursor CLI
specstory resume gemini     # resume into Gemini CLI

The agent must be installed and on your PATH, or resume will tell you so.

Use case: resume in the same agent

The simplest case — you stopped a session and want to continue it.

specstory resume

Find the session in the current-project list (use / to search within the project).
Press r.
Pick the same agent at the target step (it's the default).
The agent launches against its existing on-disk session and picks up exactly where you left off.

SpecStory keeps auto-saving as the session continues — to .specstory/history/ and, if you're logged in, to SpecStory Cloud.

Use case: resume in a different agent

Continue a session in a different agent. SpecStory reconstructs the conversation into the target agent's native format, then launches it.

specstory resume codex

Find the source session (e.g. a Claude Code session) in the list.
Press r. Because you passed codex, the picker skips the target step and resumes straight into Codex.
SpecStory reconstructs the Claude session into a Codex session, writes it to Codex's session store, and launches Codex against it.

A short note is injected into the reconstructed session recording that it was resumed from another agent via SpecStory.

Info

Not every agent can be a cross-agent resume target yet. If the agent you chose can't receive a reconstructed session, resume will tell you and suggest Claude Code or Codex CLI as the target (or resuming in the original agent).

Use case: resume a session from another project

Resume a session that was started in a different repo — either in the same agent or a different one.

specstory resume

Press tab to open the all-projects browser.
Drill into the project (enter), or press / to search across all projects and jump straight to a hit.
Highlight the session and press r.
Choose the target agent (or pass one up front: specstory resume codex).

The session is reconstructed into the target agent under your current working directory, so you continue it in this project even though it began elsewhere. This is handy for bringing a design discussion or plan from one repo into another.

Use case: resume a session from another machine (Cloud)

Sessions you've synced to SpecStory Cloud from another laptop are available in the same picker — no separate "import" step.

Info

Cross-machine resume requires SpecStory Cloud and a Pro plan. Local resume (same machine, any project, any agent) always works for everyone. If you're not logged in or not on Pro, the picker simply shows local sessions and a one-line nudge in the footer.

One-time setup

Log in on every machine you want to sync from:
```
specstory login
```
Capture sessions on each machine as usual — specstory run <agent>, specstory watch, or specstory sync. Sessions are pushed to Cloud automatically when you're logged in.
On the machine you want to resume onto, make sure you're logged in:
```
specstory login
```

Resume

specstory resume

Cloud sessions from your other machines appear in the picker alongside local ones, marked with a cloud icon. They show in both the project list (for the matching project) and the all-projects browser.

Press tab for the all-projects browser, or stay in the current project's list. Cloud-only projects (repos you've worked on from another machine but never on this one) appear here with a cloud icon.
Use m to filter by machine — cycle all → local only → <each remote machine>. Remote machines are labeled by hostname; duplicate hostnames get a (1), (2) suffix.
Highlight a cloud session and press r.
Choose the target agent.

SpecStory fetches the session from Cloud, reconstructs it into the target agent's native format on this machine, and launches it. From here on it behaves like any local session and auto-saves back to .specstory/history/ and Cloud.

Tip

If a session exists both locally and in Cloud (you ran it on this machine and it synced), the local copy wins — it resumes instantly and offline. The cloud copy is still there as a backup.

Note

If a cloud session was captured by a newer version of the SpecStory CLI than the one you're running, resume will ask you to update the CLI before continuing, so you don't silently lose fields the newer version knows about. Run brew upgrade specstory and try again.

What gets saved when you resume

A resumed session is a live session like any other. As it continues, SpecStory auto-saves:

Markdown to .specstory/history/ in the current project (unless --no-cloud-sync / --only-cloud-sync is set).
Cloud sync if you're logged in (unless --no-cloud-sync).
The local index (~/.specstory/sessions.db) is updated in real time so the resumed session shows up immediately in future resume / search / list.

The usual flags apply — for example, --no-cloud-sync to keep a resumed session local, or --local-time-zone for local timestamps.

Tips

Forgot which agent or project? Run specstory search and search across everything; resume straight from a hit with r.
Preview before you commit. space opens a rendered preview of the full session so you can confirm it's the right one before resuming.
Keep sessions scoped. Use the agent's /clear between tasks so each session is one coherent thread — easier to find and resume later.
Soft-delete noise. d removes a session (or, in the browser, a whole project) from the picker and search without touching the native files on disk. The only way to restore it is to delete ~/.specstory/sessions.db and run specstory reindex.
Index looking stale? Run specstory reindex to rebuild it from the native session files on disk.