promptscout

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

1. You run promptscout "check the auth module, there might be a token refresh bug"
2. The local LLM sees your prompt along with the project file tree (git ls-files) and decides which search tools to call
3. The LLM outputs tool calls directly as JSON (e.g. file_finder("auth"), section_finder("token"), git_history("refresh"))
4. Each tool runs against your codebase using ripgrep and git
5. The output is your original prompt unchanged, followed by the discovered context
6. 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