The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Lockkeeper listing page.
Give Claude Code, Codex, Cursor and other AI agents the few skills, MCP servers and tools that fit each task, instead of all of them.
Smaller context window, better tool choices, and no unvetted skill instructions reaching your agent.
Quickstart · Ways to use it · Benchmark · Firewall · FAQ · Docs
AI coding agents get better with skills (SKILL.md files), MCP servers, plugins and tools. But every one you install adds to what the agent has to read and choose from. With hundreds installed, your context window fills up before work starts, and the agent often picks the wrong skill or none at all.
Lockkeeper is a local skill router. It indexes everything installed across all your agents, and for each task it hands the agent a small, complementary set, up to 10 capabilities by default (you choose the size), with the exact file to read for each. Before anything reaches your agent, its built-in firewall can check skills and live tool calls for prompt injection.
1. Install from PyPI (Python 3.11+, macOS, Linux and Windows):
Only want the router skill? npx skills add Hannay001/lockkeeper installs it for any agent (it needs the lockkeeper command too). Prefer not to use a terminal? Paste the prompt in PROMPT.md into the AI agent you already use; it installs and configures Lockkeeper for you. Working from source? git clone https://github.com/Hannay001/lockkeeper.git && cd lockkeeper && ./install.sh
2. Index what you have installed:
3. Route a task:
Then pick how your agent should use it, below.
Install the Claude Code plugin (after pipx install lockkeeper). Inside Claude Code:
It adds the routing hook, the MCP server and the router skill in one step. Prefer settings files? lockkeeper hooks install claude adds just the hook (use one or the other, not both).
Every prompt you send now reaches Claude Code with a short note naming the installed skills that fit it and the exact files to read. Slash commands and short replies like "thanks" pass through untouched, and the hook never blocks a prompt. Undo with lockkeeper hooks remove claude.
Then shrink the list Claude Code loads into every session:
Claude Code puts the name and description of every skill in ~/.claude/skills into each session. Library mode moves them to a folder Lockkeeper indexes but Claude Code doesn't load, so only the skills a prompt needs reach the context. Keep favorites where they are with --keep NAME.
lockkeeper mcp gives your agent three tools, route, search and audit, and keeps the index loaded between calls so answers are fast.
The JSON form works for Cursor (~/.cursor/mcp.json), Windsurf, Cline and most other clients. Lockkeeper is also listed in the official MCP Registry (MCP Registry name: mcp-name: io.github.Hannay001/lockkeeper).
| Agent | Skills and tools indexed | How the agent gets its routes |
|---|---|---|
| Claude Code | ✓ | Automatically on every prompt (hooks install claude), or MCP |
| OpenAI Codex CLI | ✓ | MCP (lockkeeper mcp) or CLI |
| Cursor, Windsurf, Cline | ✓ | MCP |
| GitHub Copilot, Gemini CLI, OpenCode | ✓ | MCP |
| Jcode, Hermes | ✓ | MCP or CLI |
Lockkeeper reads the formats you already use: SKILL.md Agent Skills, agents and commands in Markdown, plugin manifests, and MCP server configs. The installer also detects agent tools it doesn't know by name.
Routing claims should be measurable. Lockkeeper is tested against SkillRouter Eval Core, the public benchmark from the SkillRouter paper (arXiv:2603.22455): 75 real agent tasks with known correct skills, hidden among real SKILL.md files from public repositories, including 780 deliberately misleading look-alikes.
| Before this release | Lockkeeper today | |
|---|---|---|
| Correct skill ranked first, 26,000 skills | 34.7% | 65.3% |
| Correct skill ranked first, 79,141 skills | 25.3% | 54.7% |
| Needed skills included in the routed set (79k) | 20.6% | 52.1% |
| Time to route a ~180-word task, 26k skills | 6.5 s | 0.7 s |
On the full pool, Lockkeeper's standard-library ranker scores between the paper's general-purpose embedding models (Qwen3-Embedding-0.6B at 53.3%, Gemini embedding at 56.0%) and roughly double its BM25 keyword baseline (28.0%), without loading a model. Methods, per-change results and caveats: docs/BENCHMARK.md.
Reproduce it yourself (downloads the ~400 MB dataset once):
Your prompt stays flat as your library grows. On the 79,141-skill benchmark pool (about 157M tokens of skill text), six everyday tasks each routed to 10 capabilities: a median of about 16,000 tokens even if the agent reads every one, over 99.98% kept out of context. The 26,000-skill pool gave about the same (17,600). Reproduce with python3 scripts/bench_context_savings.py.
Skills and plugins are instructions your agent follows. Lockkeeper's scanner finds text that tries to override the agent, commands that send secrets or files to the network, credential-store access, code that decodes and runs hidden payloads, destructive commands, and invisible Unicode, across Markdown, configs and scripts.
clean, suspect, hostile with exit codes 0, 1, 2.Full details: docs/FIREWALL.md.
| Routes each task | Skills, MCP, plugins and tools, across agents | Uses what a skill's body says | Injection firewall | Needs a model or GPU | |
|---|---|---|---|---|---|
| Loading every skill into context | ✗ | – | ✓, at a huge token cost | ✗ | no |
| Built-in skill lists (name and description only) | agent guesses | one agent | ✗ | ✗ | no |
| Learned skill routers (e.g. SkillRouter, 1.2B parameters) | ✓ | skills only | ✓ | ✗ | yes |
| MCP server managers | ✗ | MCP only | – | ✗ | no |
| Skill security scanners | ✗ | ✗ | ✓ | ✓ | some |
| Lockkeeper | ✓ | ✓ | ✓ | ✓ | no |
Run lockkeeper hooks install claude, then lockkeeper library move --apply. The first makes each prompt arrive with the few skills that fit it; the second moves your skills out of ~/.claude/skills into a library Lockkeeper indexes but Claude Code doesn't load, so their descriptions stop filling every session. lockkeeper library move without --apply shows the plan first, --keep NAME leaves favorites in place, and lockkeeper library restore --apply undoes it.
Both ways. It indexes the MCP servers and tools your agents have configured and routes to them, and it is itself an MCP server (lockkeeper mcp) that Codex, Cursor, Windsurf, Cline and other clients can call.
Run lockkeeper audit path/to/skill --recursive --strict. A hostile verdict (exit code 2) means don't install it. See docs/FIREWALL.md.
No. Routing, indexing and auditing run locally. The only network features are opt-in: the osv.dev dependency check, the LLM scan, remote decision providers, and the optional embedding sidecar, which downloads its model once.
Only if you say yes. lockkeeper init and lockkeeper hooks install ask once, in your terminal (never in scripts or CI), and lockkeeper telemetry on|off changes your answer at any time. It shares anonymous daily counts (which commands ran and how fast), never prompts, skill names or file paths, and DO_NOT_TRACK=1 always turns it off. See docs/TELEMETRY.md.
Yes, for you and your company, including at work and on commercial projects: use it, change it and share it. What the Functional Source License (FSL-1.1-ALv2) doesn't allow is offering Lockkeeper, or a product built from it, to others as a commercial product or service that competes with it. Each release becomes Apache 2.0 two years after it ships, and versions up to 1.2.0 remain under the MIT license.
No. The core uses only the Python standard library. Embeddings and decision models are optional add-ons.
It's tested with up to 79,141 skills. At typical sizes (hundreds to a few thousand) routing and re-indexing take well under a second to a few seconds.
Measure it: scripts/bench_routing.py runs the public benchmark, and scripts/eval_decision.py evaluates labeled tasks from your own history.
| Guide | What's in it |
|---|---|
| Configuration | All commands, projects and policy packs, freshness, long prompts, hooks, MCP, optional models |
| Firewall | What the scanner detects, verdicts, receipts, live hooks |
| Benchmark | Methods, full results, comparison with published routers, caveats |
| Telemetry | Exactly what opt-in telemetry collects, and how to turn it off |
| Architecture | How the index, router and firewall fit together |
| Roadmap | What's shipped and what's next |
Issues, ideas and pull requests are welcome. To run the tests:
By submitting a pull request, you agree to license your contribution under the project's license.
Found a security issue or a way past the firewall? Please report it privately per SECURITY.md.
Built and maintained by Himanshu (@Hannay001) · Functional Source License (FSL-1.1-ALv2)
If Lockkeeper saves you context or catches something nasty, a ⭐ helps other developers find it.