Lockkeeper 🔒

The capability router and prompt-injection firewall for AI coding agents.

Lockkeeper indexes every skill, MCP server, plugin, tool, agent, and command installed across your coding agents (Claude Code, Codex, Cursor, Jcode, Hermes, OpenCode, Gemini, Copilot, Windsurf, Cline). It routes any task to a bounded portfolio of the right capabilities and screens everything that crosses your agent's boundary with a built-in injection firewall.

Built and maintained by Himanshu (@Hannay001), with contributions welcome.

Your agent doesn't need all your installed capabilities in context.
It needs the right 8, verified safe, for this task.

_{1 · Route — one query, a bounded portfolio instead of the whole toolbox}

_{2 · Catch — the firewall flags an injection attack; exit codes gate installs and CI}

_{3 · Prove — HMAC-signed receipts show evidence wasn't altered after the scan}

$ lockkeeper route --runtime claude --stdin <<'TASK'
migrate the auth module to the new token API
TASK

status: success
summary: selected 6 complementary capabilities across 4 lanes
[context] mcp: context7
[primary] skill: api-migration
[integration] tool: mcp__context7__query_docs
[execution] tool: exec_command
[verification] agent: code-reviewer
[support] skill: python-patterns
context savings: loaded 6 of 7,540 eligible capabilities (7,534 kept out of context)

Exact entries depend on what you have installed. What lockkeeper guarantees is the structure: complementary lanes, a hard cap on portfolio size, and every entry filtered to what that runtime can actually execute. Every route reports the context savings (how many eligible capabilities it kept out of your prompt); add --savings to also estimate the skill-body tokens avoided.

How it works

flowchart LR
    T["Task"] --> Q["Query builder<br/>(runtime perspective)"]
    Q --> S["Lexical scoring<br/>over one shared index"]
    S --> O["Semantic re-rank<br/>(optional sidecar)"]
    O --> P["Policy pack<br/>deny lists + required lanes"]
    P --> B["Bounded portfolio<br/>max N entries"]
    B --> F["Runtime filter<br/>executable here only"]
    F --> R["Routed bundle"]

One index spans every harness on your machine. Queries refresh stale registries automatically, invalid config fails loudly instead of guessing, and each runtime receives only capabilities it can genuinely execute.

Why

Agent capability directories are exploding:

• Three MCP servers can eat 140k tokens before real work starts.
• Copied skills ship hidden instructions nobody reads.
• Existing tools manage servers; none route tasks across all installed capabilities, and none screen what you install.

Lockkeeper is the missing layer between your task and your toolbox:

See ROADMAP.md and docs/ARCHITECTURE.md.

The firewall

Every capability folder, plugin manifest, MCP config, and live tool call can pass through lockkeeper audit: a dependency-free static scanner with verdicts you can gate on.

flowchart LR
    A["Skill folder,<br/>manifest, or hook payload"] --> C{"lockkeeper audit"}
    C -- clean --> G["✅ allow"]
    C -- suspect --> W["⚠️ warn"]
    C -- hostile --> X["⛔ block · exit 2"]
    C -.-> Rc["HMAC-SHA256<br/>signed receipt"]

It detects instruction-override phrasing, exfiltration pipelines (secrets → curl/wget/nc), credential-store access, obfuscated execution (base64 -d | sh), destructive commands, hidden directive comments, and invisible or homoglyph Unicode. Executable payloads (.pyc, .so, .dll, .wasm) inside an audited directory can't be text-scanned, so they're hashed and floored to at least suspect: a skill that ships bytecode never audits clean.

Verdicts map to CI-friendly exit codes (clean / suspect / hostile → 0 / 1 / 2 under --strict). Every JSON finding carries a SkillTrustBench taxonomy tag (T01–T09) so results stay comparable across skill-security tooling. With --check-deps, pinned dependencies are checked against osv.dev; with --llm-scan (opt-in twice: flag plus environment variables), an OpenAI-compatible endpoint adds a second-pass review that the offline scanner never depends on.

Verifiable evidence

lockkeeper audit ~/skills/some-skill --recursive --strict \
  --receipt-out receipt.json --receipt-key key.hex
# later, prove nothing was altered:
lockkeeper audit --verify-receipt receipt.json --receipt-key key.hex   # exit 0 valid, 1 tampered

Receipts bind to the requested targets and the paths actually scanned, so they're evidence, not decoration. Useful as CI artifacts and audit trails.

Watching live tool calls

Beyond static files, register the firewall as a Claude Code hook and hostile tool calls are blocked before execution:

{
  "hooks": {
    "PreToolUse": [{ "command": "lockkeeper hook", "timeout": 5000 }]
  }
}

Works with any harness that supports stdin JSON hooks (Claude Code, Codex, ...).

Install

Way 1 — no terminal skills required (one paste)

Copy the prompt in PROMPT.md and paste it into any AI coding agent you already have. It installs Lockkeeper, binds it to every harness it finds on your machine, builds the index, and reports back in plain language.

Way 2 — terminal, zero manual wiring

git clone https://github.com/Hannay001/lockkeeper.git
cd lockkeeper
./install.sh        # symlinks `lockkeeper`, then auto-detects and binds every harness on this machine
lockkeeper snapshot-runtimes
lockkeeper rebuild
lockkeeper doctor          # shows each bound harness and its skill count

The installer scans for Claude Code, Codex, Cursor, Jcode, Hermes, OpenCode, Gemini, Copilot, Windsurf, Cline, plus anything unknown that looks like an agent harness under your home directory. Bindings land in config/local.toml (git-ignored, machine-local).

CAP_RUNTIMES=claude,codex ./install.sh   # bind only these two
CAP_NO_INIT=1 ./install.sh               # install without auto-binding

Way 3 — pip install (wheel)

pip install git+https://github.com/Hannay001/lockkeeper.git
lockkeeper doctor   # entry points: lockkeeper, lockkeeper-audit, lockkeeper-hook

This installs the CLI from the packaged wheel (CI builds and functionally smokes it on every push, including Windows). Harness auto-binding still uses install.sh or lockkeeper init.

Route and audit in 30 seconds

# Route a task from any bound harness's perspective
lockkeeper route --runtime claude --stdin --max 8 <<'CAPABILITY_QUERY'
audit our payment webhook for race conditions
CAPABILITY_QUERY

# Audit any skill folder before installing it
lockkeeper audit ~/Downloads/some-skill --recursive --strict

Configuration

Structural paths come from config/default.toml; add per-project overlays as config/<name>.toml and select them with --project <name>. Project-specific routing policy lives in declarative policy packs: see policies/example.json.

lockkeeper snapshot-runtimes and lockkeeper rebuild write runtime inventory to a machine-local state dir (~/.local/state/cap/), never into your clone. The copies under data/snapshots/ are read-only seeds used before the first snapshot run, so git status stays clean after normal use.

The optional semantic sidecar (embedder/) adds embedding re-ranking on top of lexical scoring; everything works without it.

Development

HOME="$(mktemp -d)" python3.11 -m unittest discover -s tests -p "test_*.py" -t .
ruff check .
python3 scripts/cap_audit.py            # self-audit

Requirements: Python 3.11+, no third-party dependencies in the core path. macOS and Linux are first-class today; Windows works under WSL, native support is on the roadmap.

Security

Found a bypass or vulnerability? Please report privately per SECURITY.md rather than opening a public issue.

License

MIT — see LICENSE.