# Troubleshooting ## Install ### The plugin does not install Run `/plugin` in Claude Code to see installed plugins. If slipstream is missing, re-run: ``` /plugin marketplace add sarmakska/slipstream /plugin install slipstream ``` Confirm you are running the commands inside Claude Code in VS Code, not in a terminal. ### Slash commands do nothing Use the namespaced form: `/slipstream:map`, not `/map`. If they still do nothing, the plugin did not install; see above. ## Node and hooks ### "node: command not found" from a hook The plugin's hooks and helper run on Node. Install Node 20 or newer and restart VS Code so its integrated terminal inherits the PATH. Verify with `node --version`. ### A hook prints nothing That is expected for the silent paths: no memory yet (SessionStart and UserPromptSubmit stay quiet), a small file read (PreToolUse does not warn), or a stop that did not draw the probabilistic reminder. ## MCP tools ### The sp_ tools are not available The bundled MCP server needs `dist/mcp/index.js` to exist. In a dev checkout, run `pnpm build`. `/slipstream:doctor` flags this as `mcp-build` and `mcp-declared`. If the tools still do not appear, confirm the plugin installed and restart the session so Claude Code spawns the server. ### sp_symbol returns "no symbol X in file" The map only indexes the exported surface, so a non-exported symbol is not found. Use `sp_map` to see the exports, or `sp_lines` for a non-exported region. ## Lossless compaction and recall ### No digest was written on compaction The `PreCompact` hook imports the compiled memory module; in a dev checkout, `pnpm build` first. `/slipstream:doctor` flags `precompact-hook`. With no recorded session activity there may be nothing to digest, which is fine. ### A relevant memory was not reloaded Recall ranks lexically against the branch, changed files and tags. Add a tag that names the concept; tags score highest after the branch. See [Memory recall](Memory-Recall). ## Doctor and statusline ### /slipstream:doctor reports a FAIL Read the failing line. A missing `dist/` means the plugin was not built (`pnpm build`); a missing PreCompact line means the hooks file is stale; a missing subagent means `agents/` did not ship. Fix the named item and run it again. ### The statusline shows only "cp | ctx 0% ok" The script degraded because `dist/` is missing or the budget payload had no token data. Build the plugin. Inside Claude Code the `ctx` reads the true count from the transcript and is marked with a `*` (`ctx 47%*`); without it, the budget is an estimate. See [Statusline](Statusline). ## Token efficiency ### Claude still reads whole files Make sure a map exists: run `/slipstream:map`. The `PreToolUse` warning and the `UserPromptSubmit` reminder only engage once `.claude/slipstream/map.md` is present. The warning is a nudge, not a block, so Claude can still choose a whole-file read. ### A slice returns the wrong span The brace walker is heuristic. Fall back to a line range: `npx slipstream lines . `. Widen the range if needed. ### The map is stale Re-run `/slipstream:map` after structural changes. The map is a snapshot. ## Memory ### Recall returns nothing The query shares no terms with any memory's description or tags. Rephrase, or list everything with `npx slipstream memory list --root .`. ### MEMORY.md looks out of date Regenerate it from the files: `npx slipstream memory index --root .`. ### A memory is wrong Update it by saving again with the same name, or remove it with `/slipstream:forget` or `npx slipstream memory prune --root .`. ## Live agent dashboard ### The URL did not appear in the chat The dashboard hook imports the compiled launcher from `dist/`. In a dev checkout, run `pnpm build` first. If the dashboard is disabled, check `.claude/slipstream/dashboard.json` (`"enabled": false`) or the `SLIPSTREAM_DASHBOARD=0` environment override. ### The browser did not open Auto-open is best-effort and skipped on headless or sandboxed machines. Use the URL printed in the chat, or run `npx slipstream dashboard start . --open`. To stop it opening, set `"autoOpen": false` or export `SLIPSTREAM_DASHBOARD_OPEN=0`. ### No events are showing Confirm the hooks are wired with `npx slipstream plugin-validate` (it lists `PostToolUse` and `SubagentStop`), and that Node is on PATH so the hooks can run. Check the log is growing: `cat .claude/slipstream/dashboard/.jsonl`. If the file has lines but the UI is empty, you are viewing a different session in the header dropdown. ### Port in use, or a stale server The server binds port 0, so the OS picks a free port and clashes should not happen. If `server.json` points at a dead server, the next start detects the dead pid or closed port and replaces it. To force a clean start, delete `.claude/slipstream/dashboard/server.json`. ### A second start spawned nothing That is correct. Start is idempotent: a live server is reused, and the helper prints `already running at ...`. ## Observation memory and optimization ### memory search returns nothing Observations are captured on `Stop` (Claude Code) — a fresh project has none yet. Do some work, then try `sp_search_memory` or `npx slipstream memory search "..."`. To force a capture: `npx slipstream observe --session main`. ### the "optimised" / opt% number stays at 0 It only counts scoped reads (`sp_symbol`, `sp_lines`). If Claude is reading whole files, there is nothing to optimise yet — make sure a map exists (`/slipstream:map`) so it reaches for slices. Check the tally with `npx slipstream savings`. ### lessons are empty `sp_lessons` needs a topic to recur (default 3+ observations across the store). Lower the bar with `--min 2`, or keep working. ## Cross-IDE (Cursor, Windsurf, Antigravity, VS Code) ### the dashboard does not appear in another editor The MCP server auto-starts it on connect. Ask the agent to call `sp_dashboard` for the URL. If nothing starts, confirm the server is registered (it answers `sp_map`) and that `SLIPSTREAM_DASHBOARD` is not set to `0` in that editor's MCP env. ### the dashboard is empty in another editor Activity is emitted by the MCP server after each tool call there (no hooks). It fills as the agent uses the `sp_*` tools; if it stays empty, confirm `SLIPSTREAM_MCP_EMIT` is not `0` in the editor's MCP config. See [Cross-IDE support](Cross-IDE-Support). ### the budget gauge says "estimated", not "actual" Only Claude Code exposes a readable transcript, so only there is the count true. In other editors paste your editor's real token number into `.claude/slipstream/budget.json` as `actualTokens` to calibrate. ## Validation ### plugin-validate fails It names each problem with its file. Common causes: malformed JSON in `plugin.json` or `marketplace.json`, a hook event not wired in `hooks/hooks.json`, a `SKILL.md` missing `name`, `description` or a verification gate, a skill directory name that does not match its `name`, or a command without frontmatter. Fix the named files and rerun: ``` npx slipstream plugin-validate ``` ### validate reports skill issues Same idea, scoped to skills. Each issue names the `SKILL.md` and the fault. See [Writing a skill](Writing-a-Skill). ## Build and CI ### pnpm build fails locally Use Node 20 or newer and pnpm 10. Run `pnpm install` first, then `pnpm build`. ### CI is red The workflow runs install, lint, build, skill validation, plugin validation and tests. The failing step's log names the cause. Reproduce locally with the same `pnpm` scripts. --- SarmaLinux . sarmalinux.com . [Repository](https://github.com/sarmakska/slipstream)