Spooling
Back to spooling.ai

End-to-end

How a single AI coding session flows from your IDE into Spooling Cloud, with verification commands at every stage.

This is the comprehensive walkthrough: a chat happens in your AI tool, it lands in Spool's local database, you see it in the local GUI, you push it to Spooling Cloud, and you see it in the admin GUI at app.spooling.ai. Every stage has a verification command so you can tell exactly where the pipeline is or isn't working.

If you have not installed Spool yet, do the Quickstart first. This page assumes the binary works.

The pipeline

1. IDE / CLI                    you type into Claude, Gemini, Cursor, etc.
        ↓                       provider writes a session file or DB row
2. spooling sync                   parser reads provider data
        ↓                       stores in the local database
3. spooling ui                     local API + GUI on :3002 / :3003
        ↓                       you browse, search, audit costs locally
4. spooling push                   ships sessions to api.spooling.ai
        ↓                       cloud writes them under your workspace
5. app.spooling.ai              team members search across each other's sessions

Stages 1 to 3 are local-only and free. Stages 4 to 5 require Spooling Cloud.

Stage 1: the session is captured by the IDE

You don't run anything here. Spool reads whatever the AI tool already writes to disk.

ProviderWhere it writesNotes
Claude Code~/.claude/projects/<slug>/<uuid>.jsonlStreamed JSONL, written as you chat
Codex CLI~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonlOne file per session
Cursor, Windsurf, Antigravity~/Library/Application Support/<App>/User/workspaceStorage/<hash>/state.vscdbSQLite, per-workspace
CopilotCode/User/workspaceStorage/<hash>/chatSessions/*.jsonlVS Code chat-API format
KiroKiro/User/globalStorage/kiro.kiroagent/workspace-sessions/<base64>/*.jsonOne JSON per session
Gemini Code AssistCode/User/globalStorage/state.vscdb ItemTable key google.geminicodeassistAll threads in one JSON value, keyed by account email

To verify a provider sees something:

spooling init

Each connected provider should show Status: connected and a positive file count.

Stage 2: sync to the local database

spooling sync

This walks every connected provider, finds new or changed session files, and stores them in the local database. By default it embeds message content for semantic search; pass --no-embed for a fast first run.

spooling sync reference →

Verify the sync landed

spooling stats

You should see a row per provider with non-zero session and message counts. If you just had a Gemini conversation and want to confirm only that:

spooling stats --provider gemini

If spooling stats shows zero for a provider you just used, see Stage 2 troubleshooting below.

Stage 3: browse and search locally

spooling ui

Boots three things at once:

  • API on http://localhost:3002 (read-only HTTP for the GUI)
  • GUI on http://localhost:3003 (Next.js, AG Grid, dashboards)
  • MCP server on http://localhost:3004/mcp (so Claude Code, Cursor, and any other MCP client can call into your local Spool)

Verify the GUI

Open http://localhost:3003. The Sessions page should list everything spooling sync ingested, with provider dots colored by source. Click into a session to see its messages, tool calls, and trace.

The CLI equivalent of "is the data really there":

spooling stats --by provider
spooling search "the topic of your last chat" --limit 5

If spooling search returns nothing for content you know is in the DB, your embeddings step probably skipped. Re-run spooling sync without --no-embed.

Stage 4: push to Spooling Cloud

This is optional. Skip it if you only want local memory.

One-time login

Create an account at app.spooling.ai, then sign the CLI in. Your browser opens to approve the login and choose which workspace (personal or a team) this machine pushes to.

spooling login
spooling cloud status

Prefer a key? Mint one in Settings in the app and run spooling cloud login --key sk_....

status should print the workspace's existing session count, message count, and total cost.

Push

Always preview first when pushing to a team workspace, since spooling push with no filters ships every recent session on this laptop.

spooling push --dry-run
spooling push

Scope down with filters when needed:

# only sessions from one repo
spooling push --cwd ~/anthonyloya-com --dry-run

# only sessions whose title mentions a project (useful when cwd is generic)
spooling push --title "Gemini Code Assist" --dry-run

spooling push reference →

Verify in the cloud

CLI:

spooling cloud status

The sessions and providers counts should have increased. If you pushed a Gemini session for the first time, providers jumps from N to N+1.

GUI: open app.spooling.ai → Sessions. The new sessions should appear with the same provider color and label as locally. The page is workspace-scoped, so make sure the workspace switcher in the top-left matches the workspace your CLI key belongs to.

Stage 5: keep both sides fresh

Two long-running processes cover continuous capture:

# in one terminal: keep the local DB in sync with provider files
spooling watch

# in another: keep the cloud workspace in sync with the local DB
spooling cloud watch

spooling watch polls the provider directories every few seconds and runs spooling sync for any changed file. spooling cloud watch does the same against the local DB and pushes new rows up. Run both under tmux or a launchd plist if you want them to survive shell exits.

Troubleshooting

Stage 2 troubleshooting

spooling sync runs but a provider's count stays at 0.

  1. Confirm the provider's storage location actually has data. Check the table in Stage 1 for the path; if the file or DB row does not exist, the IDE has not flushed the session yet. Some providers (Gemini Code Assist webview, Gemini CLI) only persist when you explicitly send a real chat message or run /chat save.
  2. spooling init should list the provider as connected. If it says not detected, the directory is missing entirely.
  3. If the file exists but the count is still 0, run spooling sync --provider <name> for just that one. The error message is more specific than the bulk run's.

spooling sync says it processed N files but spooling stats shows fewer.

The file was empty, malformed, or contained zero user messages. Spool drops sessions with no messages so they don't pollute search.

Stage 3 troubleshooting

The GUI says "Failed to fetch" or shows no sessions.

Check that the API is up:

curl http://localhost:3002/api/overview

If that returns nothing, the API process inside spooling ui failed. Restart with spooling ui again and watch the console for a database error (is another spooling process holding the local database open?).

spooling search returns zero results for content you know is in the DB.

Embeddings did not write. Re-run spooling sync without --no-embed. To force a re-embed of everything, use spooling sync --reembed.

Stage 4 troubleshooting

spooling push reports rejected: IDs already owned by another workspace.

The same session_id was pushed to a different workspace previously. Spooling Cloud refuses to silently move sessions between workspaces. Two options:

  • Want it in both workspaces? Re-run with --copy. The cloud rewrites session IDs deterministically so the same source session can live in multiple workspaces.
  • Want it only here? Log into the wrong workspace, run spooling cloud delete for those sessions, then push from the right workspace.

spooling cloud delete reference →

spooling push succeeds but the session never appears in the admin GUI.

Check the workspace switcher in the admin GUI. The CLI key is workspace-scoped: a key minted in your personal workspace will not push to your team workspace, and vice versa. Run spooling cloud status to see which workspace your CLI is logged into; switch the GUI to match.

Stage 5 troubleshooting

spooling cloud watch exits immediately or pushes the same sessions repeatedly.

watch is idempotent: re-pushing a session that's already in the cloud is a no-op. If the count keeps incrementing in the watch logs, the cloud is treating each batch as new because session IDs are changing locally. That usually means a provider re-ran a session through spooling sync with a different ID. Open an issue with the provider name; this is a parser bug.

What's next

On this page