knock

🚪 knock

Stop Claude Code from burning your usage limit on big repos.

On a large codebase, Claude Code spends much of each session searching and reading files, often through a sub-agent, before it answers you. knock gives it a map of the code up front: the functions that matter, their exact line ranges, and who calls what. It runs on your machine and needs no API key.

Same question, 8 runs each, on a 4,776-file repo: median cost $0.42 → $0.25 (−40%). Without knock, Claude spawned a sub-agent in 5 of 8 runs. With knock, in none.

claude mcp add knock -- uvx knock-mcp serve --repo . --toolset map

Full code map for Python and JavaScript/TypeScript; functions and classes for Go, Rust, Java and more.

Two real Claude Code sessions on Saleor , abridged: each side's median-cost run out of three. Results vary between runs and repositories; on a small, well-known repo the difference was within noise. Full numbers: docs/benchmark.md · how it was measured: the write-up .

---

🤔 The problem, in one table

Every new chat with a coding agent starts with amnesia. To answer *"where is X?"* or *"how do we deploy?"* it greps, opens big files, reads them... and next session it does it all over again.

Median characters per task on the held-out benchmark (targeted-grep and grep-and-read baselines vs knock). Fewer characters ≠ an identical cut in your bill; see the FAQ .

⚡ Getting started

You set knock up once, then you just keep using your AI agent as usual. The agent talks to knock in the background; you never have to run knock commands day to day.

1️⃣ Connect it to Claude Code (once per project)

From inside the project you work on:

claude mcp add knock -- uvx knock-mcp serve --repo . --toolset map

This uses uv, which downloads and runs knock for you. No uv? Run pipx install knock-mcp (or pip install knock-mcp), then claude mcp add knock -- knock serve --repo . --toolset map.

--toolset map gives the agent three tools (map, open, remember) and is the setup measured in the results below. Leave it out to get the original eight tools.

That's the whole setup. The next time you open Claude Code in that project, knock reads the project and builds its notes automatically. This takes a few seconds for a small project and a minute or two for about 5,000 files; after that it only re-reads files that changed.

[!TIP]

Add this line to your project's CLAUDE.md so the agent uses knock when it pays off:

*"Before exploring the repo (how/why questions, unclear bugs, changes across modules, code you can't find with one search), call knock's map tool with your task. For small edits you can locate with one grep, skip it. Save non-obvious findings with remember."*

In our recordings, knock saved money on investigations in a large codebase but added a small cost to quick edits, so this line matters.

2️⃣ Work normally

Ask your agent what you'd always ask. Here's what changes behind the scenes:

Nothing to maintain: when code changes, knock updates its notes, and flags anything that may be outdated.

🖥️ Optional: use knock yourself from the terminal

You never *need* these, but they're handy.

Want knock to ignore some files? List them in a .knockignore file (same format as .gitignore).

👥 Setting it up for a whole team

Commit a .mcp.json file to your repo, and every teammate's Claude Code picks up knock automatically (each person needs knock installed):

{

"mcpServers": { "knock": { "command": "knock", "args": ["serve", "--repo", ".", "--toolset", "map"] } } }

Each person's notes live on their own machine. Sharing findings across a team isn't supported yet (see Status below).

🧠 How it works

flowchart LR

A["📁 Your repo code · docs · configs · git log"] -->|"knock index (only changed files)"| B["🗂️ Notes each one points to file + lines + hash"] B --> C[("💾 SQLite on your machine")] C -->|"map"| D["🤖 Your agent"] D -->|"open / Read (verify the real lines)"| A D -->|"remember (save what it learned)"| C

1. Index: knock reads your repo *without running anything in it*. It writes short notes: what each module defines, what the docs say about setup and deployment, which tools and dependencies you use, why decisions were made, and which recent commits fixed bugs.
2. Ask: your agent asks a question and gets a small, ranked answer with file:line pointers, instead of reading whole files.
3. Verify: before editing, the agent reads just the lines it needs. The original files are always the source of truth.
4. Remember: the agent saves what it learned. If those files change later, knock marks the note stale so nobody trusts outdated info.

🧰 What your agent gets

With --toolset map (recommended):

The original 8-tool set (default without --toolset map )

👀 See a real example session (8-tool set, Flask)

On Flask, an agent is told: *"sessions signed with an old key in SECRET_KEY_FALLBACKS are rejected after rotating SECRET_KEY"*.

1. `get_context` returns ~7.7 KB containing:

• src/flask/sessions.py:317: SecureCookieSessionInterface.get_signing_serializer
• tests/test_basic.py:374: test_session_secret_key_fallbacks
• related commits fb54159861 secret key rotation: fix key list ordering and e13373f838 enable secret key rotation
• the docs sections on sessions and secret keys

1. `get_source("src/flask/sessions.py", symbol="get_signing_serializer")` returns the ~80 relevant lines, not the whole file.
2. `record_knowledge` saves the finding:

   {"category": "debugging",

"content": "get_signing_serializer builds the key list as SECRET_KEY_FALLBACKS followed by SECRET_KEY; ordering was fixed in fb54159.", "sources": [{"path": "src/flask/sessions.py", "start_line": 317, "end_line": 335}]}

   The next session gets it instantly. If `sessions.py` changes, the note is flagged **stale**.

📊 Does it actually help?

Measured with a reproducible benchmark: 12 engineering tasks per repo, covering architecture, finding a feature, deployment, bug investigation, design rationale and following conventions.

Held-out repo (full-stack-fastapi-template; knock was never tuned on it):

More numbers, and the fine print

• Flask (used during development, so optimistic): knock 12/12 with 92K chars, baselines 7/12 with 2.1M and 247K chars.
• Speed: a ~200-file repo indexes in 0.3–0.6 s; re-indexing with no changes takes ~30 ms.
• What this measures: whether the facts