{"_id":"@akbuilds/skillfish-router","name":"@akbuilds/skillfish-router","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@akbuilds/skillfish-router","version":"0.1.0","description":"Silent, minimal-context skill router for Claude Code & Claude Desktop: a UserPromptSubmit hook (interceptor) + MCP server (routing engine) over a shared warm capability index. Install with `npx @akbuilds/skillfish-router install`.","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/akcodes9/skillfish-router.git"},"homepage":"https://github.com/akcodes9/skillfish-router#readme","bugs":{"url":"https://github.com/akcodes9/skillfish-router/issues"},"engines":{"node":">=18"},"bin":{"skillfish-router":"bin/skillfish-router.mjs","skillfish-hook":"bin/skillfish-hook.mjs","skillfish-mcp":"bin/skillfish-mcp.mjs","skillfish-daemon":"bin/skillfish-daemon.mjs"},"exports":{".":"./dist/index.js","./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","prepack":"npm run clean && npm run build","prepublishOnly":"npm run clean && npm run build","dev:mcp":"tsx src/mcp/server.ts","dev:daemon":"tsx src/ipc/daemon.ts","route":"tsx src/tools/route-cli.ts","cli":"tsx src/cli/index.ts","test":"vitest run","typecheck":"tsc --noEmit -p tsconfig.json","smoke":"node scripts/smoke.mjs","audit":"node scripts/audit.mjs","e2e":"node scripts/e2e.mjs","artifacts":"node scripts/make-artifacts.mjs"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4"},"devDependencies":{"@types/node":"^22.10.0","tsx":"^4.19.2","typescript":"^5.7.2","vitest":"^2.1.8"},"keywords":["claude","claude-code","mcp","model-context-protocol","skills","router","hook"],"_id":"@akbuilds/skillfish-router@0.1.0","gitHead":"8dd37e7560dc486994fb466999a1d23264ad44aa","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-5yK6hVxZvKdi1E0eJpTS/JdTIRQWF3bR/uH+9Cgg7ijy4cMVoD42lTBk/rDKMyMMFEXMcx5CdxBt2sddq0Q5cA==","shasum":"04eed628feaf40edc3c260258513d9f8e1c26343","tarball":"https://registry.npmjs.org/@akbuilds/skillfish-router/-/skillfish-router-0.1.0.tgz","fileCount":104,"unpackedSize":252807,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@akbuilds%2fskillfish-router@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCZkR12qkkRjDY9H5rIFkTPBLa+GYhpGR92X3BvgjkbSwIhAK1dS9eL36+01ODyq3u4HkFL1UuXJ1UjQ9sZlB6Op17V"}]},"_npmUser":{"name":"akbuilds","email":"akhil0903@gmail.com"},"directories":{},"maintainers":[{"name":"akbuilds","email":"akhil0903@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skillfish-router_0.1.0_1784907641566_0.16928708471543596"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-24T15:40:41.477Z","0.1.0":"2026-07-24T15:40:41.713Z","modified":"2026-07-24T15:40:42.045Z"},"maintainers":[{"name":"akbuilds","email":"akhil0903@gmail.com"}],"description":"Silent, minimal-context skill router for Claude Code & Claude Desktop: a UserPromptSubmit hook (interceptor) + MCP server (routing engine) over a shared warm capability index. Install with `npx @akbuilds/skillfish-router install`.","homepage":"https://github.com/akcodes9/skillfish-router#readme","keywords":["claude","claude-code","mcp","model-context-protocol","skills","router","hook"],"repository":{"type":"git","url":"git+https://github.com/akcodes9/skillfish-router.git"},"bugs":{"url":"https://github.com/akcodes9/skillfish-router/issues"},"license":"MIT","readme":"# Skillfish Router\n\nSilent, minimal-context **skill router** for **Claude Code** and **Claude Desktop**.\nEvery prompt is intercepted and the **Skill Router** determines the **Skills\nNeeded** — the minimum set of installed skills required for the request — which\nis surfaced to the model invisibly, unless you ask *\"how were skills determined?\"*.\n\n> **Skills Needed from Skill Router.** The Skill Router is the *only* component\n> that decides which skills a request needs. Everything downstream (the hook\n> injection, the MCP tools, the model) consumes the router's **Skills Needed** —\n> nothing re-selects or re-ranks skills independently. This keeps context minimal\n> (1–3 skills, names only) while staying correct.\n\nCross-platform (macOS · Windows · Linux). One runtime dependency\n(`@modelcontextprotocol/sdk`); the routing core has none.\n\n- **How it decides / internals:** [`ARCHITECTURE.md`](./ARCHITECTURE.md)\n- **Why hook + MCP (and not MCP alone):** a pure MCP server can't intercept\n  prompts — only a `UserPromptSubmit` hook runs per-prompt. This ships both.\n\n---\n\n## One-command install\n\n**npx (all platforms — recommended):**\n\n```bash\nnpx @akbuilds/skillfish-router install\n```\n\nThat's it — no clone, no global install. You can also install globally:\n\n```bash\nnpm install -g @akbuilds/skillfish-router && skillfish-router install\n```\n\nOr, from a downloaded release: double-click **`install.command`** (macOS) or\n**`install.bat`** (Windows); on Linux run **`bash installers/install.sh`**.\n\nThe `install` command:\n\n1. Detects Claude Code and Claude Desktop.\n2. **Backs up** your Claude config (atomic writes; rollback on failure).\n3. Copies the dependency-free hook/daemon runtime to a **stable** `~/.skillfish/runtime`\n   and installs the `UserPromptSubmit` hook pointing there (so it survives npx\n   cache eviction and upgrades).\n4. Registers the MCP server as `npx -y @akbuilds/skillfish-router@<ver> mcp` for\n   Claude Code and (if present) Claude Desktop — the modern MCP convention.\n5. Indexes your installed Skillfish skills.\n6. Runs a final health check (`doctor`).\n\nIdempotent — run it again anytime; it converges to exactly one hook and one MCP\nentry. Verify with:\n\n```bash\nnpx @akbuilds/skillfish-router doctor\n```\n\n---\n\n## CLI\n\nRun any command with `npx @akbuilds/skillfish-router <command>` (or the bare\n`skillfish-router <command>` after a global install):\n\n```\n  install          Install the hook + register the MCP server\n  uninstall        Remove everything it added, restoring prior config\n  update           Upgrade the package, then re-apply configuration\n  doctor           Diagnose runtime, build, live server, and wiring\n  status           Concise snapshot of the current install\n  rebuild-index    Force-rebuild the capability index\n  mcp              Run the MCP server over stdio (Claude launches this via npx)\n  version          Print the version\n\nGlobal:   --dry-run  --json  --yes/-y  --help/-h  --version/-V\ninstall:  --no-hook  --no-mcp  --no-desktop  --code-only  --desktop-only  --force-desktop\nuninstall:--restore-backup  --purge\nupdate:   --local\n```\n\n`--dry-run` prints every change without writing a byte — safe to try first.\n`mcp` is invoked by Claude, not by you.\n\n---\n\n## Uninstall\n\n```bash\nnpx @akbuilds/skillfish-router uninstall                 # surgical: removes only what it added\nnpx @akbuilds/skillfish-router uninstall --restore-backup # byte-for-byte restore from backup\nnpx @akbuilds/skillfish-router uninstall --purge          # also delete ~/.skillfish (runtime + backups)\n```\n\nThe surgical default preserves any unrelated hooks or MCP servers you have.\nBackups live in `~/.skillfish/backups/` (or `%USERPROFILE%\\.skillfish\\backups\\`).\n\n---\n\n## What it does to your config\n\n| Target | File | Change |\n| --- | --- | --- |\n| Claude Code (hook) | `~/.claude/settings.json` | one `UserPromptSubmit` hook → `node \"~/.skillfish/runtime/…/user-prompt-submit.js\"` |\n| Claude Code (MCP) | `~/.claude.json` | `mcpServers[\"skillfish-router\"]` = `npx -y @akbuilds/skillfish-router@<ver> mcp` |\n| Claude Desktop (MCP) | platform config¹ | `mcpServers[\"skillfish-router\"]` = `npx -y @akbuilds/skillfish-router@<ver> mcp` |\n\n¹ macOS `~/Library/Application Support/Claude/claude_desktop_config.json` ·\nWindows `%APPDATA%\\Claude\\claude_desktop_config.json` ·\nLinux `~/.config/Claude/claude_desktop_config.json`.\n\nAll writes are atomic (temp + rename) and preceded by a full backup. Nothing is\nhardcoded — every path derives from `os.homedir()` and platform conventions, and\nall are overridable via env vars (used by CI to sandbox the whole flow).\n\n---\n\n## Troubleshooting\n\n**`skillfish-router: command not found` after install.**\nThe npm global bin dir isn't on your PATH. Find it with `npm bin -g` (or\n`npm prefix -g`) and add it to PATH. On Windows, open a new terminal so PATH\nrefreshes.\n\n**`doctor` says \"node on PATH\" is a warning.**\nClaude spawns the hook/MCP via `node`. If your shell can't find `node`\nnon-interactively, install Node system-wide or ensure your shell profile exports\nit. The router still works when launched from a shell that has `node`.\n\n**`doctor` says \"MCP server starts: probe failed\".**\nThe build is missing or corrupt. Re-run `npx @akbuilds/skillfish-router install`\n(or `… update`), then `… doctor` again.\n\n**Claude Code doesn't seem to route.**\nHooks load at session start — fully restart Claude Code after installing.\nConfirm wiring with `skillfish-router status` (hook=yes, mcp=yes).\n\n**Claude Desktop doesn't show the server.**\nRestart Claude Desktop after install — it reads its config on launch.\n\n**\"Claude Desktop not detected — skipping.\"**\nIts app-data folder doesn't exist yet. Install/launch Claude Desktop once, then\nre-run `skillfish-router install`, or force it with `--force-desktop`.\n\n**A config file failed to parse.**\nThe installer refuses to overwrite a config it can't parse (to avoid data loss).\nFix the JSON syntax in the reported file, then re-run.\n\n**Undo everything, exactly.**\n`skillfish-router uninstall --restore-backup` restores each touched file from the\ninstall-time backup (or deletes files the installer created).\n\n**PowerShell blocks the script.**\nUse the provided `install.bat`, or run\n`powershell -ExecutionPolicy Bypass -File installers\\install.ps1`.\n\n**Enterprise / non-standard config location.**\nSet `CLAUDE_CONFIG_DIR`, `SKILLFISH_CODE_SETTINGS`, `SKILLFISH_CODE_MCP_CONFIG`,\n`SKILLFISH_DESKTOP_CONFIG`, or `SKILLFISH_HOME` to point at custom paths.\n\n---\n\n## Development\n\n```bash\ngit clone … && cd skillfish-router\nnpm install\nnpm run build        # emit dist/\nnpm test             # unit tests\nnpm run smoke        # cross-platform install/uninstall smoke test\nnpm run audit        # F1–F4 regressions + concurrency/lifecycle (16 scenarios)\nnpm run e2e          # tarball → MCP → daemon → Skills Needed → restore (13 steps)\nnpm run route -- --explain \"make a 30s explainer video\"   # try the router\n```\n\nCI ([`.github/workflows/ci.yml`](./.github/workflows/ci.yml)) runs typecheck,\ntests, smoke, audit, and the end-to-end test on macOS/Windows/Linux × Node\n18/20/22, exercises the real installer scripts on each OS, and validates the\npublished tarball installs and runs from a clean environment.\n\n## Publishing\n\nThe package is a **public scoped** package (`@akbuilds/skillfish-router`,\n`publishConfig.access = \"public\"`). `prepack`/`prepublishOnly` rebuild `dist/`,\nand `files` ships only `dist/ bin/ installers/` + docs (no `src/`, tests, or dev\ndeps).\n\n**Manual publish:**\n\n```bash\nnpm login                       # once, as the akcodes9 npm account\nnpm publish --dry-run           # inspect the tarball (name, files, \"public access\")\nnpm publish --access public     # or --provenance from CI (see below)\n```\n\nThen anyone can install with `npx @akbuilds/skillfish-router install`.\n\n**Automated (recommended) — tag-driven semantic versioning:**\n\n```bash\nnpm version patch               # bumps package.json + commits + tags vX.Y.Z\ngit push --follow-tags\n```\n\n[`.github/workflows/release.yml`](./.github/workflows/release.yml) then guards\nthat the tag matches `package.json`, runs the full 3-OS × Node-18/20/22 matrix\n(incl. e2e), **publishes to npm with provenance** (`npm publish --provenance\n--access public`), and cuts a GitHub Release with per-platform artifacts + a\n`SHA256SUMS.txt` manifest. Requires an `NPM_TOKEN` repo secret; provenance uses\nthe workflow's OIDC identity.\n\n## License\n\nMIT — see [`LICENSE`](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-3421aebe38e9f9763ba5d6ed04df558b"}