# Spool: share and resume Claude Code and Codex CLI sessions

> Spool turns agent sessions into durable web pages that other people can read and continue in their own agent. It is early stage, it is local-first, and native resume only works for two providers today.

**paperboytm/spool** — Store, share, and resume AI coding sessions.

- Repository: https://github.com/paperboytm/spool
- Website: https://spool.new
- Stars: 591 · Forks: 41
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/paperboytm-spool

## The problem Spool targets: agent work that dies in a terminal

A coding agent session is a long, messy artifact. It contains a conversation, a sequence of tool calls, a set of touched files and a net diff. Most of it stays on one developer's disk. When that developer wants to show a colleague what happened, the usual output is a screenshot, a pasted excerpt, or a verbal summary. None of those can be resumed, and none of them can be searched later.

Spool's answer is to treat the session itself as the shareable object. The README describes it as turning work done with coding agents into durable web pages that other people can understand and resume. The author shares a real Session rather than a reconstruction, and a reader moves from Summary to conversation, tool activity, files and diff before continuing the work in their own agent.

The intended audience is narrow and specific: people who already use Claude Code or Codex CLI heavily, and who need to hand that work to someone else. The README also lists Gemini CLI, OpenCode and Pi as providers it can collect sessions from locally, but those remain Link-only shares and cannot be resumed natively.

## How the share stack is put together

The repository is a pnpm workspace with two top-level groups. Under apps/ sit three surfaces: cli for indexing, sharing, reading, resuming and automation; web for spool.new, which hosts the homepage, docs, Profiles, account and Team pages and the Session reader; and backend, described as the Hub, identity, Teams, publication and media API running on Cloudflare.

Under packages/ sit the libraries. core handles local Session ingestion, organization, SQLite storage and full-text search. redact holds the sensitive-data detection shared by publishing surfaces. session-kit provides a browser-safe Session model with canonical records, views and diffs. session-view renders conversations for Session pages, and share-kit holds curated .spool documents, templates and export primitives.

That split matters because it tells you where the trust boundary is. Ingestion, storage and search happen locally in core, using SQLite. The redaction pass runs before anything is uploaded. What leaves the machine is the records selected during the Share flow, and the README is explicit that nothing leaves until the author confirms that flow. The provider session stays authoritative, and Git stays authoritative for code.

The README draws a line between four verbs that are easy to confuse. Share is the explicit action that sends records to the Hub and returns a URL. Publish is the default result for supported Claude Code and Codex CLI shares, meaning the session becomes Public and can appear on the author's Profile, in Explore and in search. Read is the browsing experience. Resume or Fork creates new agent-native work that keeps visible lineage to the source.

## Installing the CLI and sharing your first session

The README gives a single install command that pipes a script from spool.new into sh. Install once, open a new terminal, and the spool command is available from any project directory.

```bash
curl -fsSL https://spool.new/install.sh | sh
```

Piping a remote script into a shell is the kind of thing worth pausing over. You are trusting whatever spool.new serves at that moment. If that is not acceptable in your environment, the README does not document an alternative install path such as a package manager or a pinned release archive.

With the CLI on your path, change into a project that has agent sessions and run the bare command.

```bash
cd /path/to/project
spool
```

The README states that bare spool refreshes the local index, signs in through the browser if needed, and selects the latest Session in the current project. It then shows what will be shared, scans for sensitive values, confirms the resulting visibility, publishes the records to the Hub, and returns a durable URL. Expect a browser sign-in on the first run and a printed summary of the session before anything uploads.

When you want to pick a specific session or pass options, use the explicit form with a session UUID.

```bash
spool share <session-uuid>
```

A reader can open the returned URL without installing Spool. To continue the work locally, they run resume against that URL.

```bash
spool resume <session-url>
```

Resume creates a new provider-native Session and preserves its relationship to the source. The README states the shared source is never modified, which is the right default: the reader gets a fork, not a write into someone else's history.

Visibility is the part to read carefully. Supported Claude Code and Codex CLI sessions are Public by default and can appear in Explore and search. Other providers stay Link-only. When sharing into a Team-owned Project, omitting --public fails closed to Team-only, while passing it keeps the session Public.

```bash
spool share --project paperboy/spool --public
```

## Public by default is the sharpest edge here

The confirmation step states both the Project owner and the initial visibility before upload, and the redaction pass looks for likely credentials, tokens, personal data and local paths. That is a reasonable design. It is also a design where the default answer to "who can see this?" is "everyone", for the two providers most people will actually use.

A session transcript is not a curated artifact. It contains whatever the agent read, whatever you pasted, and whatever paths the tools printed. Local path detection helps, but a path is not the same as the contents of a file the agent displayed. The README does not describe a dry-run mode that prints the full payload without uploading it, so the reviewable surface appears to be the pre-share summary and the sensitive-value scan rather than the exact bytes.

Withdrawal is the recovery path, and it differs by owner. Withdraw makes the current hosted copy return 410 Gone. A personal author can later explicitly Share the same Session again. For a Team-owned asset, a withdrawal by an Owner or Admin is permanent and cannot be revived by another member. That asymmetry is worth knowing before you hand a session to a Team Project, because it removes your own ability to re-share it later.

The other boundary is scope. Spool publishes agent work and its context. It does not replace the project's source-control system, and the README says so directly. If you want a review of a diff, you want a code host, not a session page.

