LLMScribe

---

LLMScribe

Turn any code repository into clean, structured, deterministic data.

No AI. No embeddings. No hidden ranking.

Apache-2.0, and it runs entirely on your machine — no network, no account.

---

The problem

Your agent does not have an intelligence problem. It has a retrieval problem.

On a 1.4-million-line codebase, one benchmark agent burned 6,000 seconds and produced nothing — no analysis, no output, zero score.

The same model, given structured code search instead of free-form file reading, finished the same task in 89 seconds and scored 0.90.

Across another benchmark, Codex CLI completed its entire turn sequence without ever reaching the file that would have solved the task in 27–29% of runs.

Handed the right context up front, its score nearly doubled.

The bottleneck is not the model. It is what goes into the context window.

What users keep reporting:

• The agent explores 200 files to change one line, and admits it is "looking at unnecessary files"
• Nine searches and fourteen files to find one constant, because the search itself is not ranked
• The same files re-read in a loop, with no reasoning between the reads
• Stale fixtures, mock data and outdated comments read as current truth
• Search reporting "no matches found" when a plain grep finds the text immediately
• Truncation that hides itself, and build output filling the window with noise

What LLMScribe does about it

The file an agent needs next is usually the one *structurally* related to the file it is already looking at — a dependent, a sibling module, a test fixture. That is a graph question, not a similarity question, which is why LLMScribe ships dependency analysis and a real tree instead of embeddings.

---

Feature Overview

Core Tools

More

---

Quick Start

Install LLMScribe from PyPI:

pip install llmscribe

Then point it at any project directory on your machine. No API key, no network access, no account.

The project_map(...), search(...), read(...) snippets below show MCP tool calls. The same operations are available from the CLI (local directories) and from Python through llmscribe.core (see Python API).

Map

Generate a clean directory tree without file contents. This is the best first step when exploring an unfamiliar repository.

project_map()

CLI / MCP

CLI

llmscribe map

llmscribe map --json

MCP

project_map

Output:

src/

├── api/ │ ├── routes.py │ └── auth.py ├── models/ │ └── user.py └── main.py

Search

Search across file paths, file names, file contents, and individual lines.

Search is intentionally deterministic: LLMScribe does not try to guess what you meant.

search(query="authentication")

CLI / MCP

CLI

llmscribe search "authentication"

llmscribe search "authentication" --json

MCP

search

Each match includes the file path, line number, the matching line, the matched text and the match type (filename or content).

Results are ordered by path then line, and limited to 1,000 matches. Binary and oversized files are skipped.

Output (--json, data.matches):

[

{ "file_path": "src/auth/service.py", "line_number": 12, "line_content": "def authenticate(user, password):", "match_type": "content", "matched_text": "authenticate" } ]

Read

Safely retrieve the contents of a specific file. LLMScribe validates paths and prevents path traversal outside the project.

read(file_path="src/auth/service.py")

CLI / MCP

CLI

llmscribe read src/auth/service.py

MCP

read

---

Power Your Agent

Instead of throwing an entire repository into a context window, an agent can progressively retrieve exactly what it needs:

1. project_map()

↓

1. search("authentication") ↓
2. read("src/auth/service.py") ↓
3. project_dependencies("src/auth/service.py") ↓
4. read_many([...])

MCP

LLMScribe is a standard Model Context Protocol server that runs locally over stdio.

Any MCP-compatible client can use it against a project directory on your machine.

Config — put this in your client (see the per-app setup below):

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

Use the Python module instead of the command

If llmscribe-mcp is not on your PATH, point the client at the module:

{

"mcpServers": { "llmscribe": { "command": "python", "args": ["-m", "llmscribe.mcp"] } } }

</details>

Per-app setup

Each client reads a different configuration file. The blocks below were checked against each tool's official documentation.

Claude Desktop

Edit claude_desktop_config.json (in the app: Settings → Developer → Edit Config):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

Fully quit and reopen Claude Desktop after saving.

Claude Code

claude mcp add llmscribe -- llmscribe-mcp

Confirm with claude mcp list.

Add --scope user to make it available in every project, or --scope project to share it with your team via .mcp.json.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

Restart Cursor, then check Customize → MCPs.

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace. Note that VS Code uses servers, not mcpServers:

{

"servers": { "llmscribe": { "type": "stdio", "command": "llmscribe-mcp" } } }

Then open Copilot Chat in Agent mode and click the tools icon to start the server.

Windsurf (Cascade)

Edit ~/.codeium/mcp_config.json (in the app: Windsurf Settings → Cascade → MCP → View Raw Config):

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

Press the refresh button after saving.

Cline

Open the Cline panel → MCP Servers → Configure → Configure MCP Servers, then add:

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

Roo Code

Edit the global mcp_settings.json (Edit Global MCP), or create .roo/mcp.json in your project (Edit Project MCP):

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

LM Studio

In the app: Program tab → Install → Edit mcp.json.

The file is ~/.lmstudio/mcp.json on macOS/Linux, %USERPROFILE%\.lmstudio\mcp.json on Windows:

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

LM Studio follows Cursor's mcp.json notation.

Zed

Add to your Zed settings (in the app: Settings → AI → MCP Servers → Add Server, or zed: open settings file):

{

"context_servers": { "llmscribe": { "command": "llmscribe-mcp", "args": [], "env": {} } } }

Continue

Add to ~/.continue/config.yaml (or a standalone file under .continue/mcpServers/):

name: LLMScribe

version: 1.0.0 schema: v1 mcpServers:

• name: LLMScribe command: llmscribe-mcp

Continue also picks up Cursor/Claude/Cline JSON configs dropped into .continue/mcpServers/.

JetBrains IDEs (IntelliJ, WebStorm, …)

Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → As JSON:

{

"mcpServers": { "llmscribe": { "command": "llmscribe-mcp" } } }

You can also click **Import from