The making of Spool

A product-and-engineering account of a local-first project context hub: who it serves, what crosses the network boundary, what an AI may write, and what changed only after the system met real work.

Who it is for

Spool is for people carrying several long-lived workstreams across tools that do not share memory: researchers, graduate students, developers, and people building something alone. The common cost is not “taking notes.” It is having to reconstruct the same project for every new AI conversation — which paper matters, which decision already failed, and what changed since last week.

The product sets a deliberately narrow target: re-entering a project should cost one paste, not an archaeological dig through chats, mail, tabs, and half-remembered decisions. It sits upstream of document tools. A project is a quiet, append-only log, not a collaborative canvas or a replacement for Notion.

Research boundary. The first version was built by dogfooding against the developer’s own multi-project workload. That produced useful reversals, but it is not external user research; validation with other users remains a post-release step.

What the product does

Three verbs form one loop. None of them needs a model in the critical path.

1. Capture Double-tap Option after copying to file the clipboard with its time and source, while a confirmation overlay accepts the thought that made it worth saving.
2. Project Keep fragments in a time-ordered log with exactly two levels of structure: Workspace, then Project.
3. Pack Assemble the current project into deterministic Markdown that can be pasted into any AI client. The same project produces the same bytes on the same day.

How the three surfaces relate

The desktop interface, MCP server, and CLI engine slot are three local surfaces around one source of truth. The diagram separates “runs on your machine” from “belongs to the Spool process” so the network claim can be inspected rather than inferred.

The GUI and capture overlay communicate with the Rust/Tauri core locally. That core owns one SQLite database. Running spool --mcp exposes the same library over stdio to an AI client; the CLI engine slot instead starts Claude Code, Codex CLI, or Gemini CLI as a separate process. Gemini supports Weekly Review and draft goals, but not Follow Up. The API engine is the third route and the newest: it starts spool-ai, a small binary shipped inside the app that takes one JSON request on stdin, makes one HTTPS call, and writes one JSON envelope back. It refuses plain http://, and the key reaches it only through stdin — never through the command line, where any process on the machine could read it. All three routes preserve the same distinction: what Spool does locally, and what another process does on the network.

Privacy and the write boundary

Reading and writing are separate permissions. Content leaves the machine only inside a program the user installed and authorised; the program that crosses the network is named at each path.

• AI may append; it may not overwrite. Machine-written blocks carry a server-enforced source label and cannot replace a user-authored block.
• AI may not borrow the user’s authority. Annotation authorship is stored, so a machine note renders as machine framing rather than as the user’s judgement.
• AI may propose a correction; the user decides. The original stays visible and searchable. Retiring material is a human action.

Distribution, signing, and notarisation

On macOS, Spool ships directly as a Developer ID–signed, Apple-notarised disk image. The Mac App Store is not the distribution path because sandboxing conflicts with the system-wide capture gesture. The application and the disk image are checked separately: users download the wrapper, so a notarised application inside an unnotarised disk image is not enough. The Windows installer is produced by CI and ships unsigned in this first release — a certificate is a recurring cost against an unproven platform, and pretending otherwise on the download page would be worse than SmartScreen's warning.

Inspect the release and its assets on GitHub. The website’s stable download URL points to the fixed-name copy published alongside the versioned artifact.

What measurement changed

The case-study ledger records commands and source evidence for every public figure. Two measurements changed product priorities rather than merely describing the finished system.

A separate live web-search run cost approximately $0.45 and exposed failures that mocks and prompt inspection had not revealed.

Failures that changed the system

The useful unit in a postmortem is not the patch; it is the guard that remains.

Boundaries, not promises

• Two platforms, not equally deep. Windows arrived in 0.5.0 and runs the same library and the same capture gesture, read through Raw Input rather than a keyboard hook. What did not cross over is the macOS-specific work around focus handling and browser-tab source capture, so the Windows build records the source app rather than the page you were reading.
• No auto-update. A new version is a manual download from the direct release.
• Source-visible, all rights reserved. The repository has no licence granting reuse.
• Two checks remain human. The authorised capture gesture sits upstream of synthetic events, and the packaged webview cannot be trusted from synthetic clicks; both are escalated to a person rather than claimed as automated.
• Spool is not a server, sync service, team workspace, or document editor. It stores one local project log and prepares context for tools the user already chose.

There is no placeholder video. The interactive browser demo walks through the capture → project → pack loop; the screenshots above are from the current isolated desktop build.

Spool is designed and built by Ocean (KIM-ocean-HZ). Source, roadmap, and the full product constitution are on GitHub; reproducible public figures live in the Case Study Ledger.