## Where Spool is the wrong tool

If your team runs Gemini CLI, OpenCode or Pi, Spool will collect and organize those sessions locally, but the README states they remain Link-only until Discovery supports them, and native Resume currently works only for Claude Code and Codex CLI. You get a readable page and nothing you can continue in place. That is a real limitation, not a roadmap footnote, because continuation is the feature that separates Spool from a transcript viewer.

If your requirement is that no session content ever leaves your machines, the local-first framing only covers the preparation stage. Sharing is the point of the product, and sharing means uploading records to a Hub that the README describes as running on Cloudflare. The local SQLite index and full-text search are genuinely local; the published page is not.

If you need a stable, versioned integration surface, note that the project describes itself as early stage and that the release history shows several 0.8.x versions within a few days of each other in late July 2026. The last push to the default branch was on 2026-07-27. Treat the CLI flags and the .spool document format as moving until the project says otherwise.

## How it differs from a plain transcript dump or a code host

The closest thing to a real alternative is the combination people use today: paste the transcript into a gist or a shared doc, and link the pull request for the code. That approach is provider-agnostic and needs no account. The difference in approach is that a pasted transcript has no canonical record, no diff computed against the session's own file activity, and no lineage, so a reader cannot tell which parts of the text correspond to which tool call and cannot continue from it.

Spool's session-kit package is what makes the difference concrete: a browser-safe Session model with canonical records, views and diffs, rendered by session-view. The page is generated from structured records rather than from a text blob, which is why the reader can move between Summary, conversation, tools, files and diff as separate views.

Against a code host, the split is clean. Git remains authoritative for code, and Spool publishes the agent work and its context. A pull request tells a reviewer what changed. A Spool page tells a reviewer how the change was arrived at and lets them pick the work up. Those are different questions, and neither tool answers the other's.

## Licence, trademark and the cost of keeping up

The repository declares MIT in package.json and the README's License section, and the package.json sets license to MIT. The README adds a trademark note: Spool and the Spool logo are trademarks of TypeSafe Limited, and the MIT License covers the source code only and does not grant permission to use the name or logo. If you fork and redistribute, that distinction applies to how you brand the result. This is a description of what the repository states, not legal advice.

Upgrade cost is mostly about the client, not the server. The CLI is distributed through the install script at spool.new, so upgrading means either re-running that script or whatever update path your environment provides. The README documents the install command and the development workflow, but it does not document an update command or a version pinning mechanism for the installed CLI. The release cadence visible in the repository, three 0.8.x releases across two days in July 2026, suggests you should expect the published page format and the CLI surface to change between versions.

For contributors rather than users, the README gives the workspace commands. pnpm install followed by pnpm run rebuild:native:node prepares the native modules. The per-package checks run through pnpm --filter with the package names @spool-lab/cli, @spool/backend and @spool/web, each with typecheck and test, plus a build step for the web package. The backend and the documentation site start in separate terminals with pnpm --filter @spool/backend dev and pnpm --filter @spool/web dev.

## Conclusion

Adopt Spool if you already run Claude Code or Codex CLI and need to hand a session to a teammate who will continue it, or if you want a reviewable, searchable record of how a change was produced. Do not adopt it as a code review tool, as a source-control replacement, or if your work runs on Gemini CLI, OpenCode or Pi and you need native resume, because the README states that resume currently works only for Claude Code and Codex CLI. Before your first real share, run spool in a scratch project and read the sensitive-value scan output and the visibility line it prints, then confirm the URL opens for someone who is not signed in. If that URL is public and you did not intend it to be, withdraw it: the README states the hosted copy then returns 410 Gone.

## FAQ

### How do I install the Spool CLI?

The README gives a single command that pipes the installer from spool.new into sh. Install once, open a new terminal, and the spool command is then available from any project.

### Which coding agents can Spool share and resume?

Spool can collect sessions from Claude Code, Codex CLI, Gemini CLI, OpenCode and Pi. The README states that native Resume currently works only for Claude Code and Codex CLI, and that the other providers remain Link-only shares.

### Are Spool sessions public when I share them?

For supported Claude Code and Codex CLI shares, the README states that Public is the default and the session can appear in Explore and search. Other providers remain Link-only, and sharing into a Team-owned Project without --public fails closed to Team-only.

### What happens when a session is withdrawn in Spool?

Withdraw makes the current hosted copy return 410 Gone. A personal author can explicitly share the same session again later, but the README states that a Team-owned withdrawal by an Owner or Admin is permanent and cannot be revived by another member.

### Does Spool replace Git for tracking code changes?

No. The README states that the original provider session remains authoritative and that Git remains authoritative for code. Spool publishes agent work and its context; it does not replace the project's source-control system.

### What licence does Spool use?

The repository declares MIT, and the README notes that the MIT License covers the source code only. It does not grant permission to use the Spool name or logo, which the README identifies as trademarks of TypeSafe Limited.

## Sources

- [Issues](https://github.com/paperboytm/spool/issues)
- [paperboytm/spool on GitHub](https://github.com/paperboytm/spool)
- [Project website](https://spool.new)
- [README](https://github.com/paperboytm/spool/blob/main/README.md)
- [Releases](https://github.com/paperboytm/spool/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/paperboytm-spool