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 sessionsStages 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.
| Provider | Where it writes | Notes |
|---|---|---|
| Claude Code | ~/.claude/projects/<slug>/<uuid>.jsonl | Streamed JSONL, written as you chat |
| Codex CLI | ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl | One file per session |
| Cursor, Windsurf, Antigravity | ~/Library/Application Support/<App>/User/workspaceStorage/<hash>/state.vscdb | SQLite, per-workspace |
| Copilot | Code/User/workspaceStorage/<hash>/chatSessions/*.jsonl | VS Code chat-API format |
| Kiro | Kiro/User/globalStorage/kiro.kiroagent/workspace-sessions/<base64>/*.json | One JSON per session |
| Gemini Code Assist | Code/User/globalStorage/state.vscdb ItemTable key google.geminicodeassist | All threads in one JSON value, keyed by account email |
To verify a provider sees something:
spooling initEach connected provider should show Status: connected and a positive file count.
Stage 2: sync to the local database
spooling syncThis 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.
Verify the sync landed
spooling statsYou 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 geminiIf spooling stats shows zero for a provider you just used, see Stage 2 troubleshooting below.
Stage 3: browse and search locally
spooling uiBoots 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 5If 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 statusPrefer 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 pushScope 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-runVerify in the cloud
CLI:
spooling cloud statusThe 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 watchspooling 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.
- 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. spooling initshould list the provider asconnected. If it saysnot detected, the directory is missing entirely.- 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/overviewIf 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 deletefor 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
- Cross-workspace patterns for when the same session needs to live in personal and team workspaces.
- MCP endpoint so any agent can search the cloud as a tool, alongside the local one.
- Provider-specific notes for gotchas in how each AI tool persists chat.