How slipstream works

Bundled MCP server (stdio).

tools.ts defines the nine sp_ tools and callTool, each a thin wrapper over the same library the helper CLI uses. server.ts is the pure handleRequest dispatcher plus a newline-delimited JSON-RPC stdio loop. index.ts is the entry point the IDE spawns. The protocol slice in play is small and stable: initialize, tools/list, tools/call. Tests drive handleRequest directly without spawning a process; a separate suite spawns the real binary over stdio.

The compact project map.

generateMap reads each source file once, extracts the exported surface and a one-line purpose with a cheap line scan, and never stores file contents. retrieveSymbol walks braces from a declaration line to return one slice. retrieveLines returns a bounded range. searchMap ranks files by a query. The whole module is a fast heuristic on purpose: the agent decides where to look from the map, then reads the real slice.

File-based memory store, recall and digest.

store.ts is one Markdown file per fact under .claude/slipstream/memory/ with frontmatter, plus a regenerated MEMORY.md index (addMemory, pruneMemory, listMemories, recallMemories, regenerateIndex). recall.ts ranks the store against a task signal (rankBySignal, selectRelevant) and returns only the subset that fits a token budget. digest.ts builds the PreCompact session digest (buildDigest, digestToMemory).

Token budget and read guard.

estimateTokens converts bytes to a conservative token count (3.6 bytes per token). budget reports an ok / warn / compact level against the window. guardRead flags large whole-file reads, which the PreToolUse hook surfaces as a warning before the read happens.

The local SSE dashboard.

events.ts defines and redacts the event schema. log.ts is the concurrency-safe append-only writer and reader (tested under 25 parallel writers). state.ts folds events into agent state, the same fold that drives live view and replay. server.ts is the node:http server with SSE. launch.ts is idempotent start and browser open. runner.ts is the detached process entry point.

Mind map and artifact.

buildMindMap turns the project map into a tree. mindMapToMermaid renders it as a themed Mermaid flowchart for the chat. renderArtifact writes a self-contained HTML file you can share.

Skill contract and loader.

skillFrontmatterSchema enforces the plugin name and description plus a namespaced slipstream block (category, requires, verification gate, tags). loadSkills walks skills/**/SKILL.md, aggregates every issue, checks the directory name matches the skill name, and rejects shipping skills without a gate.

The status bar line.

formatStatusline renders the one-line status (budget level, durable memory count, active skill, model) as a pure function. The formatting is pinned by a snapshot test so changes are intentional.

End-to-end install check.

runDoctor checks the MCP server is built and declared, every hook (including PreCompact) is wired, the memory directory exists, the helper CLI is built, the statusline and output style are present, the subagents are loadable, and the plugin manifest is valid. renderDoctor prints PASS / FAIL per check. Backs /slipstream:doctor.

The helper entry point.

A single dispatcher invoked by the hooks and the slash commands. Subcommands: map, slice, lines, guard, budget, memory, mindmap, status, dashboard, validate, plugin-validate, doctor, statusline, recall-signal, digest.

Manifest validator.

Proves the plugin is well-formed: every declared hook script exists, every declared MCP server has an entry point, every subagent has a name, every command file is loadable. Fails loudly on the smallest drift.

The slice of MCP in play is initialize + tools/list + tools/call. A plugin that bundles a server should add as little as possible to a user's install. The handler is a pure exported function, so tests drive it without a process.

I write the JSON-RPC framing myself. The benefit is zero runtime dependencies on the MCP path and a server I can audit in one file.

Append-only by construction, tailable, human-readable when something goes wrong, and replay is free: state is a pure fold over the log.

Hand-rolled concurrency control via a small advisory lock in log.ts, tested under 25 parallel hook processes.

The dashboard traffic is one-directional and SSE reconnects on its own. node:http is the standard library and serves one page, two JSON routes and one event stream in one file.

A tiny hand-written router. No Express tree to keep secure and in sync with the rest of the plugin build.

Reviewable, diffable, survives without a running service. The index is regenerated from the files, so it cannot silently drift.

No SQL queries over memory. Recall is signal-ranked at session start, which is what we actually need.

Loading the full store gets more expensive the more useful the store becomes. Ranking against a cheap task signal keeps recall cost flat in store size.

With no signal, recall loads nothing and defers to MEMORY.md. That is the design: loading arbitrary facts with no signal is the very thing the helper is built to avoid.

The helper cannot read the IDE's internal token counter, so it estimates from bytes-into-context at a cautious 3.6 bytes per token.

It is guidance, not a guarantee, and the wording everywhere says so. Conservative on purpose, so it warns early.