promptscout
A CLI tool that enriches your coding agent prompts with codebase context using a local LLM. No API keys, no cloud. Runs on your machine.
Designed as a Claude Code plugin. It hooks into your prompt submission flow and adds codebase context before Claude sees it.
Motivation
When you ask a coding agent like Claude Code, Cursor, or Copilot to work on your codebase, the agent spends time and tokens discovering which files matter. It greps, reads, explores, all on your dime.
promptscout does that discovery locally, for free. A small local LLM reads your prompt, searches your codebase with ripgrep and git, and appends the results to your original prompt. The paid agent gets a prompt that already contains the relevant file paths, code snippets, and commit history. It can skip straight to the actual work.
Your original prompt is never modified. promptscout only appends context.
How It Works
flowchart LR
A["Raw Prompt"] --> B["Local LLM<br/>(Qwen 3 4B)"]
B -->|"tool calls"| C["ripgrep / git"]
C --> D["Original Prompt<br/>+ Discovered Context"]
subgraph B_ctx[" "]
direction TB
T["Project Tree<br/>(git ls-files)"]
end
T -.->|"context"| B
- You run
promptscout "check the auth module, there might be a token refresh bug"
- The local LLM sees your prompt along with the project file tree (
git ls-files) and decides which search tools to call
- The LLM outputs tool calls directly as JSON (e.g.
file_finder("auth"), section_finder("token"), git_history("refresh"))
- Each tool runs against your codebase using
ripgrep and git
- The output is your original prompt unchanged, followed by the discovered context
- The result is copied to your clipboard, ready to paste into your coding agent
Installation
Prerequisites
- Node.js >= 20
- C++ compiler (Xcode Command Line Tools on macOS,
build-essential on Linux)
- ripgrep (
rg) for fast codebase search
git (for project tree generation and commit history search)- ~3GB disk space for the model
Install
npm install -g promptscout
Or from source:
git clone https://github.com/obsfx/promptscout.git
cd promptscout
pnpm install
pnpm build
pnpm link --global
Setup
Run promptscout setup to create the data directory and download the Qwen 3 4B model (~2.5GB). The model is stored in ~/.promptscout/models/.
Claude Code Plugin
promptscout ships with a Claude Code plugin that enriches every prompt you send. Once installed, it runs in the background. No manual copy-pasting needed.
Install the plugin
# Add the promptscout marketplace
claude /plugin marketplace add obsfx/promptscout
# Install the plugin
claude /plugin install promptscout
Or in Claude Code interactive mode:
/plugin marketplace add obsfx/promptscout
/plugin install promptscout
Once installed, every prompt you submit in Claude Code gets enriched with codebase context via the UserPromptSubmit hook. The plugin passes your prompt through promptscout with --json-output --no-clipboard and injects the result as additional context.
When context is found, the plugin shows a summary notification:
promptscout: enriched context (+5 files) (+3 sections) (+1 definitions)
If promptscout is not installed or fails for any reason, the plugin falls back silently and your original prompt goes through unchanged.
Model
promptscout uses Qwen 3 4B (Q4_K_M quantization) running locally via node-llama-cpp. The model uses GPU acceleration automatically when available (Metal on macOS, CUDA on Linux).
- Size: ~2.5GB (
GGUF Q4_K_M)
- Context: 8192 tokens
- Latency: ~2s per prompt (Metal, Apple Silicon)
- Purpose: Decides which search tools to call based on your prompt and the project file tree. Does not rewrite your text.
Tools
promptscout has 5 built-in search tools. The LLM picks which ones to call and with what keywords:
| Tool | What it does |
|---|
file_finder | Finds files matching a keyword. Results scored by filename relevance. |
section_finder | Finds code lines matching a keyword. Returns file:line:code entries. |
definition_finder | Finds function, class, type, and struct definitions across languages. |
import_tracer | Finds import/require/include statements referencing a module. |
git_history | Finds recent commits that added or removed code matching a keyword. |
All search tools use ripgrep, which respects .gitignore and skips binary files automatically.
Usage