Claude Code Local Reader

Claude in the cloud. Eyes on the ground.

claude-code-local-reader keeps Claude Code as the main coding agent while delegating read-heavy work to a local LLM served by LM Studio.

The boundary is strict:

• Claude Code cloud model = planner, editor, debugger, reviewer, final judge
• Local LLM = read-only reader for docs, logs, diffs, grep output, and API extraction

This is not a setup for replacing Claude Code's main model with a local model. Do not use ANTHROPIC_BASE_URL or ANTHROPIC_AUTH_TOKEN for this workflow. Those variables belong to a different setup and would change who the main agent is.

Why this exists

Claude Code is strong at planning, editing, debugging, and final judgment. Large logs, long docs, big diffs, and noisy search output are a different problem: they are mostly reading and compression work.

This repo gives Claude Code a local helper for that read-only work:

Claude Code cloud model
        |
        | shell command
        v
qdoc / qlog / qdiff / qgrep / qapi / ask-local
        |
        | OpenAI-compatible localhost API
        v
LM Studio local model

The local model summarizes or extracts context. Claude Code still inspects the important original files and makes the real decisions.

Quickstart

1. Install the Python dependency from requirements.txt:

python -m pip install -r requirements.txt

This installs the required OpenAI client version:

openai>=2.0.0

If you manage dependencies another way, make sure your environment includes openai>=2.0.0.

2. In LM Studio, load a chat-capable model and start the local server.

3. Set environment variables:

export PATH="$HOME/.local/bin:$PATH"
export LMSTUDIO_BASE_URL="http://127.0.0.1:1234/v1"
export LMSTUDIO_MODEL="<your-model-id>"

4. Run the installer:

./install.sh

5. Run the post-install test suite:

./tests/post-install.sh

6. Smoke-test the installed command manually if you want a quick spot check:

ask-local --question "Reply with exactly: local reader online" --max-tokens 512
qdoc README.md docs/design.md

For source-tree developer testing before installation:

scripts/ask-local --question "Reply with exactly: local reader online" --max-tokens 512
qapi scripts/ask-local

Post-Install Test Suite

After installation, run:

./tests/post-install.sh

It expects LM Studio to be running and LMSTUDIO_MODEL to be set to a real model id.

What it checks:

• installed commands exist in ~/.local/bin
• installed commands are on your PATH
• Python can import openai
• LM Studio is reachable
• ask-local can answer a simple connectivity prompt
• qdoc, qapi, qlog, and qgrep return non-empty output
• qdiff handles both no-change and changed working-tree cases in a temporary git repo
• optional Claude instruction and slash-command installs if you chose those options

The suite uses the installed commands by default, so it catches PATH or install problems that source-tree-only checks would miss.

If the install completed but commands still seem broken, run ./tests/post-install.sh before debugging by hand.

LM Studio Setup

1. Open LM Studio.
2. Load the model you want to use as the local reader.
3. Start the OpenAI-compatible local server.
4. Confirm the model id:

curl http://127.0.0.1:1234/v1/models

5. Export that id:

export LMSTUDIO_MODEL="<your-model-id>"

The default base URL used by this repo is http://127.0.0.1:1234/v1.

Scripts

Script	Purpose
ask-local	General local reader. Reads files from --paths, stdin when present, or an empty placeholder for simple connectivity tests.
qdoc	Summarize docs, READMEs, notes, and walkthroughs.
qlog	Summarize logs from stdin and identify the first likely failure.
qdiff	Summarize git diff against a base branch, default main.
qgrep	Compress grep or ripgrep output from stdin.
qapi	Extract public API contracts and conventions from source files.

Examples:

qdoc README.md docs/*.md
tail -n 200 build.log | qlog
qdiff main
rg "LMSTUDIO_" . | qgrep
qapi scripts/ask-local
ask-local --mode general --paths README.md docs/design.md --question "What should Claude Code know before editing this repo?"

Slash Command Installation

The repo includes:

• claude/CLAUDE.md
• claude/commands/local/read.md

./install.sh can:

• append the local-reader guidance to ~/.claude/CLAUDE.md
• append the same guidance to ./CLAUDE.md
• install /local:read globally at ~/.claude/commands/local/read.md

The installer appends marked blocks instead of overwriting unrelated user content.

Troubleshooting

Common issues:

• ask-local fails immediately: install openai for the same python on your PATH.
• LM Studio is not reachable: confirm the server is running at LMSTUDIO_BASE_URL.
• The model id is wrong: inspect /v1/models and set LMSTUDIO_MODEL again.
• qdoc or qapi returns too little context: pass fewer files or inspect the originals directly after the summary.
• /local:read does not appear: restart Claude Code after installing the command.

See docs/troubleshooting.md for the full guide.

Security and Public Sharing

This repo is designed to be easy to share publicly:

• No secrets are required in the repo.
• The intended endpoint is localhost LM Studio.
• The local model is read-only in this workflow.
• The repo uses <your-model-id> as the public placeholder.

Still, anything you pass to the local server is visible to that local model. Avoid feeding secrets, proprietary code, or sensitive logs unless you trust the machine and model. See docs/security.md.

Docs

• docs/walkthrough.md
• docs/design.md
• docs/troubleshooting.md
• docs/security.md
• examples/example-usage.md

License

MIT. See LICENSE.