readscout

Local models read your files for your coding agent. When Claude Code or Codex needs facts from big files, a long log or a whole folder, it asks readscout instead of reading everything itself. A small model on your own GPU reads the files and answers in a few lines, and every claim comes with a quote that readscout checked word for word in the source, with its real file:line. The quote and the line are proven; the sentence next to them is still the model's reading, so your agent opens the cited lines before any decision. Your agent keeps its context window (and your usage quota) for the real thinking. Nothing ever leaves your machine.

Version française

> local_ask(["app.js"], "Which POST routes are registered WITHOUT passportConfig.isAuthenticated?")

[local_ask · gemma4:26b · 1 chunk(s), 21 KB read locally, 23 s · 18 verified quote(s), 0 dropped (quote not found in source) · quotes are verified, sentences are the model's]
- app.js:253 : The POST route '/login' is registered without passportConfig.isAuthenticated. « app.post('/login', loginLimiter, userController.postLogin); »
- app.js:256 : The POST route '/login/2fa' is registered without passportConfig.isAuthenticated. « app.post('/login/2fa', login2FALimiter, userController.postTwoFactor); »
- app.js:269 : The POST route '/signup' is registered without passportConfig.isAuthenticated. « app.post('/signup', userController.postSignup); »
...

That is a real run on hackathon-starter's 101-route app.js: 21 KB stayed out of the agent's context, 18 of the 19 matching routes came back, none wrong, every line number real. The question contains "WITHOUT", so readscout picked the bigger model by itself.

Contents

• What it does · Why · Requirements

• Install: one-line installer · Claude Code plugin · manual

• First steps · Everyday use · Commands · Models · Faster with llama.cpp

• Troubleshooting · Security and privacy · Limits · Uninstall

Related MCP server: gus

What it does

readscout is an MCP server with three tools, plus a skill that tells your agent when to use them:

How the answers stay trustworthy:

• the model's output is constrained by a JSON schema, so it always parses;

• any finding whose quote is not found in the source is dropped; line numbers are computed by readscout, never by the model;

• large inputs are split into chunks instead of being refused; logs are pre-filtered (errors with context, start, end, no duplicates);

• negative questions ("without", "not", "missing") go to the bigger model automatically, because small models get them wrong;

• an edit is kept only if your tests pass;

• models free your RAM and VRAM by themselves, whichever engine runs them (Ollama, or llama.cpp's llama-server, which readscout starts and stops itself): they unload one minute after the last call, and as soon as the agent session ends. Nothing to stop by hand (readscout stop frees memory at once).

Why

Every turn of an agent session re-sends the whole conversation, so each big file or log your agent reads keeps costing tokens until the session ends. Most of that reading is mechanical: finding where something is, listing what matches a pattern, spotting the error in a log. A small local model does that well if it must prove what it says.

Earlier "delegate to a local model" setups (including the one this project replaces) failed for measurable reasons: they delegated judgement (code review, fact checking), refused large inputs, and cost the agent more tokens to drive than doing the task itself. readscout delegates reading only, adapts to any input size, and returns a short receipt. The story and the numbers: docs/DESIGN.md and docs/BENCHMARK.md.

Requirements

• Windows, macOS or Linux.

• A coding agent: Claude Code and/or Codex.

• Ollama to run the models (the installer can install it for you).

• Hardware: a GPU with 6 GB of memory or more is recommended (NVIDIA, AMD, or Apple silicon), and 16 GB of RAM. With 8 GB of VRAM and 32 GB of RAM you get the best measured setup. It also runs on CPU only, slowly.

• Disk: 7 to 25 GB for the models, depending on your machine.

• Optional, only to read big inputs faster with the 26B model: llama.cpp (llama-server; the installer does not install it, see Faster with llama.cpp). It reuses the model files Ollama already downloaded. On an NVIDIA GPU take a CUDA build (about 150 MB, plus about 400 MB of CUDA runtime on Windows): CUDA 13 builds need NVIDIA driver 580 or newer (nvidia-smi shows yours), take a CUDA 12 build for an older driver (NVIDIA's compatibility table). The Vulkan build that winget install llama.cpp installs ran slower than Ollama on an NVIDIA card. AMD (ROCm or Vulkan build) and Apple silicon (Metal build) have not been measured: compare with readscout bench.

Installation

Pick one option. A sets up everything for Claude Code and Codex. B is the quickest way if you only use Claude Code. C is the same as A, done by hand.

Option A: one-line installer (recommended)

Windows (PowerShell):

irm https://raw.githubusercontent.com/Anarchiejs/readscout/main/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Anarchiejs/readscout/main/install.sh | sh

The installer asks before installing anything:

1. uv, a Python manager from Astral (it brings its own Python; you need nothing else);

2. Ollama, if it is missing (winget on Windows, Homebrew on macOS, the official script on Linux);

3. readscout itself;

4. then it opens the setup page in your browser (http://127.0.0.1:8765/setup):

   • Your machine: GPU memory and RAM are detected and pre-filled; adjust the sliders (VRAM 6-24 GB, RAM 16-64 GB) if needed;

   • Models: the models recommended for that machine, each with an Install button (one click, with a progress bar), then Use these models;

   • Coding agents: Connect Claude Code and/or Codex (registers the MCP server and copies the skill);

   • Check: everything should be green.

Restart Claude Code / Codex, and continue with First steps.

Option B: Claude Code plugin

For Claude Code only. You need uv and Ollama installed first. In Claude Code, run:

/plugin marketplace add Anarchiejs/readscout
/plugin install readscout@readscout

The plugin brings the skill and the MCP server (started with uvx, nothing else to install). Then, in a terminal, download the models:

uvx --from https://github.com/Anarchiejs/readscout/releases/download/v0.1.6/readscout-0.1.6-py3-none-any.whl readscout setup

That opens the same setup page as option A: install the models there (skip "Coding agents": the plugin already did it). Restart Claude Code.

Tip: to have a short readscout command for later, install it once with uv tool install https://github.com/Anarchiejs/readscout/releases/download/v0.1.6/readscout-0.1.6-py3-none-any.whl.

Option C: manual install

# 1. Ollama: https://ollama.com/download (then make sure it is running)
# 2. uv:     https://docs.astral.sh/uv/getting-started/installation/
# 3. readscout
uv tool install https://github.com/Anarchiejs/readscout/releases/download/v0.1.6/readscout-0.1.6-py3-none-any.whl

# 4. models recommended for your machine (see `readscout hardware` first if you are curious)
readscout pull

# 5. connect your agent(s)
readscout install-agent claude
readscout install-agent codex

# 6. check
readscout doctor

Restart Claude Code / Codex.

First steps

1. Check the setup: readscout doctor must end with All good. (plugin users: use the uvx ... readscout form above).

2. Open any project in Claude Code or Codex.

3. Ask something that needs a lot of reading, in your own words. For example:

   • "Which API routes in src/routes don't check authentication?"

   • "Where is the session expiry handled in this repo?"

   • "Summarize what the lib/ folder does."

   • "Run the tests and tell me why they fail" (the agent saves the output to a file and digests it).

4. Watch the agent call local_ask or local_digest and get a short receipt instead of opening every file. The first call loads the model into memory (10-30 s); later calls are faster.

5. See what it saved: readscout stats, or readscout dashboard for the usage page.

You can also call the tools from a terminal, without any agent, to see what they return:

cd /path/to/my-app
readscout ask src -q "Which functions read environment variables?"
readscout digest build.log

Everyday use

You keep working as usual: the skill tells the agent when to delegate. It uses readscout for:

• facts spread over files it has not read yet (more than a few hundred lines in total);

• understanding a module or folder without reading it;

• long logs, test or build output;

• small, fully specified mechanical edits (docstrings, type hints, renames, a new parameter, test scaffolding), always with your tests as the gate.

It keeps for itself: anything a quick grep answers, short files it reads anyway, and every judgement (code review, "is there a bug", architecture, real-world facts).

Things you may see in a receipt:

• retried with quality model: the fast model found nothing quotable, the bigger one was used;

• quality model ... not installed, used ...: install it with readscout pull <model> for better answers;

• The list may be incomplete: the agent should narrow the question or add a grep;

Commands

readscout setup                        open the setup page
readscout doctor                       check that everything is installed and wired
readscout hardware                     detected GPU/RAM and recommended models
readscout pull [MODEL ...]             download models (default: the recommended ones)
readscout install-agent claude|codex   register the MCP server and the skill (uninstall-agent to undo)
readscout ask PATH... -q QUESTION      run local_ask from the terminal (--summary, --quality)
readscout digest PATH                  run local_digest from the terminal
readscout edit PATH... -i TEXT --gate "CMD"   run local_edit from the terminal
readscout folders [add|remove DIR...]  limit the local models to these folders (no list: any folder)
readscout gate on|off                  allow or forbid local_edit's gate commands
readscout engine [ollama|llamacpp]     which engine runs each model (see "Faster with llama.cpp")
readscout stats                        what was read locally instead of by your agent
readscout dashboard                    usage page
readscout stop                         unload every model now, on both engines (they also unload by themselves)
readscout bench                        measure your models on the public benchmark

Settings and usage data live in your user folder, never in the package: %APPDATA%\readscout on Windows, ~/Library/Application Support/readscout on macOS, ~/.config/readscout on Linux (config.json, metrics.jsonl, and with llama.cpp llamacpp.json, llama-server.log).

Models

Chosen per machine from catalog.json, measured with the public benchmark:

The context size follows the machine too: 32k tokens by default, 64k for the fast model from 12 GB of VRAM, and for the quality model from 24 GB (26B) or 14 GB (12B). A bigger context means fewer chunks on big files; it has not been benchmarked yet, and you can change it in config.json (models.<tier>.ctx).

On an RTX 4060 Ti 8 GB + 32 GB RAM (docs/BENCHMARK.md): gemma4:12b and gemma4:26b score 0.94 and 0.93 on 25 reading tasks from four pinned open-source repositories (about 24 and 23 s per task), gemma4:e4b 0.83 with 7/7 edits (about 6 s). Negative questions are where the small models fail (gemma4:e4b 0.28, gemma4:e2b 0.12, the bigger ones 0.88), which is why readscout sends them to the quality model. Measure your own machine with readscout bench and share the table in an issue.

Faster with llama.cpp (optional)

Ollama is the default engine and stays the best choice on most machines. llama.cpp reads big prompts about twice as fast with a mixture-of-experts quality model, but writes more slowly. Measured on an RTX 4060 Ti 8 GB + 32 GB RAM (Ollama 0.40.3, llama.cpp b11636 CUDA, the same GGUF files, Gemma 4, full results):

So llama.cpp pays off for one thing: reading new big inputs with the 26B (here 1.4x faster overall, 2x on the prompt alone). It loses when the same files are asked about again (Ollama keeps the start of the prompt in cache and writes faster), and it is slower for the fast and the 12B models. That is why each model can run on its own engine. The Vulkan build that winget install llama.cpp installs was slower than Ollama on an NVIDIA card: with NVIDIA, take the CUDA build from the releases (llama-bXXXX-bin-win-cuda-13.x-x64.zip plus the matching cudart-...zip; see Requirements for the driver). On a machine with an integrated GPU too, add --args "--device CUDA0" (or Vulkan0) so the model is not split onto it; readscout doctor shows the device ids.

readscout engine llamacpp --quality ollama:gemma4:26b --binary path/to/llama-server --args "--n-cpu-moe 30"
readscout engine                                         # fast: ollama gemma4:e4b, quality: llamacpp ...
readscout doctor
readscout bench --models gemma4:26b,llamacpp:quality     # compare both engines on your machine

Only the models you name move to llama.cpp: above, the fast model stays on Ollama (--fast ollama:gemma4:e4b would move it too, --quality ollama moves the quality model back). ollama:<model> reuses the file Ollama already downloaded (nothing to download again); a .gguf path works too. readscout then starts llama-server itself on a free loopback port (flash attention, 8-bit KV cache, 2048 micro-batch, Ollama's repeat penalty), keeps a single model loaded, shared by all your agent sessions, and stops it after the same idle delay as Ollama (one minute) or when the session ends; readscout stop stops it at once. On an 8 GB card the two engines cannot both hold a model, so they take turns: before llama.cpp loads a model, readscout unloads Ollama's, and before an Ollama call it stops its idle llama-server (never one in the middle of another session's request; switching costs a model load, a few seconds from RAM). Extra flags go in --args, for all models, or in config.json under llamacpp.models.<tier>.args for one (the 26B above used ["--n-cpu-moe", "30"]). Already running your own llama-server? Give its address instead: --fast http://127.0.0.1:8080 (readscout then never starts or stops it). Every model back on Ollama: readscout engine ollama (your llama.cpp models are kept: readscout engine llamacpp brings them back). Restart your agent after switching.

Troubleshooting

Security and privacy

• Models run on 127.0.0.1 only; any other endpoint is refused in code, and so are Ollama cloud models (by name and when Ollama reports them as served by a remote host). readscout never calls an online model, even as a fallback. If you use Ollama itself with cloud features, that is outside readscout; the Ollama settings it offers also switch them off (OLLAMA_NO_CLOUD=1). With the optional llama.cpp engine, readscout starts llama-server itself, bound to 127.0.0.1 on a free port with a random secret key (so a web page cannot query it), only for the .gguf files you configured; a server you run yourself must be on 127.0.0.1 too.

• The model has no tools: it reads the text readscout gives it and returns JSON. Only readscout reads files: the ones your agent names, by default in any folder (nothing to register). .env*, .git, keys, credential files and binaries are always refused whatever the letter case; common secrets (provider keys and tokens, JWTs, passwords in URLs, Authorization headers, password/secret/token assignments, also in JSON) are masked before reaching the model, and local_edit refuses files that contain one. Masking is pattern based: it cannot catch every secret, so keep real credentials out of your projects.

• If you restrict your agent (no Bash, Read limited to some folders in Claude Code's permissions), readscout does not see those rules: it reads what the agent names and runs its gate commands. To keep the same limits, use readscout folders add <folder> (the local models then only read and write inside the listed folders; readscout folders shows the list, readscout folders remove <folder> drops one) and readscout gate off (local_edit then refuses any gate command). readscout doctor shows both settings.

• File contents and model answers are treated as data, never as instructions. Model-written text is flattened to short single lines in the receipts, but it stays unverified: the agent checks the cited lines before deciding.

• local_edit writes atomically, never overwrites a file that changed while the model was working, and restores only what it wrote. Its gate commands are run as you, without a shell, in the project folder: they are chosen by the calling agent, exactly like the tests it would run itself.

• Stored locally, in your user folder: config.json and metrics.jsonl (tool, model, sizes, timings and counts; never file contents, questions or answers), and with llama.cpp llamacpp.json (the running server's process, port and last use) and llama-server.log (model loading messages and timings; no file contents). Nothing is sent anywhere. Agent installers back up ~/.codex/config.toml once (config.toml.readscout-bak) and only touch the mcp_servers.readscout entry.

• The setup page listens on 127.0.0.1, checks Host and Origin, and requires a per-session token for every change. The "Recommended Ollama settings" button saves permanent user environment variables on Windows after asking.

• Installers ask before installing uv or Ollama (and install nothing when no terminal is available unless you set READSCOUT_YES=1). Each release publishes SHA256SUMS for the wheel, the sdist and the installers.

Details and reporting: SECURITY.md.

Limits

• Small models are good readers and poor authorities: do not delegate code review, bug hunting or fact checking.

• A verified quote proves the line exists, not that the model understood it; the agent opens the cited lines before any decision (the skill says so).

• Lists can be incomplete (the receipt says so when a cap was hit); when completeness matters, add a targeted grep.

• Lines longer than 4000 characters (minified files) are cut and the receipt says so; only the start was read.

• A quote may differ from the source by whitespace and by line breaks between adjacent lines, nothing else.

• Tests run without Ollama or a GPU (a fake model); real-model checks (scripts/e2e.sh, scripts/e2e.ps1) are run by hand before a release and are not part of CI.

Uninstall

readscout uninstall-agent claude      # or: /plugin uninstall readscout@readscout
readscout uninstall-agent codex
uv tool uninstall readscout

Models stay in Ollama (ollama rm gemma4:26b); settings stay in the user folder listed under Commands.

Contributing

Benchmark reports from other GPUs, bug reports and pull requests are welcome: see CONTRIBUTING.md. Roadmap: more model families in the catalog, GGUF downloads for the llama.cpp engine from the setup page, more benchmark tasks.

License

MIT