Introduction

This manual covers codescout: an MCP server that gives AI coding agents IDE-grade code navigation, optimized for token efficiency.

The Problem

When an AI coding agent tries to understand a codebase with conventional file tools, it faces a mismatch between what the tools produce and what the task actually requires.

Consider a routine task: “find all callers of authenticate_user and check whether they handle the error case.” With standard tools, the agent has a few options:

• grep — returns every line containing the string, including comments, string literals, documentation, and test fixtures. Disambiguation is the agent’s problem.
• cat — dumps the entire file when the agent needs one function. A 1,000- line module floods the context for a 30-line function.
• find — locates files by name, but has no awareness of what is inside them.

None of these tools understand code structure. They operate on bytes and lines, not symbols, definitions, or references. The result is that agents burn most of their context window on navigation overhead: reading full files to find one function, re-reading the same module multiple times from different entry points, asking questions they already answered two tool calls ago.

The downstream effects compound:

• Shallow understanding. When an agent can only see fragments at a time, it builds an incomplete picture and fills gaps with plausible-sounding guesses.
• Hallucinated edits. Functions that do not exist, arguments in the wrong order, return types copied from the wrong overload.
• Constant course-correction. The human has to re-read the agent’s output, identify what it got wrong, and re-explain the structure it missed.

The tools are structurally blind. Every coding agent using only file primitives runs into this wall, regardless of model capability.

The Solution

codescout exposes the same information an IDE uses — symbol definitions, references, call hierarchies, type information, git history — through a standard MCP interface that any agent can call.

It is a Rust binary that runs alongside your coding agent. The agent sends MCP tool calls; codescout delegates to the right backend (LSP server, tree-sitter, git, embedding index) and returns structured, compact results.

Four pillars:

LSP Navigation (5 tools, 9 languages)

• symbols — the outline of a file or directory: classes, functions, structs, in tree form (also performs name-based search)
• references — all callers/usages of a given symbol
• symbol_at — inspect a symbol at a position via LSP: definition location and/or hover (type signature + docs)
• call_graph — transitive caller/callee traversal for impact analysis
• edit_code — mutate code by symbol name with action: replace | insert | remove | rename (consolidates the older replace_symbol, insert_code, remove_symbol, rename_symbol into one tool)

Supported languages: Rust, Python, TypeScript/JavaScript, Go, Java, Kotlin, C/C++, C#, Ruby.

Semantic Search (2 tools)

Sometimes you know the concept but not the name. Semantic search finds code by meaning using embeddings, not keywords.

• semantic_search — “authentication middleware”, “retry with exponential backoff”, “how errors are serialized” — returns ranked code chunks. The optional scope parameter restricts search to project code, a specific library, or all sources.
• index(action: build) — build or incrementally update the embedding index (smart change detection via git diff → mtime → SHA-256 fallback)
• index(action: status) — show index stats: file count, chunk count, embedding model, last update time, and optional per-file drift scores

The embedding backend is configurable: OpenAI, Ollama, or any compatible endpoint.

For git history and diffs, use run_command with shell git commands (e.g. run_command("git log src/auth.rs") or run_command("git diff HEAD")).

Persistent Memory (1 tool)

Agents are stateless across sessions by default. codescout provides a lightweight key-value store backed by markdown files in .codescout/memories/.

• memory — unified dispatch tool: action: "read" / "write" / "list" / "delete" for the file store; "remember" / "recall" / "forget" for natural-language semantic memory

Use this to record decisions, gotchas, and conventions so the agent picks them up on the next session without re-discovery.

Library Navigation (1 tool)

Navigate third-party dependency source code without leaving your agent workflow. Libraries auto-register when LSP symbol_at returns paths outside the project root.

• library(action: list) — see all registered libraries and their status (use index(action: build) with a library scope to build a semantic index for it)

The Rest

Beyond these pillars: 7 file/markdown operation tools (directory listing, file reading, pattern search, file creation, find-and-replace editing, markdown-aware reading and editing), 3 workflow tools (project onboarding, shell commands, write-root approval), and 1 config tool (workspace). With librarian enabled (default), 5 additional artifact tools appear at session start. ~20 tools in the base server, ~25 with librarian.

Token Efficiency by Design

Every tool defaults to the most compact representation that is still useful. Full bodies are available via detail_level: "full". Paginated results use offset and limit. Tools never dump unbounded output.

The design follows two modes:

• Exploring (default) — names and locations, capped at 200 items. Low token cost. Right for orientation.
• Focused — full detail, paginated. Use once you know what you are looking at.

When results overflow the cap, the tool tells you how to narrow the query rather than silently truncating. You get guidance, not garbage.

Who This Manual Is For

This manual is written for three audiences.

Operators

You are setting up codescout for a team or configuring it to work with Claude Code, Cursor, or another MCP-capable agent. You need to understand installation, the MCP configuration format, embedding backend options, and which LSP servers to install for your languages.

Start here: Installation, then Project Configuration.

End-User Developers

You are a developer using Claude Code (or another agent) with codescout already set up. You want to understand what the tools do and when to reach for each one, so you can ask the agent better questions and interpret its reasoning.

Start here: Progressive Disclosure and Tool Selection, then browse the Tool Reference for the categories you use most.

Contributors

You want to add a language, write a new tool, or swap in a different embedding backend. You need to understand the internal architecture: the Tool trait, the LSP client, the embedding pipeline, the output guard system.

Start here: Architecture, then Adding Languages and Writing Tools.

How to Read This Manual

The manual is organized into three sections:

User Guide — everything you need to install, configure, and use codescout. Reads linearly for first-time setup; use it as a reference once you are familiar.

Tool Reference — one page per tool category. Each page covers what the tools do, their parameters, output format, and when to prefer them over alternatives. You do not need to read this cover to cover; look up the category you need.

Development — architecture internals, extension guides, and troubleshooting. Oriented toward contributors and operators debugging unexpected behavior.

Get Started

• Installation — build the binary, register the MCP server, install LSP servers
• Your First Project — onboarding, indexing, and your first tool calls
• Routing Plugin — the plugin that ensures Claude always reaches for codescout tools

A Quick Example

Here is what a concrete agent interaction looks like with codescout versus without it.

Without codescout — the agent uses read_file on auth.rs (850 lines), scans for authenticate_user, reads the function, then uses grep for callers, gets 23 hits including test fixtures, reads three more files to disambiguate, and still misses that the error type changed in a recent refactor.

With codescout:

symbols("src/auth.rs")
  → authenticate_user [fn, line 142], SessionStore [struct, line 12], ...

references("authenticate_user", "src/auth.rs")
  → middleware/auth_guard.rs:88, handlers/login.rs:34, handlers/api.rs:201

run_command("git log src/auth.rs")
  → 3 days ago: "refactor: change AuthError to return structured payload"

symbols("AuthError", include_body=true)
  → enum AuthError { ... } with full definition

Four targeted calls. The agent sees the symbol tree, the exact call sites, the relevant git history, and the type definition — without reading a single full file. That is the difference codescout makes.

From code-explorer to codescout

TL;DR

• The project was renamed. The binary is now codescout, not code-explorer.
• Update your MCP config: change the server key from code-explorer to codescout.
• Update any scripts or aliases that call the old binary name.
• 9 tools were renamed and 3 consolidated — see the CHANGELOG for the full mapping.

The name

The original name was code-explorer. It made sense at the time — the tool helped an AI navigate a codebase the way a developer would explore it in an IDE.

Two things changed.

First, the practical one: code-explorer was already taken on crates.io. A Rust binary needs a crate name, and that one wasn’t available.

Second, the honest one: the name had stopped fitting. By the time the rename happened, the tool had grown persistent memory that survives across sessions, semantic search over embeddings, a shell integration with output buffering, a project dashboard, and LSP-backed navigation across 9 languages. It wasn’t just exploring files anymore. It was orienting an AI inside a codebase — tracking context, surfacing what matters, remembering what was learned.

Scout felt closer to that. A scout doesn’t just wander. It goes ahead, maps the terrain, and comes back with something useful.

What it grew into

The project started as file navigation. You could list symbols, search for patterns, read a function body without dumping the whole file into context.

Then it got LSP: real go-to-definition, hover types, find-all-references — the same signals a developer gets from their IDE, available to the AI.

Then semantic search: find code by concept, not just by text match. Then persistent memory: notes the AI can read back next session, carrying context forward. Then shell integration with output buffers, so large command output doesn’t blow the context window. Then a dashboard for project health.

Each addition was driven by a recurring friction — the AI doing something clumsy that a better tool could prevent. The scope kept expanding because the problem kept expanding.

Migrating from code-explorer

If you were running code-explorer before, here’s everything that changed at the API surface:

Update your .mcp.json (or Claude Code’s ~/.claude/settings.json) to use "codescout" as the server key. The core behavior is unchanged — it’s a rename, not a rewrite. Tool names were also tidied up alongside the rename; see What else changed below.

What else changed

Alongside the rename, the tool API was tidied up:

• 9 tools renamed for consistency — plural list_* for enumeration, find_* for search, search_* for text/semantic. Full mapping in the CHANGELOG.
• 3 tools consolidated — insert_before_symbol and insert_after_symbol merged into insert_code(position: "before"|"after"). is_onboarded folded into onboarding(force: true).

Why codescout?

AI coding agents using only raw file tools — cat, grep, find — burn most of their context window on navigation overhead: reading full files to find one function, re-reading the same module from different entry points, asking questions they already answered two tool calls ago.

The result is shallow understanding, hallucinated edits, and constant course-correction. See the comparison table in the project README for a side-by-side view.

Design choices

codescout exposes the same information an IDE uses — symbol definitions, references, type info, git history — through a standard MCP interface. Three choices drive the design:

• Single-session over agent chains — skills run in the same context window as the main session, avoiding the compound error that accumulates at every inter-agent handoff
• LSP navigation over file reads — symbol-level queries are 10–50x more token-efficient than reading files, and return structured results rather than noise
• Compact by default — every tool defaults to the most useful minimal representation; full bodies available on demand via detail_level: "full"

Research

These choices are informed by research on compound error in multi-agent systems — research and empirical evidence confirm failure rates of 41–87% in production multi-agent pipelines.

Read the analysis →

Installation

Platform support: codescout has been tested on Linux. macOS and Windows may work but have not been verified. Contributions welcome.

This is a Claude Code tool. codescout is built for Claude Code and currently requires it as the host agent.

The Easy Way

Clone the repo and let Claude handle the installation. It has access to the full documentation, your system, and the install scripts — it will build the binary, register the MCP server, install LSP servers for your languages, and set up the routing plugin.

git clone https://github.com/mareurs/codescout.git
cd codescout
claude
# Then ask: "Help me install and set up codescout"

Manual Installation

If you prefer to install manually, follow the steps below.

Prerequisites

You need a working Rust toolchain. If you do not have one, install it via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify you have Rust 1.75 or later:

rustc --version

You also need Claude Code installed and available as claude on your PATH.

Installing the Binary

Install codescout from crates.io:

cargo install codescout

This builds with the remote-embed feature enabled by default, which adds HTTP client support for talking to an external embedding API (OpenAI-compatible, Ollama, etc.). If you want local CPU-based embeddings without any external service, see Feature Flags below.

Registering as an MCP Server

Claude Code discovers MCP servers through its configuration. You can register codescout either globally (applies to every Claude Code session on your machine) or per-project (applies only when working in a specific directory tree).

Global Registration

Run this once to make codescout available in every Claude Code session:

claude mcp add --global codescout -- codescout start --project .

With global registration, codescout starts automatically whenever Claude Code opens. The --project . argument tells it to activate the project you opened Claude Code in.

Per-Project Registration via .mcp.json

For tighter control — useful when different projects need different embedding backends or when you are sharing configuration with a team — create or edit .mcp.json in the project root:

claude mcp add codescout -- codescout start --project /path/to/your/project

This writes an entry to .mcp.json. Commit the file so that everyone working on the project gets the same codescout setup automatically.

A resulting .mcp.json entry looks like this:

{
  "mcpServers": {
    "codescout": {
      "command": "codescout",
      "args": ["start", "--project", "/path/to/your/project"]
    }
  }
}

Replace /path/to/your/project with the absolute path to your repository root.

Verification

After registering, confirm Claude Code sees the server and all its tools:

claude mcp list

You should see codescout listed with 29 tools. If it does not appear, make sure the codescout binary is on your PATH:

which codescout
codescout --version

Running Onboarding

This is the most important step. After registering the MCP server, you must run onboarding once for each project you want to use codescout with. Until you do, codescout has no project context — LSP servers haven’t started, no system prompt has been generated, and the agent won’t know which tools to use or when.

In a new session in your project directory, ask your agent:

Run codescout onboarding

The onboarding tool will:

1. Detect your project — languages, entry points, key files
2. Start LSP servers — one per detected language (Rust analyzer, Pyright, ts-server, etc.)
3. Generate a system prompt — a project-specific guidance block injected into every future session, covering tool selection rules, entry points, and navigation tips
4. Write .codescout/project.toml — your project config file, which you can edit to customize embedding backends, ignored paths, and security settings

Onboarding takes 10–30 seconds on first run (LSP server startup). Subsequent sessions reuse the running servers and load instantly.

When to re-run onboarding

• After adding a new language to a project (new LSP server needed)
• After significantly restructuring your codebase (entry points change)
• After editing .codescout/project.toml manually
• If codescout’s tool guidance feels stale or wrong

Re-run with force: true to rebuild from scratch: ask your agent "Run codescout onboarding with force: true".

Note: If you skip onboarding, tools like symbols, symbols, and symbol_at will return errors — they depend on LSP servers that onboarding starts.

Feature Flags

As of v0.12 the default substrate is the Retrieval Stack (Qdrant + dense embedder + sparse SPLADE + cross-encoder reranker, all running as docker containers). The local-embed Cargo feature still exists for air-gapped use but is no longer the default and is no longer the path the team benchmarks against — local-embed skips sparse fusion and rerank, which the benchmark shows costs ~9 points out of 75 (28 vs 37 on the champion config). See Migration from local-embed if you are upgrading from <0.12.

The Cargo features below control the codescout binary’s compile-time capabilities. They are independent of whether you run the retrieval stack — even without local-embed, the binary always speaks HTTP to the stack via remote-embed.

Want free, local embeddings without running docker? Two options:

1. Ollama as the dense embedder. Install Ollama, pull a model (ollama pull nomic-embed-text), and set CODESCOUT_EMBEDDER_URL=http://127.0.0.1:11434, CODESCOUT_EMBEDDER_PROTOCOL=openai. You still need Qdrant + the reranker + the sparse service running from the docker stack — Ollama only replaces the dense leg. See Retrieval Stack > Using Ollama / llama.cpp / OpenAI.
2. Build with local-embed for the pure in-process path. Accept the benchmark penalty (no rerank, no sparse fusion) in exchange for zero network dependencies.

Local Embeddings via fastembed (local-embed)

The local-embed feature depends on ONNX Runtime as a native system library. Because of this native dependency, it is not available via cargo install codescout from crates.io. To use it you must build from source:

git clone https://github.com/mareurs/codescout.git
cd codescout
cargo install --path . --no-default-features --features local-embed,http,librarian

The first time you build a semantic search index, the local backend model downloads automatically to ~/.cache/huggingface/hub/. Subsequent uses are fully offline.

In this mode semantic_search falls back to pure dense vector scoring — no SPLADE sparse leg, no cross-encoder rerank. The retrieval-stack configuration in this manual does not apply to local-embed mode.

Minimal Install (No Embeddings)

If you only want LSP-backed symbol navigation and git tools and do not need semantic search, you can build without any embedding feature:

cargo install codescout --no-default-features --features http,librarian

Semantic search tools (semantic_search, index) will return a clear error if called without an embedding backend compiled in.

Next Steps

• Your First Project — open a project, run onboarding, and try the basic tools
• Routing Plugin — install the plugin that steers Claude toward codescout tools automatically

Your First Project

This page walks you through opening a project for the first time and making sure codescout is working correctly before you start a real task.

Start a Claude Code Session

Open Claude Code in your project directory:

cd /path/to/your/project
claude

When codescout is registered (either globally or via .mcp.json), it starts automatically alongside Claude Code. You do not need to do anything to launch the MCP server.

What Happens on First Open

The first time codescout activates in a project it:

1. Creates a configuration file at .codescout/project.toml with sensible defaults.
2. Detects the languages present in the repository (based on file extensions and tree-sitter grammar support).
3. Starts LSP servers for the detected languages, ready to answer symbol queries.

You can check the generated configuration at any time with the workspace tool:

{ "name": "workspace", "arguments": { "action": "status" } }

Running Onboarding

For a project you have not explored before, run onboarding first. It performs a structured discovery pass: reads directory structure, detects languages and frameworks, and writes a set of memory entries so future sessions start with context already in place.

{ "name": "onboarding", "arguments": {} }

Onboarding takes 10–30 seconds depending on project size. During the run it probes your hardware (Ollama availability, GPU, RAM) and presents a ranked list of embedding model options. Accept the recommendation or pick an alternative — the chosen model is written into .codescout/project.toml before indexing begins.

It produces a summary of what it found and tells you how many memory entries it wrote. Subsequent sessions skip the heavy discovery work because the memories are already there — call onboarding again (with default arguments) to retrieve existing memories without re-running discovery:

{ "name": "onboarding", "arguments": {} }

Building the Embedding Index

Semantic search requires an embedding index. Build it once, then keep it up to date as the codebase changes:

{ "name": "index", "arguments": { "action": "build" } }

Indexing chunks every source file, embeds each chunk, and stores the vectors in .codescout/embeddings.db. For a project with ~100k lines of code this typically takes 1–3 minutes. The index is incremental — only changed files are re-embedded on subsequent runs.

Verify the index was built successfully:

{ "name": "workspace", "arguments": { "action": "status" } }

Sample output:

Embedding index status
  Files indexed : 312
  Chunks        : 4 847
  Model         : nomic-embed-text
  Last updated  : 2026-02-26 14:32 UTC

Trying the Basic Tools

Once onboarding and indexing are done, try these tools to get a feel for what is available.

List Directory Structure

See the top-level layout of the project:

{ "name": "tree", "arguments": { "path": "." } }

Drill into a subdirectory:

{ "name": "tree", "arguments": { "path": "src", "recursive": true } }

List Symbols

See the classes, functions, and types defined in a directory — one compact line per symbol, no bodies:

{ "name": "symbols", "arguments": { "path": "src/" } }

Sample output (Rust project):

src/main.rs
  fn main                    src/main.rs:12
  fn parse_args              src/main.rs:28

src/server.rs
  struct Server              src/server.rs:14
  impl Server
    fn new                   src/server.rs:31
    fn run                   src/server.rs:58
    fn shutdown              src/server.rs:102

Find a Symbol by Name

Locate every definition of a symbol across the entire project:

{ "name": "symbols", "arguments": { "pattern": "main" } }

To see the full function body alongside the location, add include_body:

{
  "name": "symbols",
  "arguments": { "pattern": "main", "include_body": true }
}

Semantic Search

Find code by concept rather than by name — useful when you do not know what the relevant symbol is called:

{
  "name": "semantic_search",
  "arguments": { "query": "error handling" }
}

Sample output:

src/server.rs  lines 88-112  score 0.91
  fn handle_request(...) -> Result<Response, AppError> {
      ...

src/errors.rs  lines 1-45  score 0.87
  pub enum AppError { ... }

Each result includes the file path, line range, similarity score, and a preview of the matched chunk. Use the score as a rough relevance signal — results above 0.8 are usually directly relevant; results below 0.5 are often tangential.

Typical First-Session Workflow

A practical sequence for exploring an unfamiliar codebase:

1. onboarding — discover and remember the project structure.
2. index(action: build) — build the semantic search index.
3. tree on the root and key subdirectories — build a mental map.
4. symbols("src/") — see what is defined at the top level.
5. semantic_search("entry point") or symbols("main") — find where execution starts.
6. From there, use references to trace callers and symbols to navigate deeper into subsystems.

After the first session, onboarding memories persist in .codescout/memories/ and the embedding index stays in .codescout/embeddings.db. Both are checked into .gitignore by default so team members build their own local copies.

Next Steps

• Routing Plugin — install the plugin that ensures subagents also use codescout
• Tool Selection — when to use symbol tools vs semantic search vs text search
• Progressive Disclosure — how tools manage output size automatically

codescout-companion Plugin

Why the Plugin Exists

Claude Code has access to codescout’s 28 tools, but it also has built-in tools like grep, cat, and Read. Without guidance, Claude tends to reach for the familiar built-ins — especially in subagents, which start each task with a blank slate and have no memory of earlier instructions.

The codescout-companion plugin solves this with three hooks that run automatically:

• SessionStart — injects a tool selection guide into every new session, explaining when to prefer codescout tools over built-ins.
• SubagentStart — propagates the same guide to every subagent that Claude Code spawns, so subagents also know to use codescout from the start.
• PreToolUse — actively intercepts calls to grep, cat, Read, find, and ls and redirects them to the appropriate codescout equivalents before they execute.

The difference in practice:

• Without the plugin: Claude has access to codescout but may use grep for pattern search and cat for reading files out of habit, missing LSP-backed navigation, token-efficient output, and progressive disclosure.
• With the plugin: every session and subagent starts with a clear preference order, and old habits are caught and redirected automatically.

Architecture

┌─────────────────────────────────────────────────────┐
│                   Claude Code                        │
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │  codescout-companion plugin (hooks)        │    │
│  │                                              │    │
│  │  SessionStart  → inject tool selection guide │    │
│  │  SubagentStart → propagate to all subagents  │    │
│  │  PreToolUse    → redirect grep/cat/read to   │    │
│  │                  codescout equivalents    │    │
│  └──────────────────────┬──────────────────────┘    │
│                         │ routes to                   │
│  ┌──────────────────────▼──────────────────────┐    │
│  │  codescout MCP server (28 tools)         │    │
│  │                                              │    │
│  │  LSP · Semantic · Git · AST · Memory · ...   │    │
│  └──────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

The plugin is a lightweight shim — it holds no state and adds no latency to tool calls. Its only job is to steer Claude toward the right tools at the right moment.

Installation

Option 1: Claude Code Plugin Command

/plugin marketplace add mareurs/sdd-misc-plugins
/plugin install codescout-companion@sdd-misc-plugins

This downloads and enables the plugin immediately. It persists across sessions.

Option 2: User Settings

Add the plugin to your Claude Code user settings at ~/.claude/settings.json:

{
  "enabledPlugins": {
    "codescout-companion@sdd-misc-plugins": true
  }
}

If the file does not exist yet, create it with that content. Settings take effect the next time you start a Claude Code session.

Verification

After installation, start a new Claude Code session and ask Claude which tools it will use for code search. You should see it cite grep, symbols, and semantic_search rather than grep. You can also check installed plugins:

claude /plugin list

codescout-companion@sdd-misc-plugins should appear in the output.

What Each Hook Does

SessionStart

Injects the following guidance at the start of every session:

• Prefer grep over grep for regex search across files.
• Prefer symbols and symbols over cat/Read when exploring code structure.
• Prefer tree over ls and tree (with glob) over find.
• Use semantic_search when looking for code by concept rather than by name.
• Reserve built-in file tools for writing new content and reading files that codescout does not index (binary files, generated artifacts, etc.).

This guidance is injected as a system-level note, not as a user message, so it does not clutter the conversation.

SubagentStart

Claude Code spawns subagents for parallel or delegated tasks. Each subagent is a fresh context with no knowledge of earlier instructions. The SubagentStart hook fires when each subagent initialises and injects the same tool selection guide, ensuring consistent behaviour across the full agent tree.

Without this hook, subagents reliably fall back to grep and cat because they have no other frame of reference.

PreToolUse

The interception hook fires before any of these built-in tools execute:

The hook does not blindly block all uses of these tools. It applies heuristics to distinguish between reading source code (redirect) and reading configuration, logs, or other non-code files (allow through). You can inspect the redirection logic in the plugin source if you need to adjust the heuristics for your workflow.

Disabling the Plugin

To turn off the plugin without uninstalling it, set its value to false in settings:

{
  "enabledPlugins": {
    "codescout-companion@sdd-misc-plugins": false
  }
}

Or uninstall it entirely:

claude /plugin uninstall codescout-companion@sdd-misc-plugins

Further Reading

• Routing Plugin (concepts) — how the plugin works, why hard blocks beat soft warnings, the subagent coverage problem

Agent Integrations

codescout works with any MCP-capable coding agent. Once registered as an MCP server, codescout’s system prompt injects automatically into every session, giving the agent tool selection rules and iron laws for code navigation.

Feature comparison

Guides

Claude Code

One-Time Setup

Prerequisites: Rust toolchain.

1. Install the binary

Option A — from crates.io (recommended):

cargo install codescout

The binary lands at ~/.cargo/bin/codescout.

Option B — build from source:

git clone https://github.com/mareurs/codescout
cd codescout
cargo build --release
# binary is at target/release/codescout
# optionally copy it somewhere on your PATH:
cp target/release/codescout ~/.local/bin/

2. Register as an MCP server

User-level (available in all projects) — recommended:

claude mcp add --scope user --transport stdio codescout -- codescout start

This writes the entry to ~/.claude.json. You can also edit that file directly if you prefer.

Project-level — place a .mcp.json file at the project root:

{
  "mcpServers": {
    "codescout": {
      "command": "codescout",
      "args": ["start"],
      "type": "stdio"
    }
  }
}

3. Onboard your project

Once the MCP server is registered, open Claude Code in your project directory and ask it to run onboarding. Onboarding performs a structured discovery pass — reads directory structure, detects languages and frameworks, probes available embedding backends, and writes memory entries so future sessions start with context already in place. It takes 10–30 seconds depending on project size.

After onboarding, build the semantic search index:

Run index_project.

See Your First Project for the full walkthrough.

Workflow Skills

Claude Code handles workflow skills differently from Copilot/Cursor — skills are loaded via the Superpowers plugin system, not manually installed files. No manual skill file installation is needed; skills activate automatically once the companion plugin is set up. See Superpowers workflow for details.

Routing Plugin (codescout-companion)

The routing plugin is a Claude Code plugin that enforces codescout tool use via PreToolUse hooks. Without it, the agent may fall back to native Read, Grep, and Glob tools — which work but bypass codescout’s token-efficient symbol navigation.

What it blocks:

• Read on source files (.rs, .ts, .py, etc.) → redirects to list_symbols / find_symbol
• Grep / Glob on source files → redirects to search_pattern / find_file
• Bash for shell commands → redirects to run_command

What it allows:

• Read on non-source files (markdown, TOML, JSON, config)
• All codescout MCP tools pass through unrestricted

Install via:

claude plugin install codescout-companion

Or follow the Routing Plugin guide for manual setup.

Debugging: If the plugin blocks a legitimate operation, create .claude/codescout-companion.json with {"block_reads": false} to temporarily disable blocking.

Verify

Restart Claude Code, then run /mcp — confirm codescout appears as connected. Then ask: “What symbols are in src/main.rs?” — Claude should call mcp__codescout__list_symbols, not read the file.

Multi-Project Workspaces

codescout supports multi-project workspaces. Register projects in .codescout/workspace.toml:

[[project]]
id = "backend"
root = "services/backend"

[[project]]
id = "frontend"
root = "apps/frontend"

After onboarding, use the project parameter to scope tool calls:

find_symbol("UserService", project: "backend")
memory(action: "read", project: "frontend", topic: "architecture")

See Multi-Project Workspaces.

Day-to-Day Workflow

codescout injects tool guidance automatically into every session via the MCP system prompt. For the full disciplined development workflow, see:

• Superpowers workflow
• Tool Reference
• Progressive Disclosure

Tips

Buffer refs — When read_file or run_command returns a @file_* or @cmd_* handle, the content is stored server-side. Query it with run_command("grep pattern @cmd_xxxx") or read sub-ranges with read_file("@file_xxxx", start_line=1, end_line=100).

Semantic search for exploration — When entering an unfamiliar part of the codebase, start with semantic_search("how does X work") rather than reading files. It returns ranked code chunks by relevance.

Memory for cross-session context — Use memory(action: "remember", content: "...") to store decisions, patterns, or gotchas. Use memory(action: "recall", query: "...") to retrieve them by meaning in future sessions.

Library navigation — When goto_definition resolves to a dependency, codescout auto-registers the library. Use semantic_search(scope: "lib:tokio") to search within it.

GitHub Copilot

codescout works with GitHub Copilot Chat in VS Code via the MCP protocol. Once registered, Copilot uses codescout’s symbol and semantic tools for all code navigation instead of reading source files directly.

One-Time Setup

Prerequisites: VS Code (latest), GitHub Copilot subscription (Individual, Business, or Enterprise), Rust toolchain.

Install codescout:

cargo install codescout

The binary lands at ~/.cargo/bin/codescout. Make sure ~/.cargo/bin is in your PATH.

Next, clone the codescout-companion repository — this provides the workflow skills, enforcement hook, and code-reviewer agent used in the steps below. The commands use path/to/copilot-codescout as a placeholder for wherever you cloned it.

Register codescout as an MCP server

Recommended: user-level registration — codescout becomes available in all your projects without per-project config. Edit ~/.config/Code/User/mcp.json (create if it doesn’t exist):

{
  "servers": {
    "codescout": {
      "type": "stdio",
      "command": "codescout",
      "args": ["start"]
    }
  },
  "inputs": []
}

Note: VS Code uses "servers" not "mcpServers". If cargo is not in PATH, use the full path as the command value (e.g. ~/.cargo/bin/codescout).

Alternative: per-project registration — create .vscode/mcp.json in your project root with the same servers block. Use this if you want codescout only for specific projects.

VS Code schema validation note: VS Code validates MCP tool schemas more strictly than Claude Code. If you see a warning like “Failed to validate tool … array type must have items”, it is a schema bug in the MCP server — other tools still load and work normally. Report it to the codescout maintainer.

Once registered, codescout’s system prompt injects automatically into every Copilot Chat session, giving Copilot iron laws for code navigation, a tool selection table, anti-patterns to avoid, and the output buffer system for large results.

Enable Agent Skills

1. Open Settings (Ctrl+, / Cmd+,)
2. Search for chat.useAgentSkills
3. Enable it

Copilot will now auto-detect and load skill files when relevant to your request.

Add workflow skills

VS Code Copilot discovers skills in .github/skills/.

# Option A: Symlink (recommended — stays in sync with updates)
# NOTE: do NOT mkdir .github/skills first — ln creates the symlink as the target name
mkdir -p .github
ln -s path/to/copilot-codescout/Skills .github/skills

# Option B: Copy (standalone, no sync)
mkdir -p .github/skills
cp -r path/to/copilot-codescout/Skills/* .github/skills/

Skills are discovered automatically — no further configuration needed.

Add the code-reviewer agent

VS Code Copilot discovers agents in .github/agents/.

mkdir -p .github/agents
cp path/to/copilot-codescout/Agents/code-reviewer.agent.md .github/agents/

Enforcement Hook

The enforcement hook blocks Copilot from reading source files directly and redirects it to codescout tools. Requires Python 3.

mkdir -p .github/hooks
cp path/to/copilot-codescout/Hooks/enforce-codescout.py .github/hooks/
cp path/to/copilot-codescout/Hooks/enforce-codescout.json .github/hooks/

This installs a PreToolUse hook that:

• Blocks read/readFile on source files (.ts, .js, .py, .rs, etc.) and redirects to the appropriate codescout tool
• Blocks search/codebase and redirects to mcp__codescout__semantic_search
• Allows reading config files, markdown, JSON, YAML, and lock files

Multi-Project Workspaces

codescout supports multi-project workspaces via .codescout/workspace.toml. After onboarding, pass project to scope tool calls to a specific project:

{ "tool": "find_symbol", "arguments": { "pattern": "UserService", "project": "backend" } }

See Multi-Project Workspaces.

Always-On Instructions

cp path/to/copilot-codescout/copilot-instructions.md .github/copilot-instructions.md

VS Code Copilot injects .github/copilot-instructions.md into every chat session automatically, giving Copilot the codescout iron laws and tool selection table before any request.

If .github/copilot-instructions.md already exists, append the codescout section rather than overwriting.

Verify

Start a new Copilot Chat session and ask:

“What symbols are in src/main.ts?”

Copilot should call mcp__codescout__list_symbols rather than reading the file directly.

Day-to-Day Workflow

Skills activate automatically when their description matches the request — you never type a slash command. The standard flow is:

brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → finishing-a-development-branch

Skill trigger table

Step-by-step

1. Brainstorming — Describe what you want to build. Copilot activates the brainstorming skill, explores the codebase via codescout (semantic search, symbol lookup), asks clarifying questions one at a time, and proposes 2–3 approaches with trade-offs. No code is written until you approve the design.

2. Set up an isolated workspace — Say “Create a worktree” or “Let’s work on a branch.” The using-git-worktrees skill creates an isolated git worktree on a new branch, runs project setup, and verifies the test baseline is clean before any code is written.

3. Write the implementation plan — Say “Write the plan” or “Break this into tasks.” The writing-plans skill produces a detailed docs/plans/YYYY-MM-DD-feature.md with every task broken into 2–5 minute TDD steps: write the failing test, watch it fail, write minimal code, watch it pass, commit.

4. Execute the plan — Say “Execute the plan” or “Implement it.” The subagent-driven-development skill dispatches a fresh sub-agent per task (clean context, no drift). A spec compliance reviewer and a code quality reviewer both check each implementation before the next task begins.

5. Code review — Happens automatically after each task in subagent-driven-development. For ad-hoc review, say “Review this implementation.” The requesting-code-review skill dispatches the code-reviewer agent, which uses references and semantic_search to check impact beyond the changed files.

6. Finish the branch — Say “I’m done” or “All tasks complete.” The finishing-a-development-branch skill verifies all tests pass, presents merge/PR/discard options, and cleans up the worktree.

Tips

• Don’t rush brainstorming. The questions feel slow but they prevent far more work later.
• Trust the spec reviewer. If it says something is missing, it read the actual code — not the implementer’s report.
• Let codescout navigate. If Copilot starts reading whole files, remind it: “use codescout to explore”.
• One task at a time. The subagent-driven workflow is sequential by design — parallel tasks introduce conflicts.

Updating Skills

cd path/to/copilot-codescout
git pull
# Symlink: already up to date.
# Copy: re-run the cp command.

Cursor

codescout works with Cursor Agent chat via the MCP protocol. Once registered, Cursor uses codescout’s symbol and semantic tools for all code navigation instead of reading source files directly.

One-Time Setup

Prerequisites: Cursor (latest), Rust toolchain.

Install codescout:

cargo install codescout

The binary lands at ~/.cargo/bin/codescout. Make sure ~/.cargo/bin is in your PATH.

Next, clone the codescout-companion repository — this provides the workflow skills, enforcement hook, and code-reviewer agent used in the steps below. The commands use path/to/copilot-codescout as a placeholder for wherever you cloned it.

Register codescout as an MCP server

Recommended: project-level registration — checked into git, shared with your team. Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codescout": {
      "command": "codescout",
      "args": ["start"]
    }
  }
}

Note: Cursor uses "mcpServers" (with s), unlike VS Code’s "servers". If cargo is not in PATH, use the full path as the command value (e.g. ~/.cargo/bin/codescout).

Alternative: global registration — available in all projects. Open Cursor → Settings → Cursor Settings → MCP → Add new server → paste the same config block.

Once registered, codescout’s system prompt injects automatically into every Agent session.

Add workflow skills

Cursor discovers rules in .cursor/rules/. Two options:

Option A — Convert each skill to .mdc format (recommended):

For each skill in path/to/copilot-codescout/Skills/, create a corresponding .cursor/rules/<name>.mdc file:

mkdir -p .cursor/rules

Each .mdc file follows this format:

---
description: [paste the description from skill frontmatter]
globs:
alwaysApply: false
---

[paste the full skill body here]

Set alwaysApply: false — Cursor auto-applies rules based on description matching, the same model-invoked behavior as Copilot Skills.

Option B — Entry-point rule with alwaysApply: true:

Add the using-superpowers skill content to .cursor/rules/using-superpowers.mdc with alwaysApply: true. This tells the agent to check for relevant rules before any task, mirroring the Claude Code hook behavior.

Add the code-reviewer agent

mkdir -p .cursor/agents
cp path/to/copilot-codescout/Agents/code-reviewer.agent.md .cursor/agents/

Enforcement Hook

The enforcement hook blocks Cursor from reading source files directly and redirects it to codescout tools. Requires Python 3.

mkdir -p .cursor/hooks
cp path/to/copilot-codescout/Hooks/enforce-codescout.py .cursor/hooks/
cp path/to/copilot-codescout/Hooks/enforce-codescout.json .cursor/hooks/

This installs a PreToolUse hook that:

• Blocks read/readFile on source files (.ts, .js, .py, .rs, etc.) and redirects to the appropriate codescout tool
• Blocks search/codebase and redirects to mcp__codescout__semantic_search
• Allows reading config files, markdown, JSON, YAML, and lock files

Verify

Start a new Agent chat and ask:

“What symbols are in src/main.ts?”

The agent should call mcp__codescout__list_symbols rather than reading the file directly.

Day-to-Day Workflow

Skills activate automatically when their description matches the request — you never type a slash command. The standard flow is:

brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → finishing-a-development-branch

Rule trigger table

Step-by-step

1. Brainstorming — Describe what you want to build. The agent activates the brainstorming rule, explores the codebase via codescout (semantic search, symbol lookup), asks clarifying questions one at a time, and proposes 2–3 approaches with trade-offs. No code is written until you approve the design.

2. Set up an isolated workspace — Say “Create a worktree” or “Let’s work on a branch.” The using-git-worktrees rule creates an isolated git worktree on a new branch, runs project setup, and verifies the test baseline is clean before any code is written.

3. Write the implementation plan — Say “Write the plan” or “Break this into tasks.” The writing-plans rule produces a detailed docs/plans/YYYY-MM-DD-feature.md with every task broken into 2–5 minute TDD steps: write the failing test, watch it fail, write minimal code, watch it pass, commit.

4. Execute the plan — Say “Execute the plan” or “Implement it.” The subagent-driven-development rule dispatches a fresh sub-agent per task (clean context, no drift). A spec compliance reviewer and a code quality reviewer both check each implementation before the next task begins.

5. Code review — Happens automatically after each task in subagent-driven-development. For ad-hoc review, say “Review this implementation.” The requesting-code-review rule dispatches the code-reviewer agent, which uses references and semantic_search to check impact beyond the changed files.

6. Finish the branch — Say “I’m done” or “All tasks complete.” The finishing-a-development-branch rule verifies all tests pass, presents merge/PR/discard options, and cleans up the worktree.

Tips

• .cursor/rules/ is your friend. If a rule isn’t triggering, check that the .mdc file exists and the description field is specific enough.
• Context window. Cursor Agent can lose context on very long sessions. The subagent-driven approach (fresh agent per task) is specifically designed to prevent this.
• Let codescout navigate. If the agent starts reading whole files instead of using symbol tools, say: “use codescout to explore this”.
• Compose with existing Cursor Rules. Your team’s .cursor/rules/ files for style, architecture, or tooling sit alongside the codescout skill rules — they don’t conflict.
• Check MCP is active. Open Cursor Settings → MCP and verify the server shows a green status indicator.

Multi-Project Workspaces

codescout supports multi-project workspaces via .codescout/workspace.toml. After onboarding, pass project to scope tool calls to a specific project:

{ "tool": "find_symbol", "arguments": { "pattern": "UserService", "project": "backend" } }

See Multi-Project Workspaces.

Cursor-Specific Notes

Rules vs Skills

Cursor calls them “Rules” (.cursor/rules/*.mdc). They are functionally identical to Copilot Skills — model-invoked based on description matching. Same content, different filename extension and location.

Agent Chat vs Background Agent

• Agent Chat (Cmd+L → Agent): Interactive, sees your conversation. Use this for the full workflow.
• Background Agent: Headless task runner. Good for executing a specific isolated task from the plan, but lacks the interactive brainstorming/review loop.

Use Agent Chat for the full codescout workflow.

Plan Mode

Cursor has a built-in “Plan Mode” (the thinking icon in Agent chat). The brainstorming rule replaces this for structured design work — it’s more thorough and saves a design doc. For quick one-off tasks, Plan Mode is fine.

Feature comparison

Progressive Disclosure

LLM context windows are finite. Every token spent on output you didn’t need is a token that could have held something useful. codescout is designed around a single principle to address this: show the minimum that is actionable, and reveal detail only when asked.

The Problem

Without guardrails, code intelligence tools can produce enormous output:

Filling the context window with irrelevant symbols, boilerplate bodies, and off-target files makes it harder to reason about the code you actually care about. It also wastes time: you pay the cost of processing all that output before you can identify what you need.

The Solution: Two Modes

codescout tools operate in one of two modes, controlled by the detail_level parameter.

Exploring mode (the default) produces compact summaries: names, kinds, file paths, and line numbers. Results are capped at 200 items. No function bodies, no full diffs, no deep trees. The goal is to give you a map of the territory so you can identify your target.

Focused mode (detail_level: "full") produces complete detail: function bodies, full symbol trees, entire diffs. Results are paginated via offset and limit (default page size: 50). Use this only after you know what you are looking for.

How OutputGuard Enforces This

Every tool that can produce unbounded output delegates its output control to a shared OutputGuard struct (in src/tools/output.rs). Tools do not implement their own truncation logic; the guard enforces consistent behavior project-wide.

OutputGuard::from_input() reads three optional fields from a tool’s JSON input:

• detail_level: "full" activates Focused mode; anything else (or absent) gives Exploring mode.
• offset: where to start in paginated output (default: 0).
• limit: page size in Focused mode (default: 50). If you pass an explicit limit in Exploring mode, the guard honours it as a cap.

should_include_body() returns true only in Focused mode. Tools use this to decide whether to fetch and include function bodies from the language server.

cap_items() and cap_files() enforce the limits:

• In Exploring mode: keep the first max_results (or max_files) items, discard the rest, attach an overflow object describing what was omitted.
• In Focused mode: apply offset/limit pagination, attach an overflow object that includes next_offset when more pages remain.

When results exceed the cap, the overflow object tells you what to do next:

{
  "overflow": {
    "shown": 47,
    "total": 312,
    "hint": "Narrow with a file path or glob pattern"
  }
}

In Focused mode, the overflow includes next_offset for sequential pagination:

{
  "overflow": {
    "shown": 50,
    "total": 312,
    "hint": "Use offset/limit to page through results",
    "next_offset": 50
  }
}

The Pattern: Explore, Identify, Focus

The intended workflow has three steps:

1. Explore broadly. Use tools in their default Exploring mode to get a compact map of the area you care about.
2. Identify your target. Read the compact output to find the file, symbol, or range that contains what you need.
3. Focus narrowly. Switch to Focused mode on exactly that target to get full detail.

Example

You want to understand the authentication logic in a service layer.

Step 1 — get the map:

{ "tool": "symbols", "arguments": { "path": "src/services/" } }

Response (compact, exploring mode):

{
  "files": [
    {
      "file": "src/services/auth.rs",
      "symbols": [
        { "name": "AuthService", "kind": "Struct", "start_line": 12 },
        { "name": "handle_login", "kind": "Function", "start_line": 34 },
        { "name": "verify_token", "kind": "Function", "start_line": 61 },
        { "name": "refresh_session", "kind": "Function", "start_line": 89 }
      ]
    },
    {
      "file": "src/services/user.rs",
      "symbols": [
        { "name": "UserService", "kind": "Struct", "start_line": 8 },
        { "name": "find_by_email", "kind": "Function", "start_line": 22 }
      ]
    }
  ]
}

Four symbols in auth.rs, verify_token looks relevant. Total context consumed: a few dozen tokens.

Step 2 — identify the target: verify_token in src/services/auth.rs.

Step 3 — focus on it:

{
  "tool": "symbols",
  "arguments": {
    "pattern": "verify_token",
    "relative_path": "src/services/auth.rs",
    "include_body": true,
    "detail_level": "full"
  }
}

Now you get the full function body — but only for the one function you identified, not for every symbol in the file.

This workflow minimizes context usage at every step. The broad exploration is cheap; the focused read is exact.

Further Reading

• Output Modes — the detail_level, offset, and limit parameters in full detail, with examples for every tool
• Tool Selection — matching your level of knowledge to the right tool, including the anti-patterns that cause context bloat

Output Modes

codescout tools produce different amounts of detail depending on which mode they operate in. Understanding the two modes — and when to switch between them — is the key to using the tools efficiently.

Exploring Mode (Default)

Exploring mode is the default for every tool that supports it. You do not need to pass any parameter to get it.

In Exploring mode, tools return compact summaries:

• Symbols: name, kind, file path, start and end line. No function bodies.
• Files: paths only, no content.
• Diffs: truncated at a reasonable size with a count of omitted files.
• Blame: first 200 lines, with an overflow message if the file is longer.

Results are capped at 200 items (or 200 files for directory-spanning tools). If more results exist, the response includes an overflow object explaining what was omitted and how to narrow the query.

Example — exploring mode response for symbols:

{
  "file": "src/services/auth.rs",
  "symbols": [
    { "name": "AuthService", "kind": "Struct", "start_line": 12, "end_line": 30 },
    { "name": "handle_login", "kind": "Function", "start_line": 34, "end_line": 60 },
    { "name": "verify_token", "kind": "Function", "start_line": 61, "end_line": 88 }
  ]
}

No bodies, no children — just the shape of the file.

Focused Mode (detail_level: "full")

Focused mode returns full detail and paginates results. Activate it by passing detail_level: "full" to any tool that supports it.

In Focused mode, tools return:

• Symbols: full bodies, all children, complete detail.
• Files: full content of matching entries.
• Diffs: complete diff output, paginated by file if needed.
• Blame: paginated line-by-line blame for the full file.

Results are paginated via offset and limit (default page size: 50). The first page starts at offset: 0. Subsequent pages use the next_offset value from the overflow object.

Example — focused mode response for symbols:

{
  "symbols": [
    {
      "name": "verify_token",
      "kind": "Function",
      "file": "src/services/auth.rs",
      "start_line": 61,
      "end_line": 88,
      "body": "pub fn verify_token(token: &str, secret: &[u8]) -> Result<Claims> {\n    let key = DecodingKey::from_secret(secret);\n    let validation = Validation::new(Algorithm::HS256);\n    let data = decode::<Claims>(token, &key, &validation)\n        .map_err(|e| AuthError::InvalidToken(e.to_string()))?;\n    if data.claims.exp < Utc::now().timestamp() as usize {\n        return Err(AuthError::TokenExpired);\n    }\n    Ok(data.claims)\n}"
    }
  ]
}

Switching Between Modes

Pass detail_level: "full" to any tool that supports it:

{
  "tool": "symbols",
  "arguments": {
    "pattern": "verify_token",
    "relative_path": "src/services/auth.rs",
    "include_body": true,
    "detail_level": "full"
  }
}

{
  "tool": "symbols",
  "arguments": {
    "path": "src/services/",
    "detail_level": "full",
    "limit": 10
  }
}

## Overflow Messages

When the number of results exceeds the cap, the response includes an `overflow`
object at the top level:

```json
{
  "results": [ "..." ],
  "overflow": {
    "shown": 47,
    "total": 312,
    "hint": "Narrow with a file path or glob pattern"
  }
}

The hint tells you how to reduce the result set. Common hints suggest narrowing the path, providing a more specific pattern, or adding a glob filter.

In Focused mode, the overflow object also includes next_offset when more pages exist:

{
  "results": [ "..." ],
  "overflow": {
    "shown": 50,
    "total": 312,
    "hint": "Use offset and limit to page through results",
    "next_offset": 50
  }
}

When next_offset is absent (or null), you are on the last page.

Paginating through results:

{ "tool": "symbols", "arguments": { "pattern": "Error", "detail_level": "full", "offset": 0,  "limit": 50 } }
{ "tool": "symbols", "arguments": { "pattern": "Error", "detail_level": "full", "offset": 50, "limit": 50 } }
{ "tool": "symbols", "arguments": { "pattern": "Error", "detail_level": "full", "offset": 100, "limit": 50 } }

Tools That Support Both Modes

These tools respect detail_level, offset, and limit:

Tools With Fixed Output

Some tools always cap their output at a fixed limit and do not support mode switching:

For these tools, use their own limit or max_results parameter to control output size. They do not use the detail_level / offset / limit pattern.

Practical Guidance

Use Exploring mode to find what you are looking for. Use Focused mode only once you have a specific target. Switching early costs you context; switching at the right time costs almost nothing.

If you see an overflow message in Exploring mode, prefer narrowing the query (a more specific path, glob, or pattern) over switching to Focused mode. A narrower Exploring query is usually more useful than a paginated Focused query over 300 results.

If you see next_offset in Focused mode and you need all the results, page through sequentially. Do not try to read all pages in a single pass unless you need the full picture; often the first one or two pages contain the answer.

Further Reading

• Progressive Disclosure — the design principle behind the two-mode system and how OutputGuard enforces it
• Symbol Navigation Tools — the tools where detail_level has the most impact

Tool Selection

Choosing the right tool for a task depends on what you already know about the code. codescout organizes its tools around three knowledge levels. Matching your level of knowledge to the right tool category avoids wasted queries and keeps context usage low.

You Know the Name

You have a file path, function name, class name, or method name. Use the structure-aware tools that navigate by name directly.

symbols(pattern) — locate a symbol by name substring across the project or within a specific file. Fast because it goes through the language server index.

{
  "tool": "symbols",
  "arguments": { "pattern": "AuthService", "relative_path": "src/services/auth.rs" }
}

symbols(path) — list all symbols in a file, directory, or glob pattern. Use this when you have a file and want to see what is in it before deciding which symbol to read.

{ "tool": "symbols", "arguments": { "path": "src/services/auth.rs" } }

**`references(name_path, path)`** — find every location
that references a specific symbol. Use this when you know the symbol and want
to trace all its callers or usages.

```json
{
  "tool": "references",
  "arguments": { "name_path": "AuthService/verify_token", "path": "src/services/auth.rs" }
}

Once you have located the symbol you want, switch to Focused mode to read its
body:

```json
{
  "tool": "symbols",
  "arguments": {
    "pattern": "verify_token",
    "relative_path": "src/services/auth.rs",
    "include_body": true,
    "detail_level": "full"
  }
}

You Know the Concept

You have domain knowledge but not a specific name. You know that “there is error handling somewhere” or “authentication goes through a token check” but you do not know the file or function name.

Start with semantic search, then drill down.

semantic_search(query) — finds code relevant to a natural language description using embedding similarity. It crosses file boundaries and finds conceptually related code even when the literal words do not match.

{ "tool": "semantic_search", "arguments": { "query": "JWT token verification and expiry" } }

The response gives you scored chunks with file paths and line ranges. From those results, you have names and locations — move to the name-based tools to read the full symbols.

Typical concept-first workflow:

1. semantic_search("how are database errors handled") — get a list of relevant files and line ranges.
2. symbols(found_file) — see the symbol structure around those lines.
3. symbols(name, include_body=true, detail_level="full") — read the specific function body.

You Know Nothing

You are exploring an unfamiliar codebase or an area you have not touched before. Start with structure and orient yourself before looking at any code.

Step 1 — see the directory structure:

{ "tool": "tree", "arguments": { "path": "src" } }

This gives you the top-level layout: which directories exist, rough file counts. Do not use recursive: true yet — the compact view of the top level is usually enough to identify where to look next.

Step 2 — scan a promising file or directory:

{ "tool": "symbols", "arguments": { "path": "src/services/" } }

This shows all symbols across the directory in compact form. You get names, kinds, and line numbers for every symbol in every file, without loading any bodies.

Step 3 — get a high-level picture with semantic search:

{ "tool": "semantic_search", "arguments": { "query": "request lifecycle and routing" } }

Semantic search fills in context that structure cannot: which files handle which concerns, what patterns are used, where the main logic lives.

Step 4 — drill into specifics:

Once you have a target, use symbols in Focused mode to read actual code.

Common Anti-Patterns

Reading entire files with read_file instead of using symbols. read_file without explicit line ranges dumps the full file content into context. If you know the function name, use symbols(include_body=true) instead — you get the function body without the surrounding boilerplate.

Using grep (grep) when semantic_search would serve better. grep matches literal text. It works well for finding exact strings, imports, or call sites where you know the exact text. When you want code that implements a concept (“retry logic”, “cache invalidation”), semantic search finds related code even when the words you think of do not appear in the source.

Switching to Focused mode before knowing what you want. Calling symbols with detail_level: "full" on a large directory floods the context with every function body in every file. Use Exploring mode to identify the target, then use Focused mode on that specific target.

Using references without a specific symbol. This tool requires a fully-qualified symbol path (TypeName/method_name in the file that defines it). It is not a search tool — it is a precision tool for tracing usages of a known symbol.

Quick Reference

Further Reading

• Progressive Disclosure — how output volume is controlled once you’ve selected the right tool
• Semantic Search — deeper explanation of when and how semantic search finds code you can’t name

Shell Integration

Overview

run_command executes any shell command from the project root with stderr capture, Output Buffer support, and a thin safety layer. It is the primary way the AI interacts with the build system, test runner, version control, and any other CLI tooling.

run_command("cargo build")
run_command("git log --oneline -20")
run_command("grep FAILED @cmd_a1b2c3")   # query a previous buffer
run_command("diff @cmd_abc @file_def")   # compose refs freely

Stderr is captured automatically alongside stdout — no 2>&1 needed. Use the cwd parameter to run in a subdirectory (path traversal outside the project root is rejected).

Safety Layer

Dangerous Command Detection

Commands with destructive potential are detected before execution and blocked until the AI explicitly passes acknowledge_risk: true. The detection covers:

• Filesystem destruction: rm -rf, rmdir, shred
• Git rewrites: reset --hard, push --force, clean -f, rebase
• Database mutations: DROP TABLE, DELETE FROM, TRUNCATE
• Process termination: kill -9, pkill

The intent is a deliberate pause, not an impenetrable wall. The AI can always pass acknowledge_risk: true to proceed — it just has to do so explicitly rather than accidentally.

In practice: Over 6+ months of daily use, Claude has never triggered this unprompted on a command that would actually cause damage. The main effect is an extra confirmation click for legitimate destructive operations (e.g. cleaning build artifacts). It’s still worth keeping — MCP tools run with your full user permissions, and the occasional pause costs almost nothing compared to what it could prevent.

Source File Access Blocking

cat, grep, head, tail, sed, and awk used directly on source files (.rs, .py, .ts, .go, .java, .kt, etc.) are blocked at the tool level. The error message suggests the appropriate codescout equivalent:

This enforces token-efficient navigation. Reading an entire file to find one function is the antipattern codescout is designed to eliminate.

Pass acknowledge_risk: true to bypass when you genuinely need raw access (e.g. checking file encoding, binary content, or files codescout can’t parse).

Path Traversal Protection

The cwd parameter is validated before the command runs. Any path that attempts to escape the project root — via ../, symlink chains, or absolute paths outside the tree — is rejected with an error naming the violation.

Output Buffer refs (@cmd_id, @file_id) are resolved within the session and are read-only when materialised as temporary files for Unix tool access. They never expose raw filesystem paths outside the buffer system.

Further Reading

• Output Buffers — how large command output is stored and queried with @cmd_id refs rather than dumped into context
• Workflow & Config Tools — full run_command reference including all parameters

Output Buffers

The Problem

MCP tools return their results directly into the AI’s context window. For large command output — a full cargo test run, a broad grep, a 2000-line file — that means the entire output lands in context whether the AI needs all of it or not. The result is a bloated context, wasted tokens, and an AI that has to skim walls of text to find what it actually needs.

How It Works

When run_command or read_file produces output above a size threshold, codescout stores the full content in an in-memory buffer and returns a compact summary + an @id handle instead:

run_command("cargo test")
→ {
    "summary": "47 passed, 2 failed — FAILED: test_parse, test_render",
    "output_id": "@cmd_a1b2c3",
    "exit_code": 1
  }

The full output is held in memory, keyed by the @id. The AI can then query it with targeted follow-up run_command calls using standard Unix tools:

run_command("grep FAILED @cmd_a1b2c3")
run_command("sed -n '42,80p' @cmd_a1b2c3")
run_command("grep -A5 'thread.*panicked' @cmd_a1b2c3")

File reads work the same way — large files become @file_id references:

read_file("src/main.rs")
→ { "summary": "...", "file_id": "@file_abc456" }

run_command("grep 'fn.*async' @file_abc456")

Refs compose freely. You can diff two buffers, pipe one through awk, or pass a @file_id to grep alongside a pattern from a @cmd_id:

run_command("diff @cmd_a1b2c3 @cmd_d4e5f6")
run_command("grep -F -f @file_abc456 @cmd_a1b2c3")

Why It Matters

Short output is always returned inline. Only responses above the threshold get buffered. The AI never has to think about whether to use @refs — the tool handles the routing automatically.

Each buffer query shows up as a distinct tool call in Claude Code’s UI. Instead of one undifferentiated wall of text, the user sees the AI making targeted, reviewable queries — grep FAILED, then sed -n '42,80p', then grep -A5 'panicked'. The exploration is transparent and auditable.

When a buffer query still returns too much, you get 100 lines inline. If grep @ref or jq @tool_ref produces more than 100 lines, codescout returns the first 100 lines inline with truncation metadata rather than creating another @ref handle (which would cause an infinite loop). The response includes truncated: true, stdout_shown/stdout_total (and stderr_shown/stderr_total when stderr is non-empty) so the AI can decide whether to refine further. Stderr is prioritised — up to 20 stderr lines are shown, with the remaining budget going to stdout.

The context window stays lean. The AI holds a reference to large output without paying the token cost of the full content. It pays only for what it actually reads.

Buffers survive across multiple turns. A @cmd_id from a cargo test run can be queried again later in the same session — no need to re-run the command to look at a different part of the output.

Buffer Lifecycle

Buffers are held in memory for the lifetime of the MCP server process. They use an LRU eviction policy: when the buffer store fills up (default: 50 entries), the least-recently-accessed entry is dropped. Accessing a buffer (even to query it) refreshes its position in the eviction order.

Buffers are not persisted to disk. Restarting the server clears them.

Further Reading

• Shell Integration — run_command in full detail: safety layer, dangerous command detection, and source file access blocking
• Workflow & Config Tools — full reference for run_command including the cwd, acknowledge_risk, and timeout_secs parameters

Elicitation-Driven Interactive Sessions

run_command now supports an interactive: true parameter that spawns the process with piped stdin/stdout/stderr and drives it via MCP elicitation in a loop. Instead of a session_send/session_cancel multi-tool protocol, the entire session fits in one tool call.

Usage

{
  "command": "python3 -c \"name=input('Your name? '); print(f'Hello, {name}!')\"",
  "interactive": true
}

Each loop iteration:

1. Reads available output (with a 150 ms settle window to batch bursts).
2. Shows accumulated output in an elicitation dialog.
3. Waits for the user to type input (or leave empty to cancel).
4. Sends the input to the process stdin.
5. Repeats until the process exits naturally or the user cancels.

Parameters

Cancellation

Leave the input field empty in the elicitation dialog to cancel. The process is killed with SIGKILL and accumulated output is returned.

A safety cap of 50 elicitation rounds is enforced. If reached, the process is killed and a [interactive: max rounds reached, process killed] note is appended to the output.

Return value

{
  "exit_code": 0,
  "stdout": "<accumulated stdout + stderr>",
  "interactive_rounds": 3
}

When the process is killed (user cancel, max rounds, or write error):

{
  "exit_code": -1,
  "stdout": "<accumulated output>\n[interactive: cancelled by user]",
  "interactive_rounds": 2,
  "note": "process killed or loop exited before natural termination"
}

Limitations

• Latency: each round-trip through MCP elicitation adds ~1–3 s. Suitable for setup wizards and slow-paced REPLs; not suitable for ncurses TUIs, editors, or programs expecting sub-second responses.
• Settle heuristic: the 150 ms silence window may split a logical prompt across two rounds if the program emits output in bursts with longer pauses.
• Dangerous commands: interactive: true blocks dangerous commands outright (no elicitation confirmation). Use the standard non-interactive path with acknowledge_risk: true if needed.
• No elicitation fallback: if the MCP client does not support elicitation, a RecoverableError is returned immediately. There is no non-interactive fallback — use interactive: false (the default) in that case.
• No test coverage: integration testing requires a live MCP peer with elicitation support.

Semantic Search

Semantic search finds code by meaning rather than by name or text pattern. It answers queries like “authentication middleware”, “retry with exponential backoff”, or “parse JSON from HTTP response” — without knowing what the relevant functions are called.

It complements symbol tools: use symbol tools when you know the name, semantic search when you know the concept.

How It Works

Three steps happen when you call semantic_search:

1. Chunking — The first time index(action: build) runs, every source file is split into chunks whose size is derived from the configured model’s context window (roughly max_tokens × 3 chars/token at 85 % utilisation). Splits follow language structure: each top-level function, method, or class becomes its own chunk. When a container (an impl block, a class) exceeds the budget, it is recursively split into one chunk per inner method, plus a header chunk for the container signature. The plain-text fallback path handles languages without tree-sitter support. Each chunk records its 1-indexed start and end line so results link back to exact source locations.

2. Embedding — Each chunk is converted to a vector (a list of floating-point numbers) by the configured embedding model. Semantically similar text produces vectors that point in similar directions in high-dimensional space. The model is selected by onboarding based on your hardware (Ollama availability, GPU, RAM); ollama:nomic-embed-text is the default when Ollama is running, and local:JinaEmbeddingsV2BaseCode is used on CPU-only machines. See Embedding Backends to change it manually. The vectors are stored in .codescout/embeddings.db.

3. Search — Your query is embedded with the same model and compared to every stored chunk using cosine similarity. The closest chunks are returned, ranked by score.

The index is incremental. On subsequent index(action: build) calls, only files that changed since the last run are re-embedded — detected via git diff, then file mtime, then SHA-256 as a fallback chain.

Similarity Scores

Results include a score between 0 and 1:

Code embeddings score lower than prose embeddings for the same conceptual similarity — a score of 0.75 in a code search is strong. Do not compare scores across different embedding models; they are not on the same scale.

When to Use Semantic Search

Semantic search is slowest of these options (it embeds your query at call time and scans all stored vectors). Prefer symbol tools when you know the name.

Index Lifecycle

Build the index once before first use:

{ "tool": "index(action: build)", "arguments": {} }

Check its health:

{ "tool": "workspace(action: status)", "arguments": {} }

The index is stored in .codescout/embeddings.db and excluded from version control by default. Each team member builds their own local copy.

Drift detection: workspace(action: status) can report per-file drift scores — a measure of how much file content has changed since it was last indexed. Pass threshold to surface files with high drift:

{ "tool": "workspace(action: status)", "arguments": { "threshold": 0.3 } }

Switching embedding models invalidates the entire index — all chunks must be re-embedded. See Embedding Backends for model selection guidance.

Further Reading

• Semantic Search Setup Guide — step-by-step: choose a backend, configure, build the index, write effective queries
• Embedding Backends — all supported backends and model selection guidance
• Semantic Search Tools — full reference for semantic_search, index(action: build), and workspace(action: status)

The Retrieval Stack

As of v0.12 codescout’s default retrieval substrate is a network-attached stack (Qdrant + three embedding services), not the in-process local-embed path. The local-embed Cargo feature still exists for air-gapped use, but it is no longer the default and is no longer the path the team benchmarks against. If you upgrade from <0.12 and want to keep working, you must either bring up the stack or rebuild with --features local-embed and accept the older sqlite-vec code path. See Migration from local-embed below.

What runs where

codescout connects to these services on 127.0.0.1. There is no per-project substrate — the stack is shared across all projects on a machine.

Bring up the stack

# CPU profile (default — works on any Linux/macOS machine, ~3 GB RAM idle):
docker compose --profile cpu up -d

# GPU profile (CUDA — uses NVIDIA runtime, ~2.5 GB VRAM idle):
docker compose --profile gpu up -d

The dense embedder needs a GGUF model file. First-run setup:

mkdir -p models
cd models
huggingface-cli download nomic-ai/CodeRankEmbed-GGUF \
    CodeRankEmbed-Q4_K_M.gguf --local-dir .
# Or: wget https://huggingface.co/nomic-ai/CodeRankEmbed-GGUF/resolve/main/CodeRankEmbed-Q4_K_M.gguf

If your models/ directory is somewhere else, set CODESCOUT_MODEL_DIR before docker compose up.

Verify everything is healthy:

docker compose ps                 # all services "healthy"
curl -fsS http://127.0.0.1:48081/health   # dense
curl -fsS http://127.0.0.1:48083/health   # reranker
curl -fsS http://127.0.0.1:48084/health   # sparse
curl -fsS http://127.0.0.1:6333/healthz   # qdrant

AMD ROCm profile (docker compose --profile amd)

The amd profile in docker-compose.yml runs every leg of the retrieval stack on the GPU: dense embedder, cross-encoder reranker, and sparse SPLADE all share the AMD device. Qdrant runs alongside on CPU as usual. This is the recommended path on any workstation with an AMD GPU and ROCm 7.x installed on the host.

Bring up:

docker compose --profile amd up -d

Topology when using the amd profile:

Required model files in ${CODESCOUT_MODEL_DIR:-./models}:

huggingface-cli download nomic-ai/CodeRankEmbed-GGUF \
    CodeRankEmbed-Q4_K_M.gguf --local-dir ./models      # ~90 MB
huggingface-cli download gpustack/bge-reranker-v2-m3-GGUF \
    bge-reranker-v2-m3-Q4_K_M.gguf --local-dir ./models # ~419 MB

The SPLADE model is pulled by the sparse-amd container at first launch into the huggingface-cache volume; no manual download needed.

Host requirements:

• AMD GPU (RX 7xxx / MI series), gfx1100+ recommended
• ROCm 7.x installed on host (kernel driver + /dev/kfd, /dev/dri)
• User in video and render groups

The compose service declares devices: [/dev/kfd, /dev/dri] and group_add: ["44", "992"] (numeric video/render GIDs — the rocm/pytorch sparse image lacks a render group entry, so group names don’t resolve). No NVIDIA-style runtime extension needed; AMD exposes the GPU via standard Linux character devices.

Wire codescout: copy .env.amd (in the repo root) to .env. It sets the ports above plus the protocol selectors required to talk to llama-server’s /v1/embeddings and /v1/rerank:

CODESCOUT_EMBEDDER_PROTOCOL=llama-server  # /v1/embeddings, not TEI's /embed
CODESCOUT_RERANKER_PROTOCOL=llama-server  # Cohere-shape /rerank

Why dense + reranker use llama.cpp instead of TEI:

• TEI’s ROCm path is fragile and lags upstream; rocm/llama.cpp is AMD-built.
• Same binary serves the dense embedder and the cross-encoder reranker (--reranking mode), so one image covers two services.

Why sparse uses TEI: SPLADE is an MLM-style model with no llama.cpp implementation, and CPU latency saturates 32 cores on a full reindex of a 21k-chunk project. Building TEI from source against ROCm 7.1 + PyTorch 2.8 (see SPLADE on ROCm) puts SPLADE on the GPU and drops a full reindex from “minutes of CPU melting” to ~6 m 36 s at 121 % CPU.

How codescout finds the stack

codescout reads endpoints from environment variables and falls back to the defaults above:

Using Ollama / llama.cpp / OpenAI as the dense embedder

The shipped stack uses llama.cpp:server for the dense leg, but the dense service is just an HTTP endpoint behind CODESCOUT_EMBEDDER_URL. Any TEI-compatible or OpenAI-compatible server will work.

Ollama

Ollama exposes an OpenAI-compatible embeddings endpoint at http://localhost:11434/v1. Pull a model and point codescout at it:

ollama pull nomic-embed-text         # or any model with /api/embeddings
export CODESCOUT_EMBEDDER_URL=http://127.0.0.1:11434
export CODESCOUT_EMBEDDER_PROTOCOL=openai
export CODESCOUT_EMBEDDER_MODEL_NAME=nomic-embed-text

# Optional — Nomic needs a query prefix for asymmetric search:
export CODESCOUT_QUERY_PREFIX="search_query: "

You still need Qdrant + the reranker + the sparse service running from the docker-compose stack — Ollama only replaces the dense leg. Stop the compose dense-cpu or dense-gpu container so the port is free:

docker compose --profile cpu stop dense-cpu

llama.cpp (standalone)

If you already run llama-server outside docker, the same approach applies:

llama-server -m ~/models/CodeRankEmbed-Q4_K_M.gguf \
    --port 48081 --embedding --pooling mean --ctx-size 8192

…then leave CODESCOUT_EMBEDDER_URL and CODESCOUT_EMBEDDER_PROTOCOL at their defaults. The compose dense-* service is just a packaged version of this command — see docker-compose.yml for the full flag list.

OpenAI / Anthropic-compatible APIs

export CODESCOUT_EMBEDDER_URL=https://api.openai.com/v1
export CODESCOUT_EMBEDDER_PROTOCOL=openai
export CODESCOUT_EMBEDDER_MODEL_NAME=text-embedding-3-small
# (codescout reads OPENAI_API_KEY from the environment automatically)

Cost: a full index of a ~10k-file Rust project is roughly 8 M tokens at ~768-dim. Budget accordingly.

How we chose the components — benchmark summary

A 75-query retrieval benchmark was run across ~15 candidate stacks on a pinned worktree of this repo. The full history lives in docs/trackers/retrieval-benchmark.md. Headline results below — all measured on the same query set at bm25_boost=5.0, mode=code, with cross-encoder rerank enabled unless noted.

Dense embedder

Why Q4 over f16: Q4_K_M scores higher than f16 in our query set when no prefix is set, and runs in ≤1 GB RAM. The f16 advantage only appears when the model’s asymmetric query prefix is enabled, and even then it caps one point below Q4 no-prefix. We default to Q4 no-prefix.

Sparse leg

We initially shipped a local Tantivy BM25 leg. It scored similarly to SPLADE on lexical queries but was a maintenance burden (tantivy compile time, on-disk index drift, separate rebuild step) and could not run as a service. We migrated to SPLADE-PP_en_v1 via TEI — same conceptual role, runs as a container, no per-project index. The benchmark showed sparse fusion gives +2 points over dense-only at bm25_boost=5.0.

Reranker

bge-v2-m3 wins on the full suite and is the default. jina-rerank-v2 lifts the T5 (real-usage) tier by +1 every time but loses on long natural-language queries. The protocol toggle (CODESCOUT_RERANKER_PROTOCOL=infinity) lets you swap with a single env var — no rebuild needed.

Stack-wide latency (champion config)

Indexing throughput on the codescout repo itself (~3.5 k chunks):

Migration from local-embed

If you have a .codescout/embeddings/project.db from a pre-v0.12 install:

# 1. Stand up the stack (see above)
# 2. Re-embed legacy memories into Qdrant:
codescout migrate-memories --dry-run    # preview
codescout migrate-memories              # execute
# 3. Re-index your project:
codescout index

The legacy sqlite-vec file is no longer read after migration. You can delete it once you’ve verified memory recall works against the new substrate.

If you cannot run the stack (air-gapped, embedded environment), build with local-embed:

cargo install codescout --no-default-features --features local-embed,http,librarian

This restores the in-process ONNX + fastembed path. Note: the network retrieval pipeline (sparse fusion, cross-encoder rerank) is not available in this mode — semantic_search falls back to pure dense vector scoring.

Troubleshooting

Semantic Search Guide

Semantic search lets you find code by describing what it does rather than knowing what it is called. This page walks you through the full setup from choosing a backend to writing effective queries. For a reference of the individual tools, see Semantic Search Tools.

For an explanation of how semantic search works under the hood — chunking, scoring, and when to use it vs symbol tools — see Semantic Search Concepts.

Choosing an Embedding Backend

codescout supports four embedding backends. The model string prefix in project.toml selects which one is used:

Recommended starting point: The bundled local:AllMiniLML6V2Q model — no setup required, works offline, and downloads only ~22 MB on first use. For higher search quality or multi-project setups, see Embedding Backends.

Setting Up Ollama

Install Ollama, pull the default model, and verify it responds correctly before touching project.toml.

# Install Ollama (Linux/macOS)
curl -fsSL https://ollama.com/install.sh | sh

# Pull the default model
ollama pull mxbai-embed-large

# Verify the embedding endpoint is responding
curl http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "mxbai-embed-large", "input": "test"}'

A successful response looks like:

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.012, -0.034, ...] }],
  "model": "mxbai-embed-large"
}

If curl returns a connection error, Ollama is not running. Start it with ollama serve in a separate terminal and retry.

If you run Ollama on a non-default host or port, set the OLLAMA_HOST environment variable before starting Claude Code:

export OLLAMA_HOST=http://192.168.1.10:11434

Configuring codescout

The [embeddings] section of .codescout/project.toml controls which model is used and how files are chunked. The defaults work well for most projects:

[embeddings]
model = "local:AllMiniLML6V2Q"

model is the only setting you need to change. Chunk size is derived automatically from the model’s context window — no manual tuning required.

To use OpenAI instead, set the model and export your API key:

[embeddings]
model = "openai:text-embedding-3-small"

export OPENAI_API_KEY=sk-...

Building the Index

Once project.toml is configured (or using the default), build the index:

{ "name": "index", "arguments": { "action": "build" } }

What happens internally:

1. codescout walks the project tree, skipping directories listed in ignored_paths (by default: .git, node_modules, target, __pycache__, .venv, dist, build, .codescout).
2. Each source file is split into chunks using an AST-aware chunker. Each top-level function, method, or class becomes its own chunk. Oversized containers (impl blocks, classes) are recursively split into one chunk per inner method plus a header chunk for the container signature. Chunk size is derived from the model’s context window — no configuration needed.
3. Each chunk is sent to the configured embedding backend, which returns a dense vector.
4. The vectors and chunk metadata are stored in .codescout/embeddings.db (SQLite).

How long it takes: With Ollama on a modern laptop, expect roughly 80–120 files per minute. OpenAI’s API is faster in wall-clock time because requests are batched and network latency is low — typically 3–5x faster for large projects. A 10,000-line project usually indexes in under two minutes with either backend.

Incremental updates: Running index(action: build) again after editing a few files is cheap. codescout hashes each file’s content and only re-embeds files whose hash has changed since the last run. Unchanged files are skipped at negligible cost.

Force reindex: Use force: true when you change the model in project.toml. Vectors from different models are not comparable, so the entire index must be rebuilt:

{ "name": "index", "arguments": { "action": "build", "force": true } }

You can check index health at any time:

{ "name": "workspace", "arguments": { "action": "status" } }

The output shows config.embeddings.model (from project.toml) and the index.model (what was used to build the current index). If they differ, a force reindex is needed.

Searching Effectively

Natural Language Queries

Describe what the code does in plain language. You do not need to know the function name or file location:

{ "name": "semantic_search", "arguments": { "query": "how errors are handled" } }

{ "name": "semantic_search", "arguments": { "query": "database connection setup" } }

{ "name": "semantic_search", "arguments": { "query": "authentication token validation" } }

Concrete, specific queries outperform vague ones. Prefer “retry logic with exponential backoff” over “error handling”. Prefer “connection pool initialization” over “database”.

Code Snippet Queries

Paste a function signature or a short snippet as the query to find similar code elsewhere in the project. This is useful for spotting duplication or locating the canonical version of a pattern:

{
  "name": "semantic_search",
  "arguments": {
    "query": "fn connect(host: &str, port: u16) -> Result<Connection>"
  }
}

Interpreting Scores

Each result includes a score between 0 and 1 (cosine similarity):

The top result is not always the most useful one. Scan the top five results before drilling into any single chunk.

Recommended Workflow

Semantic search is the entry point for concept-first exploration. After finding relevant chunks, use the symbol tools to navigate the surrounding code:

1. semantic_search — find the files and line ranges where a concept lives.
2. symbols on those files — see the surrounding structure.
3. symbols with include_body: true — read the exact implementation.
4. references — trace callers if needed.

Tuning

Chunk Size

Chunk size is not configurable — it is derived automatically from the model’s published context window using the formula:

chunk_size = max_tokens × 0.85 × 3 chars/token

The 0.85 factor leaves headroom for tokenisation variance; 3 chars/token is a conservative lower bound for mixed code and prose. Representative values:

Because AST chunking splits at function/method boundaries rather than at character counts, most chunks are well within the budget regardless of model. The budget mainly controls when a single oversized node is recursively split into inner methods.

Model Choice

The embedding model has the largest effect on search quality. General-purpose text models (nomic-embed-text, text-embedding-3-small) work well for documentation and comments. Code-specific models (local:JinaEmbeddingsV2BaseCode) tend to perform better on function signatures and code identifiers.

After changing the model, always run index(action: build) with force: true.

Troubleshooting

“No results” or empty results list

The index may not be built yet. Run workspace(action: status) to check. If index.indexed is false, run index(action: build). If the index exists but results are empty, the query may be too generic — try a more specific description.

“Connection refused” when indexing

An external embedding server (Ollama, llama.cpp, etc.) is not running. Start it, or switch to the bundled model by setting model = "local:AllMiniLML6V2Q" in .codescout/project.toml.

“Model not found” error

The model has not been pulled. For Ollama, run ollama pull <model-name> (or whatever model is configured) and retry.

Stale results after editing many files

Run index(action: build) without extra arguments. The incremental update will re-embed only the files that changed.

Results seem wrong after changing the model

The index was built with a different model and the vectors are no longer compatible. Run index(action: build) with force: true. You can confirm the mismatch by checking workspace(action: status): if the config model and the index model differ, a force reindex is required.

Indexing is very slow

If using an external server (Ollama, llama.cpp), check it is running locally and not routing over a slow network connection. The bundled local:AllMiniLML6V2Q model runs in-process and avoids network overhead. For the fastest throughput on large projects, openai:text-embedding-3-small batches requests via API.

Asymmetric Query Prefix for Embedding Models

Some embedding models are trained asymmetrically: documents and queries use different input conventions. The canonical example is CodeRankEmbed, which expects every query to be prefixed with:

Represent this query for searching relevant code:

Without the prefix, query vectors land in a different part of the embedding space than the indexed document vectors, and semantic_search recall drops sharply (typical effect: 30–50% worse top-5 recall).

What this does

codescout now distinguishes document embedding from query embedding at the Embedder trait level. RemoteEmbedder automatically prepends the model-specific query prefix when semantic_search runs, while index-time embedding (through embed) stays unprefixed.

The prefix is selected from the model name:

Detection is purely name-based — no external config and no registry lookup.

Configuration

No user-facing configuration. Set your model via project.toml as usual:

[embeddings]
model = "ollama:coderank-embed"
# or any remote endpoint serving a CodeRankEmbed variant
url = "http://127.0.0.1:43300/v1/embeddings"

codescout detects the coderank substring in the model name and applies the prefix to every query automatically. Re-index after switching models, since document vectors are model-specific.

Trait surface

For library consumers, two points on the Embedder trait:

• embed(&[&str]) — unchanged, document-side batch embedding.
• embed_query(&str) — new, single-query embedding with prefix applied. Default impl delegates to embed with no prefix; RemoteEmbedder overrides to apply the model-specific prefix.

The free function embed_one(embedder, text) now routes through embed_query, so all code paths that embed a single query string benefit from the prefix automatically.

Adding a new asymmetric model

Extend RemoteEmbedder::query_prefix_for in src/embed/remote.rs:

#![allow(unused)]
fn main() {
fn query_prefix_for(model: &str) -> Option<String> {
    let l = model.to_lowercase();
    if l.contains("coderank") {
        Some("Represent this query for searching relevant code: ".into())
    } else if l.contains("your-model") {
        Some("Your model's query prefix: ".into())
    } else {
        None
    }
}
}

No other call site needs to change — the trait default + override pattern keeps the per-model knowledge localized.

Limitations

• Local (fastembed) models do not currently apply prefixes. Add an override on LocalEmbedder::embed_query if you run an asymmetric model locally.
• The match is a simple substring check; if a non-asymmetric model happens to contain coderank in its name you’ll get an incorrect prefix. Rename the model or extend the match if this bites you.

Why this matters

Embedding models are often evaluated on symmetric tasks (document-to-document similarity). Asymmetric models can score higher on code search benchmarks but silently underperform when a pipeline treats query and document embedding as the same operation. Making the distinction explicit at the trait level means the right thing happens automatically once the model is selected.

Metadata-Enriched Chunks

Every code chunk stored in the semantic index now carries a short searchable header prepended to its embedding input. Headers encode file path, container context, and symbol name:

src/embed/index.rs :: impl IndexStore :: fn build_index(force: bool)

This information was previously invisible to the embedding model — chunks were embedded as raw code bodies with no location context. Multi-concept keyword queries (the dominant query shape in real usage) now match on file path, container, and symbol name in addition to body content, giving them more surface area to match on.

What changes

• Chunks have a new metadata column populated during indexing.
• Embedding input is metadata + "\n" + content when metadata is present.
• Search results are unchanged — users still see raw code content. The header is an embedding-only signal.
• Unknown languages and markdown files have metadata = NULL and embed only the body (no behavior change there).

When it helps

• Queries that mention a file path or module name ("embed index build")
• Queries that mention a struct/class name alongside a concept ("IndexStore force rebuild")
• 3–10 word keyword queries — the dominant shape in production traffic

When it won’t help

• Queries that don’t map to any code structure (cross-file architectural questions)
• Bare symbol lookups — use symbols instead, it’s exact

Schema migration

On first index after upgrading, the existing chunks and chunk_embeddings tables are dropped and rebuilt. Expect one reindex delay; thereafter indexing is incremental as usual.

Index Scope Guard

Before index(action: build) commits to walking and embedding a directory, codescout checks whether the scope looks broad enough to be accidental, and requires explicit human confirmation via an MCP elicitation dialog before proceeding.

Triggers

Confirmation is required if either:

1. The project root is a known-broad directory, such as:
   • Your home directory (~)
   • The parent of home (e.g. /home)
   • A system root: /, /usr, /etc, /var, /tmp, /root, /opt, /proc, /sys
2. The approximate raw source size exceeds the threshold (default 500 MB of eligible content, respecting .gitignore and hidden-file rules — same filter index(action: build) itself uses).

When either trigger fires, the MCP client shows a dialog like:

⚠ Broad index scope detected

Root: /home/alice  (home directory)
Eligible files: ~3,200
Approx source content: ~2.4 GB
Estimated chunks: ~600,000

This will use significant RAM and CPU time.
Confirm indexing this directory?

You can accept to proceed or decline to abort. The check runs on every call — it is not persisted. If your MCP client does not support elicitation, the call is refused with a clear error rather than silently proceeding.

Configuration

Adjust the size threshold in .codescout/project.toml:

[security]
max_index_bytes = 1073741824   # 1 GB

The default is 524288000 (500 MB). Set it higher to allow larger projects without a prompt; lower to trigger the guard more aggressively.

Currently, the suspicious-path list is fixed — it is not configurable.

Rationale

An agent that calls workspace(action: activate, path: "~") followed by index(action: build) would otherwise walk the entire home directory, ingest every file, and cause severe RAM spikes or OOM (see docs/issues/memory-leak-x-session-freeze.md). The scope guard makes that path impossible without a human in the loop.

Auto-Reindex on Edit

Semantic search results stay current as files are edited, without requiring an explicit index(action='build') call.

How it works

When a write tool (edit_file, edit_code, create_file) modifies a file, codescout checks whether the file’s hash has changed since it was last indexed. If it has, the file is added to an in-memory dirty set.

The next call to semantic_search drains the dirty set and re-embeds all changed files before running the KNN query. The write tool still returns immediately — re-embedding is deferred until search time.

edit_code("src/foo.rs", ...)       → dirty_set: {"src/foo.rs"}
semantic_search("find all traits") → reindex src/foo.rs → knn on fresh index

Properties

• Zero write latency — dirty set insertion is synchronous and sub-millisecond (one SHA-256 hash check).
• Idempotent — multiple writes to the same file before a search collapse to a single re-embed.
• Non-blocking on failure — if re-embedding fails (e.g. embedder unavailable), a warning is logged and the search continues with stale data.
• Scope — only files written through codescout tools. External editor edits are not tracked (filesystem watcher is a separate future feature).

Hybrid Dense + Sparse Retrieval

semantic_search uses a hybrid retrieval pipeline combining dense vector search with sparse SPLADE keyword search, fused via Reciprocal Rank Fusion (RRF) inside Qdrant.

History: Prior to v0.12 the sparse leg was a local Tantivy BM25 index. Since v0.12 it is a SPLADE service in the retrieval stack — same conceptual shape (lexical complement to dense), different implementation. The Tantivy code and bm25.rs module have been deleted.

How it works

1. Dense leg — query embedded by the dense embedder service (default localhost:48081, TEI or OpenAI protocol) and matched against the code_chunks collection’s dense vector field.
2. Sparse leg — query embedded by the SPLADE service (default localhost:48084, TEI protocol) and matched against the same collection’s sparse vector field.
3. RRF fusion — Qdrant fuses the two ranked lists server-side using 1/(1+rank) (note: rank-1 = 0.500, rank-9 ≈ 0.100 — this is Qdrant’s constant, not the academic k=60 formula).
4. Cross-encoder rerank — top fused candidates are POSTed to the reranker service (default localhost:48083, bge-reranker-v2-m3) for pairwise scoring. Final results are sorted by rerank score.

Behavior

• Hybrid search is always on for project-scope queries — both legs run unconditionally when the retrieval stack is reachable.
• Library scope (scope: "libraries") follows the same pipeline against the lib:NAME project_id namespace.
• If the retrieval stack is unreachable, semantic_search returns a structured error with stack-inspection hints (see src/tools/semantic/search.rs error classification).

Configuration

Rebuilding the indexes

The hybrid indexes are rebuilt automatically at the end of every index(action="build") call — no separate “build the sparse index” step. Both legs share the same chunk set and are upserted into Qdrant atomically.

SPLADE on ROCm (sparse-amd)

Status: stable since v0.12.0. The image is built from a not-yet-merged upstream PR and verified on gfx1100. Other RDNA3 / CDNA arches will probably work but have not been tested by us. If upstream PR #860 ships, this page will simplify to a one-line pointer at the official ROCm image.

The default amd profile keeps SPLADE on CPU because upstream text-embeddings-inference (TEI) does not ship a ROCm release. The sparse-amd service brings sparse encoding onto the GPU by building TEI from source against ROCm 7.1 + PyTorch 2.8.

On a 21k-chunk codescout reindex this drops sparse CPU usage from ~3200 % (saturating 32 cores) to ~121 % (the Rust router thread plus light Python overhead) and finishes the full re-embed in 6 m 36 s.

Why this is experimental

• Upstream PR not merged. The AMD path lives on PR #860 (fa-varlen branch). We pin commit 1588129f93… because requirements-amd.txt and Dockerfile-amd landed there post-v1.9.3. If PR #860 changes, you may need to rebuild.
• gfx1100 has no upstream flash-attention. Upstream PR #860 builds ROCm/flash-attention pinned to gfx942 (MI300). RDNA3 is not supported by that fork. Our Dockerfile skips the flash-attn build and relies on PyTorch SDPA fallback (wired by upstream PR #853). Functionally correct, slower than MI300 would be.
• Heavy image. ~12 GB because the runtime stage keeps the full rocm/pytorch base. A leaner runtime stage is on the TODO list.

Bring up

The service is part of the amd profile in docker-compose.yml:

docker compose --profile amd up -d --build sparse-amd

First build is ~25 minutes (Rust router compile + Python deps + ROCm PyTorch). Subsequent runs reuse the image.

Verify:

curl 127.0.0.1:48084/health     # {"status":"Ok"}
curl -X POST 127.0.0.1:48084/embed_sparse \
     -H 'Content-Type: application/json' \
     -d '{"inputs":"async fn cancel()"}'
# → [[{"index":..., "value":...}, ...]]   sparse activations

The container logs Python backend ready in 5.157s and ROCm / HIP version: 7.1.25424 on startup. If you see torch.cuda.is_available=False, the GPU passthrough is misconfigured — check /dev/kfd and /dev/dri permissions on the host.

Compose service

sparse-amd:
  profiles: [amd]
  build:
    context: ./docker/sparse-amd
    dockerfile: Dockerfile
    args:
      TEI_REF: 1588129f932125a780ab97ccb300e7774b02d230
      PYTORCH_ROCM_ARCH: gfx1100
  image: codescout/sparse-amd:tei-1588129f93
  container_name: codescout-sparse-amd
  ports: ["127.0.0.1:48084:80"]
  devices: [/dev/kfd, /dev/dri]
  group_add: ["44", "992"]   # video, render — numeric: rocm/pytorch image lacks 'render' group
  shm_size: 8g

The numeric group_add is intentional. Docker resolves group names against the image’s /etc/group, not the host’s. rocm/pytorch does not declare a render group, so passing the name fails with Unable to find group render. GIDs 44 (video) and 992 (render) match the defaults on Debian/Ubuntu hosts — adjust if your host differs.

Deviations from upstream PR #860

We follow upstream where possible. Three intentional differences:

1. Skip the flash-attention build. Upstream pins ROCm/flash-attention to gfx942. We delete that build step; PyTorch SDPA covers the gap.
2. Force-reinstall numpy / scipy / scikit-learn after make install. requirements-amd.txt pins numpy==1.26.4 and an old accelerate that wants numpy<2. The rocm/pytorch base image ships numpy 2.x and scipy 1.15 already, so the downgrade leaves scipy._fitpack_impl linked against the wrong numpy ABI and import fails with a TypeError. We restore the base versions instead.
3. Add three missing deps. more_itertools, psutil, and backports.tarfile are transitive requirements of transformers that the rocm/pytorch slim env doesn’t ship. Without them the Python backend crashes on import.

If you hit different ABI breakage, the upstream Makefile workflow (cd backends/python/server && make install) is the reproducible starting point.

Wiring

The default .env.amd already points sparse at 127.0.0.1:48084. No env change is needed when you swap sparse-cpu → sparse-amd; the codescout client only cares about the URL and the protocol (TEI’s /embed_sparse), both of which match.

CODESCOUT_SPARSE_EMBEDDER_URL=http://127.0.0.1:48084

Known issues

• Image size ~12 GB. Runtime stage carries the full rocm/pytorch base. A multi-stage trim that copies only /opt/venv + ROCm runtime libraries onto a smaller base is feasible but not yet attempted.
• Cold start 5 s. The Python backend imports torch + transformers at startup. Live latency after warm is in the same ballpark as TEI-on-CUDA.
• gfx1100 only verified. gfx1030, gfx1101, MI series should work (PyTorch SDPA is arch-agnostic) but have not been tested.

Library Navigation

Library navigation lets you explore third-party dependency source code using the same symbol tools you use for your own project — symbols, symbols, symbol_at, semantic_search — without switching contexts or manually locating package directories.

Auto-Discovery

Libraries are discovered automatically. When you call symbol_at on a symbol and the LSP resolves it to a path outside the project root (typically inside a language package cache), codescout registers that path as a library and names it by the package name inferred from the manifest it finds there.

The next time you call list_libraries, the dependency appears in the list. No manual registration is required for the common case.

The Scope Parameter

Once a library is registered, pass scope to any navigation or search tool to target it:

{
  "tool": "semantic_search",
  "arguments": { "query": "retry with backoff", "scope": "lib:reqwest" }
}

Results include a "source" field so you can tell project code from library code at a glance.

Building a Library Index

Semantic search over library code requires an embedding index, just like project code. Build one with index(action: build) pointed at the library’s root path:

{ "tool": "index(action: build)", "arguments": { "path": "/path/to/tokio-1.35.1/" } }

This is a one-time cost per library. The index persists in .codescout/embeddings/lib/<name>.db — see Per-Library Embedding Databases below.

When to Use Library Navigation

• You’re debugging an unfamiliar error from a dependency and want to read its source without leaving your session
• You want to understand how a library’s internal types relate before writing integration code
• You’re doing a security audit and want to trace a call chain into a dependency
• You want to find usage examples by searching the library’s own tests with semantic_search(scope: "lib:<name>")

Further Reading

• Library Navigation Tools — full reference for list_libraries and library indexing
• Symbol Navigation Tools — the tools that accept the scope parameter
• Semantic Search Tools — semantic search within library scope

Per-Library Embedding Databases

Earlier versions stored all embeddings in a single .codescout/embeddings.db. The current layout splits storage into separate databases:

.codescout/
  embeddings/
    project.db          ← your project's code
    lib/
      tokio.db          ← one file per registered library
      serde.db
      reqwest.db

The filename for each library is derived from its registered name: / and \ are replaced with -- and the result is lowercased (e.g. @org/pkg → org--pkg.db).

Migration is automatic. If an old embeddings.db is found, codescout moves its contents into the new structure the first time the project is opened. No manual steps required.

To build or rebuild a library’s index:

{ "tool": "index(action: build)", "arguments": { "scope": "lib:tokio" } }

Version Tracking and Staleness Hints

When index(action: build, scope="lib:<name>") runs, codescout reads the project’s lockfile (Cargo.lock, package-lock.json, etc.) to record the library version that was indexed.

After a dependency upgrade, semantic_search includes a stale_libraries field:

{
  "stale_libraries": [
    {
      "name": "tokio",
      "indexed": "1.37.0",
      "current": "1.38.0",
      "hint": "tokio was updated — run index(action: build, scope='lib:tokio') to re-index"
    }
  ]
}

Staleness is detected by comparing indexed vs current versions from the lockfile. If the lockfile ecosystem is not recognised, version tracking is skipped.

Multi-Ecosystem Library Auto-Registration

Overview

When workspace(action: activate) runs, codescout now automatically detects and registers dependencies from five ecosystems:

How It Works

1. Discovery — each ecosystem’s manifest file is parsed to extract dependency names. Only production dependencies are included (dev/test dependencies are skipped).

2. Source location — for each dependency, codescout checks whether local source code exists (e.g., in node_modules/, the Cargo registry, or a Python venv).

3. Registration — dependencies are batch-registered with DiscoveryMethod::ManifestScan. The source_available flag indicates whether the source was found locally.

4. Precedence — ManifestScan never overwrites Manual or LspFollowThrough registrations. If you’ve manually registered a library, auto-scan won’t touch it.

Source Availability

Libraries without local source (common for JVM dependencies) are registered with source_available: false. When an agent tries to use symbol tools or semantic search on such a library, they receive a RecoverableError with a hint:

Library source code is not available locally for: jackson-databind
Hint: To browse library source, download it using the project's build tool
(e.g. ./gradlew dependencies, mvn dependency:sources), then call
register_library(name, "/path/to/source", language) and retry.

Output

The workspace(action: activate) response includes auto-registered libraries:

{
  "auto_registered_libs": [
    {"name": "express", "language": "javascript", "source_available": true},
    {"name": "guava", "language": "java", "source_available": false}
  ]
}

The compact output shows: activated · myproject · auto-registered 5 libs (2 without source)

list_libraries now includes source_available for each entry.

Python Name Normalization

Python package names are normalized per PEP 503: lowercased, with runs of -, _, . collapsed to a single _. This matches how pip stores packages in site-packages/.

Go Module Cache Encoding

Go module paths with uppercase letters are encoded per Go conventions: Azure → !azure. This ensures correct lookups in $GOMODCACHE.

Multi-Project Workspace Support

codescout can manage multiple related projects from a single server instance. This is useful for monorepos or closely related repositories where you want cross-project navigation without running separate MCP servers.

Registering projects

Projects are registered in .codescout/workspace.toml under a [[project]] table:

[[project]]
id = "backend"
root = "services/backend"

[[project]]
id = "frontend"
root = "apps/frontend"

Each entry requires id (unique name) and root (path relative to the workspace root). The languages and depends_on fields are optional: languages restricts which LSP servers are started for the project; depends_on lists project IDs whose symbols are visible during cross-project navigation.

Each project gets its own LSP servers, memory store, and semantic index.

Using project scope

Most tools accept a project parameter to scope the operation:

symbols("MyStruct", project: "backend")
semantic_search("authentication flow", project: "frontend")
memory(action: "read", project: "backend", topic: "architecture")

Omitting project uses the workspace-level context.

Onboarding

Run onboarding once after registering projects:

Run codescout onboarding

codescout generates a per-project Navigation Strategy section in the system prompt so the agent knows which files and entry points belong to each project. It also generates cross-project semantic search scope guidance.

Cross-project semantic search

The system prompt includes guidance on which scope= values to use for semantic search across projects, so the agent does not need to guess project boundaries.

workspace(action: activate) Output Optimization

workspace(action: activate) now returns a slim orientation card instead of the full raw config dump.

New response shape

{
  "status": "ok",
  "project": "my-project",
  "project_root": "/home/user/my-project",
  "read_only": false,
  "languages": ["rust"],
  "index": { "status": "not_indexed", "hint": "Run index(action: build) to enable semantic_search." },
  "memories": ["architecture", "conventions"],
  "hint": "CWD: /home/user/my-project. Run workspace(action: status) for health checks and memory staleness.",

  // RW only:
  "security_profile": "default",
  "shell_enabled": true,

  // Multi-project workspaces only:
  "workspace": [
    { "id": "root", "root": ".", "languages": ["rust"], "depends_on": [] },
    { "id": "web", "root": "packages/web", "languages": ["typescript"], "depends_on": ["root"] }
  ],

  // When dependencies were auto-registered:
  "auto_registered_libs": { "count": 12, "without_source": 3 }
}

What changed

Hint scenarios

workspace(action: status) for full details

The orientation card is intentionally compact. For detailed health checks, memory staleness scores, and drift detection, call workspace(action: status) after activation.

Project Hints

workspace(action: activate) now returns a project_hints field with manifest-derived context so agents have useful information even when onboarding has never been run.

Why

Previously, an agent hitting a codescout project in a client that never calls onboarding saw only the languages list. No build commands, no entry points, no manifest info. The agent had to probe the filesystem itself — or guess.

project_hints fills that gap with a cheap manifest probe that runs on every workspace(action: activate) call.

What you get

{
  "status": "ok",
  "project": "codescout",
  "project_root": "/home/you/work/codescout",
  "languages": ["rust"],
  "project_hints": {
    "primary_language": "rust",
    "manifest": "Cargo.toml",
    "entry_points": ["src/main.rs", "src/lib.rs"],
    "build_commands": ["cargo build", "cargo test", "cargo run"],
    "onboarded": false
  },
  "memories": [],
  "hint": "CWD: /home/you/work/codescout. Run workspace(action: status) for health checks and memory staleness."
}

Fields

Supported manifests

Relationship to onboarding

project_hints is not a replacement for the onboarding tool. It’s a cheap fallback for when onboarding has never been called:

When onboarded: true, the real memories (project-overview, architecture, language-patterns) are the authoritative source. project_hints stays populated for consistency but agents should prefer memory content when available.

Behaviour

• No probe runs if the project root has no recognised manifest — fields are null / empty arrays.
• All probes are read-only file-existence checks. No file parsing beyond checking tsconfig.json presence for TS vs JS disambiguation.
• First manifest match wins. package.json takes priority; otherwise the order is: Cargo.toml → pyproject.toml → setup.py → go.mod → pom.xml → build.gradle.kts → build.gradle.

MCP resources, tool diet, and progress notifications

Codescout now exposes three mechanisms to reduce per-turn token overhead and surface activity from long-running operations. They ship together because they share one thesis: pay tokens only when the model asks.

Resources

Codescout implements MCP’s resources/list and resources/read so Claude Code (and any MCP client that supports resources) can fetch static and dynamic context on demand:

In Claude Code, @-mention the URIs to include them in the prompt.

Tool-description diet + conditional exposure

Tool descriptions sent to the model every turn are capped at 300 characters. Longer usage notes (examples, tradeoffs, gotchas) live in doc://codescout-tool-guide and are fetched only when the agent needs them.

Tools are also hidden from list_tools when their required capability is missing:

• LSP tools (symbol_at, references, edit_code(action="rename")) — hidden when no LSP provider is wired for the project’s language.
• Embedding tools (semantic_search, index) — hidden when embeddings are disabled at build time.
• Library tools (library) — hidden when no supported language is detected in the registry.

workspace(action: activate) emits notifications/tools/list_changed when the set shifts, so Claude Code refreshes its tool palette automatically.

Progress notifications

Long-running operations emit notifications/progress (throttled to 2 Hz):

• index(action: build) — per-batch progress + start / complete text
• semantic_search — “loading embedding model” → “searching”
• run_command — elapsed-time heartbeat every 3s during long commands

LSP cold-start progress is not yet wired (would require a trait-wide change to the LSP provider interface — tracked for a future release).

Why this matters

Claude Code re-sends every MCP tool description and server-instruction block every turn with no delta caching on the client side. Codescout ships 22 tools. Shrinking descriptions and moving reference material into on-demand resources compounds into a significant per-turn token saving on long sessions, without losing any information the agent might need.

Tool Description Diet & Tool Guide Resource

Keeps every tool’s MCP description at ≤ 300 characters and exposes long-form usage notes on demand via the doc://codescout-tool-guide resource.

Motivation

The MCP tool list is sent to the LLM on every turn. Bloated descriptions waste context tokens with prose that is only occasionally useful. This feature separates what the tool does (short, always paid) from how to use it well (long, paid only when the agent asks).

Tool::long_docs()

A new optional method on the Tool trait:

#![allow(unused)]
fn main() {
fn long_docs(&self) -> Option<&str> { None }
}

Tools with long documentation override it. Currently populated for the five most complex tools: symbols, symbols, semantic_search, run_command, memory.

doc://codescout-tool-guide

A generated MCP resource that renders each registered tool’s long_docs() (or falls back to its short description()) into a single Markdown page.

Fetch it with:

resources/read doc://codescout-tool-guide

The guide is re-generated on every workspace(action: activate) call so it always reflects the current tool set.

Guard test

tool_descriptions_stay_under_budget in src/server.rs asserts that every registered tool’s description().len() <= 300. The test fails at compile time if a future tool exceeds the budget.

Tool Usage Doctor

The doctor://tool-usage MCP resource surfaces per-tool call statistics and prune candidates, so codescout maintainers can quantify what the current token-diet actually bought us and identify rarely-used tools for the next prompt-surface review.

Background

From docs/trackers/mcp-integration-ideas-2026-04.md idea #7: every tool description is re-sent to the LLM on every turn. Tools that almost never get called are pure context-window tax. Before pruning a tool we want to verify — with data — that it’s actually unused across sessions.

Reading the resource

Any MCP client can read the resource. Example over HTTP:

curl -s -X POST http://127.0.0.1:PORT/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/read",
       "params":{"uri":"doctor://tool-usage"}}'

Response shape

{
  "window": "30d",
  "low_call_threshold": 5,
  "total_calls": 4217,
  "tools": [
    {
      "name": "symbols",
      "calls": 1830,
      "errors": 4,
      "overflows": 12,
      "error_rate_pct": 0.22,
      "overflow_rate_pct": 0.66,
      "p50_ms": 18,
      "p99_ms": 210
    }
  ],
  "prune_candidates": ["symbol_at", "git_blame"],
  "unused_tools": ["register_library"]
}

Fields

Behaviour

• If usage.db doesn’t exist for the active project (fresh install), all counts are zero and every registered tool appears in unused_tools.
• The window is currently fixed at 30d. Future work: accept a query parameter to change it.
• prune_candidates uses a strict < comparison, so a tool called exactly low_call_threshold times is not flagged.
• Sorting: tools mirrors usage-DB ordering (descending calls). unused_tools is sorted alphabetically for deterministic output.

Typical workflow

1. Review the report monthly.
2. For every name in unused_tools: check if any known MCP client would ever plausibly use it. If not, consider unregistering.
3. For every name in prune_candidates: look at the p99_ms and error_rate_pct. Expensive + rarely-useful tools are the highest-value pruning targets.
4. When pruning a tool, update all three prompt surfaces (see CLAUDE.md § Prompt Surface Consistency) in the same commit.

librarian-mcp — workspace artifact registry

Codescout’s sister MCP server. Indexes markdown artifacts (specs, plans, runbooks, ADRs, memories, audits, handoffs, roadmaps, user docs) across every repo in a workspace, stores metadata + link graph in SQLite, and exposes MCP tools for finding, reading, linking, and packaging those artifacts as context.

Where codescout is project-scoped and code-shaped, librarian-mcp is workspace-scoped and artifact-shaped. Runs as a separate stdio MCP server — both can be wired into the same agent.

Installation

Ships as a sibling binary in the same Cargo workspace. Build with:

cargo build --release -p librarian-mcp

The binary lands at target/release/librarian-mcp.

One-time setup

1. Seed project registry. librarian-mcp reads a user-maintained TOML listing every repo to index. By default: ~/.codescout-registry.toml (or override via CODESCOUT_REGISTRY env). Format:

   [[projects]]
   name = "codescout"
   path = "/home/you/work/codescout"
   
   [[projects]]
   name = "backend"
   path = "/home/you/work/backend"
   

2. Generate workspace config. Run once:

   ./target/release/librarian-mcp import-codescout
   

   Writes ~/.config/librarian/workspace.toml with the seeded projects plus 9 default classification rules (spec / plan / memory / roadmap / adr / audit / handoff / runbook / doc).

3. Index. Populate the catalog:

   ./target/release/librarian-mcp reindex          # incremental
   ./target/release/librarian-mcp reindex --force  # wipe + rebuild
   

4. Wire into Claude Code:

   claude mcp add librarian-mcp /absolute/path/to/target/release/librarian-mcp
   

   Full Claude Code restart to surface the tools.

Tools

Filter AST

JSON tree ported from Redis agent-memory-server. Composition and / or / not. Leaf ops eq / ne / in / nin / gt / lt / gte / lte / contains. Example:

{"and": [
  {"kind": {"eq": "spec"}},
  {"status": {"in": ["active", "blocked"]}},
  {"tags": {"contains": "embedding"}}
]}

tags and owners are JSON-array columns — contains compiles to a json_each membership test, not LIKE.

Semantic search

Optional. Set LIBRARIAN_EMBED_MODEL to any model codescout supports (local via fastembed, remote via Ollama / OpenAI-compatible endpoint). On reindex, each artifact’s first chunk is embedded into sqlite-vec’s vec0 virtual table. artifact_find and librarian_context accept semantic: "<natural language>" and fall back to SQL LIKE when no embedder is configured.

Classification

Every indexed file passes through two sources of truth:

1. Frontmatter (authoritative if present) — kind, status, title, owners, tags, topic, time_scope.
2. Rule match on relative path — compiled glob patterns from workspace.toml under [[rule]].

When neither identifies a kind, the row lands as kind = "unknown" with confidence = 0.5. librarian_reindex reports the unknown ids so you can triage by adding rules or frontmatter.

Architecture

• codescout-embed — shared crate extracted from codescout. Provides the Embedder trait + local / remote clients + markdown chunker. Both codescout and librarian-mcp depend on it.
• crates/librarian-mcp — SQLite catalog (artifact / artifact_link / artifact_observation / artifact_vec), indexer, filter AST compiler, 11 MCP tools, stdio transport via rmcp.
• ~/.config/librarian/workspace.toml — roots + ignore globs + classification rules.
• ~/.local/share/librarian/catalog.db — SQLite database (override with LIBRARIAN_DB).

Known limits

• Indexing is on-demand via librarian_reindex or CLI. No file watcher.
• One vector per artifact (first chunk only). Chunk-level semantic search is not v1.
• artifact_update’s body patch replaces the entire body — no diff semantics.
• No central codescout project registry yet; import-codescout reads a user-maintained TOML.
• Title derivation falls back to the first # H1 when frontmatter has no title — files with neither land with title: null.

Related

• Spec: docs/superpowers/specs/2026-04-19-librarian-mcp-design.md
• Plan: docs/superpowers/plans/2026-04-19-librarian-mcp.md
• Credits: crates/librarian-mcp/CREDITS.md

Librarian (embedded in codescout)

librarian-mcp is no longer a standalone MCP server. It is embedded inside the codescout binary as an opt-in subsystem behind the librarian cargo feature, which is on by default in dev builds and off in --no-default-features production builds.

When active, the 15 librarian tools (artifact_*, librarian_*, workspace_state_at) are advertised alongside codescout’s core toolset and the librarian server instructions block is appended to codescout’s MCP instructions field.

Build-time control

# Cargo.toml
[features]
default = ["remote-embed", "http", "librarian"]
librarian = ["dep:librarian-mcp"]

# Dev build — librarian on
cargo build --release

# Production build — librarian compiled out, zero runtime cost
cargo build --release --no-default-features \
  --features remote-embed,http

Runtime override

Even with the feature compiled in, librarian registration is enabled by default. Opt out per session via env var, or per project via project.toml.

The env var wins; project.toml is consulted only when the env var is unset.

To opt out globally, set LIBRARIAN_ENABLED=0 in the codescout MCP server launch env (e.g. the env block of .mcp.json or your shell rc).

What you lose with librarian off

• The 15 librarian tools disappear from tools/list.
• The librarian instructions block is omitted from the MCP instructions field, so the LLM gets no hint that artifact tooling exists.
• The on-disk catalog (SQLite at $XDG_DATA_HOME/librarian/catalog.db) and workspace.toml are untouched — flipping the feature back on resumes where the previous session left off.

Opting out in production

Production users of codescout-as-MCP without a workspace.toml or a configured catalog can opt out via LIBRARIAN_ENABLED=0 to avoid the token overhead of the librarian tool descriptions. The cargo feature can also be compiled out entirely (--no-default-features) for a leaner production binary.

Default scope: project (not workspace)

All listing tools default to scope="project", returning only artifacts under the agent’s current sub-project. The current project resolves from cwd → nearest .git ancestor → workspace root from ~/.config/librarian/workspace.toml.

librarian_reindex follows the same default. A force-wipe under scope="project" only deletes rows whose rel_path starts with the current sub-project’s subdir — sibling projects under the same workspace root are preserved.

Read tools surface a scope block + hints (more_in_repo, more_in_workspace) so the LLM can widen on demand. Reindex echoes its scope and resolved targets in the response.

Per-project classifier overrides

Drop a <project>/.codescout/librarian.toml to declare classification rules for that project’s paths without touching the global ~/.config/librarian/workspace.toml. Schema matches the global file’s [[rule]] blocks. Rule precedence is project > workspace > built-in defaults, first-match-wins.

# <project>/.codescout/librarian.toml
[[rule]]
glob = "codescout/docs/reviews/**/*.md"
kind = "memory"
time_scope = "dated_snapshot"

[[rule]]
glob = "codescout/docs/agents/*.md"
kind = "doc"

Built-in defaults already cover common patterns: CHANGELOG.md, CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/QUICK-START.md, docs/concepts/**, docs/configuration/**, docs/experimental/**, docs/issues/** (tracker), docs/TODO-*.md (tracker), docs/review-*.md (memory, dated), **/prompts/*.md, src/**/prompts/*.md, crates/**/prompts/*.md. The override file is for project-specific patterns the defaults can’t reasonably guess.

Migration from standalone librarian-mcp

Earlier sessions ran librarian-mcp as a separate stdio MCP server. That binary no longer exists — crates/librarian-mcp is now lib-only. The codescout-companion plugin’s session-start hook no longer injects a separate librarian companion-hint block; the librarian instructions are served through codescout’s own instructions field.

~/.claude/.claude.json should have only one MCP server entry (codescout) with optional LIBRARIAN_EMBED_* envs:

{
  "mcpServers": {
    "codescout": {
      "type": "stdio",
      "command": "/abs/path/to/codescout",
      "args": ["start", "--debug"],
      "env": {
        "LIBRARIAN_EMBED_MODEL": "CodeRankEmbed",
        "LIBRARIAN_EMBED_URL": "http://localhost:43300/v1"
      }
    }
  }
}

Librarian Tools Collapse (16 → 5)

The 16 individual librarian tools have been collapsed into 5 action-dispatched tools, reducing MCP surface area and improving discoverability.

New tools

Usage

Every tool takes a required action parameter:

// Find active trackers
{"action": "find", "kind": "tracker", "status": "active"}

// Get one artifact with links
{"action": "get", "id": "abc123", "include_links": true}

// Append a note event
{"action": "create", "artifact_id": "abc123", "kind": "note", "payload": {"text": "..."}}

// Gather refresh context
{"action": "gather", "id": "abc123"}

// Pack context bundle
{"action": "context", "topic": "authentication"}

Migration

Old tool names are no longer registered. If you have saved prompts or scripts using the old names, update them:

• artifact_find {...} → artifact {action: "find", ...}
• artifact_get {...} → artifact {action: "get", ...}
• artifact_create {...} → artifact {action: "create", ...}
• artifact_update {...} → artifact {action: "update", ...}
• artifact_link {...} → artifact {action: "link", ...}
• artifact_graph {...} → artifact {action: "graph", ...}
• artifact_state_at {...} → artifact {action: "state_at", ...}
• artifact_event_create {...} → artifact_event {action: "create", ...}
• artifact_timeline {...} → artifact_event {action: "list", ...}
• artifact_refresh {...} → artifact_refresh {action: "gather", ...}
• artifact_refresh_stale {...} → artifact_refresh {action: "list_stale", ...}
• librarian_context {...} → librarian {action: "context", ...}
• librarian_reindex {...} → librarian {action: "reindex", ...}
• tracker_design {...} → librarian {action: "tracker_design", ...}
• workspace_state_at {...} → librarian {action: "workspace_state_at", ...}

doc://librarian-guide MCP Resource

A dense reference document for the librarian subsystem, surfaced as an MCP resource so agents can pull it on demand without consuming system-prompt tokens.

Usage

resources/read doc://librarian-guide

Returns a self-contained markdown guide covering:

• Artifact model — frontmatter fields, id, status, kind, tags, owners
• Filter syntax — leaf format {"field": {"op": value}} with composition (and/or/not)
• Tracker workflow — design → create → augment → refresh lifecycle
• Augmentation lifecycle — gather / commit_refresh / append_mode / history_cap
• Archiving / Moving — artifact(action="update", patch={status:"archived"}) and artifact(action="move")
• Common mistakes — filter format inversion, forgetting repo on create, direct file edits

Why pull it?

The system prompt references librarian tools but cannot include the full filter reference inline (token cost). When you encounter a complex artifact query, call resources/read doc://librarian-guide once to load the complete reference into context.

Source

src/prompts/librarian-guide.md — served directly from disk, always current.

artifact_refresh_stale

Discovery tool: surfaces augmented artifacts whose last refresh is older than a threshold. Returns them oldest-first (never-refreshed first) so the agent knows what to call artifact_refresh on next.

Schema

{
  "threshold_hours": 24,
  "limit": 10,
  "scope": "project"
}

All fields are optional.

Output

{
  "count": 2,
  "threshold_hours": 24,
  "items": [
    {
      "id": "abc123",
      "kind": "tracker",
      "title": "My Tracker",
      "rel_path": "codescout/docs/trackers/my-tracker.md",
      "last_refreshed_at": null,
      "refresh_count": 0,
      "age_hours": null
    }
  ],
  "next_step": "Call artifact_refresh(id) on each item..."
}

age_hours: null means never refreshed. Items ordered: never-refreshed first, then oldest last_refreshed_at ascending.

Typical workflow

artifact_refresh_stale(scope="repo")
→ pick item from list
artifact_refresh(id)
→ synthesize new content
artifact_update(id, { body: "..." })
artifact_refresh_commit(id)

Known limitations

• scope=umbrella is not supported (returns a recoverable error).
• Threshold is wall-clock time only — no per-artifact config yet.
• No priority weighting; ordering is strictly oldest-first.

artifact(action="move") — Atomic File Rename

Atomically renames a librarian-managed artifact file and updates the catalog’s rel_path in a single operation. Replaces the previous git mv + artifact(update, patch={rel_path:...}) + librarian(action="reindex") three-step sequence.

Usage

artifact(action="move", id="<16-hex>", new_rel_path="docs/archive/my-tracker.md")

Parameters

Response

{
  "id": "abc123def456abcd",
  "old_rel_path": "docs/trackers/my-tracker.md",
  "new_rel_path": "docs/archive/my-tracker.md",
  "moved": true
}

What it does

1. Resolves the artifact’s current file path from the catalog
2. Calls std::fs::rename (atomic on same filesystem)
3. Creates any missing parent directories at the destination
4. Updates rel_path, updated_at, file_mtime, and file_sha256 in the catalog

Git sees the rename automatically in git status — no extra git add needed.

Error cases

• Destination already exists → RecoverableError (no filesystem change)
• Unknown id → RecoverableError
• Destination on a different filesystem → OS-level rename error propagated

When to use

Use artifact(action="move") whenever you need to reorganize a tracker or archive it to a different directory. Do not use git mv or fs::rename directly — those leave the catalog stale until the next reindex.

tracker_design

Teaching tool that guides tracker creation. Call it before tracker_create whenever the user asks to create a tracker.

What it returns

{
  "design_version": "1",
  "system_prompt": "...",   // 7-step design guide
  "archetypes": [...],       // 6 archetype definitions
  "existing_trackers": [...],// current trackers in catalog (cap 30)
  "next_step": "..."
}

The 7 steps

1. Pick an archetype — match intent to one of 6 archetypes.
2. Write the augmentation prompt — imperative, names sources, states conflict resolution.
3. Design params — live state only, flat, stable keys.
4. Decide schema discipline — loose early, lock when mature.
5. Compose render_template — MiniJinja projecting params to markdown.
6. Sketch body skeleton — prose sections + History block.
7. Check for collisions — existing_trackers prevents duplicate concerns.

Archetypes

Each archetype ships with params_shape_example, params_schema_example, render_template_example, body_skeleton, and prompt_template.

Usage

tracker_design()                    // load guide + landscape
→ pick archetype, compose spec
tracker_create(repo, rel_path, title, prompt, params, ...)

Pass intent to tracker_design for future tailoring (reserved, currently echoed back in the response).

Known limitations

• existing_trackers is capped at 30 entries (scope=repo).
• intent field is reserved; no tailoring is applied yet.

workspace_state_at — Time-Travel Workspace Snapshot

The workspace_state_at tool returns a snapshot of every artifact in scope as it stood at a given commit or timestamp, with a per-artifact comparison of freshness_at_as_of (freshness replayed up to the cutoff) vs freshness_now (freshness from current state).

Use cases

• “What was stale at the time of release v2.3?”
• “Which specs were unreviewed when we cut the RC?”
• “Show me everything that has become stale since the last review round.”

Parameters

Response shape

{
  "as_of": 1714300000000,
  "scope": { "scope": "all", ... },
  "artifacts": [
    {
      "id": "specs/auth-redesign",
      "kind": "spec",
      "status_at_as_of": "active",
      "freshness_at_as_of": "stale",
      "freshness_now": "fresh",
      "freshness_changed": true,
      "latest_event_at_as_of": { "id": "...", "kind": "reviewed", "created_at": 1714200000000 },
      "supersession_chain": [],
      "rel_path": "specs/auth-redesign.md",
      "repo": "my-repo"
    }
  ],
  "hints": {
    "scope_fallback": false,
    "more_in_scope": 42,
    "hint": "Result capped at 200. Narrow with `kinds`, `freshness_filter`, or a tighter scope."
  }
}

Cap behaviour

Results are capped at 200 artifacts. When more candidates exist, hints.more_in_scope reports the total excess and hints.hint suggests how to narrow the query.

Freshness semantics

• freshness_at_as_of — computed by replaying only events with created_at ≤ cutoff. This is the true historical freshness.
• freshness_now — computed from all events without a cutoff (current state). Uses file_mtime from the current artifact row in both cases.
• freshness_changed = true when the two values differ — the most interesting signal for “what has drifted since commit X?”

Augmentation: render_template + params_schema

Two optional fields on augmented artifacts that decouple live state (params) from narrative (artifact body).

render_template

A MiniJinja template projecting params into a markdown snippet injected under the [LIVE] header in librarian_context output. Set it when you want a status table, flag grid, or F-N row list that the agent can read without parsing raw JSON.

Common patterns

{# Table from an array #}
| id | status | owner |
|----|--------|-------|
{% for f in failures %}| {{ f.id }} | {{ f.status }} | {{ f.owner or "—" }} |
{% endfor %}

{# Dict iteration #}
{% for env, s in envs|items %}{{ env }}: {{ "✅" if s.enabled else "❌" }}
{% endfor %}

{# Filtered count #}
{{ items|selectattr("status","equalto","fail")|list|length }} failing

Schema

Pass render_template to artifact_augment or artifact_update_params:

{
  "render_template": "**Flag:** `{{ flag_name }}`\n..."
}

Behaviour

• Evaluated at librarian_context read time against current params.
• Errors in template evaluation are surfaced inline (not fatal).
• Omit the field for reflective trackers — prose-only body needs no template.

params_schema

A JSON Schema (draft-07+) validating params on every write: artifact_augment (initial seed) and artifact_update_params merges. Violations return a recoverable error — params are not written.

When to use

• Early life: omit or use additionalProperties: true. Let the shape settle over 2-3 refreshes.
• Mature: add required, enum, pattern constraints to lock drift out.

Example

{
  "params_schema": {
    "type": "object",
    "required": ["failures"],
    "properties": {
      "failures": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["id", "status"],
          "properties": {
            "id":     { "type": "string", "pattern": "^F-\\d+$" },
            "status": { "type": "string", "enum": ["fail","pass","flaky","wontfix"] }
          }
        }
      }
    }
  }
}

Known limitations

• Template is re-evaluated on every librarian_context call — no caching.
• Schema validation uses draft-07 semantics; newer keywords are ignored.

LSP Idle TTL Eviction

codescout starts LSP servers on demand and keeps them running for fast symbol lookups. A server that has been idle beyond its timeout is shut down automatically to reclaim memory.

Default timeouts

Kotlin gets a longer TTL because its LSP server has a long startup time — evicting it aggressively would cause noticeable latency on the next query.

Behaviour

When an LSP server’s idle TTL expires:

1. codescout sends a shutdown request and exit notification to the server.
2. The server process is removed from the pool.
3. On the next symbol request for that language, a new server is started automatically.

There is no user-visible interruption — the eviction and restart are transparent.

Configuration

TTL eviction is not yet configurable via project.toml. This is planned for a future release.

Memory

Memory gives codescout persistent, project-scoped storage that outlives any single conversation. Notes written in one session are available in every future session — the agent accumulates knowledge about a codebase over time rather than rediscovering the same things repeatedly.

The Problem It Solves

Without persistent memory, every new session starts from scratch. The agent has to re-read CLAUDE.md, re-run onboarding, and re-discover facts it already knew: which module handles authentication, where the main entry point is, what convention the project uses for error types. This re-discovery burns time and context window on every session.

With memory, the agent writes a note the first time it discovers something non-obvious. Every subsequent session reads that note immediately and skips the rediscovery entirely.

Storage Layout

Memories are plain Markdown files in .codescout/memories/:

.codescout/memories/
  architecture.md
  conventions/
    error-handling.md
    naming.md
  debugging/
    lsp-timeouts.md

Topics with forward slashes map to subdirectories. You can version-control memory files alongside code, or keep them local.

Typical Workflow

At the start of a session:

1. Call onboarding — it lists existing memories and skips heavy discovery if memories are already written
2. Call memory(action: "read", topic: ...) for topics relevant to the current task

During a session: 3. Call memory(action: "write", topic: ..., content: ...) when you discover something worth remembering — a naming convention, an architectural decision, a gotcha

At the end of a session: 4. Call memory(action: "write", ...) to update entries if your understanding changed

What Makes a Good Memory Entry

Good candidates:

• Architectural decisions — why a module is structured a certain way
• Naming conventions — patterns used throughout the codebase that aren’t obvious from reading one file
• Debugging insights — root causes of tricky issues, non-obvious interactions
• Entry points — which file/function to start from for a given concern
• Gotchas — behaviours that surprised you and would surprise the next session

Avoid:

• Things obvious from reading the code
• Things that change so frequently the memory goes stale immediately
• Duplicating information already in CLAUDE.md

Onboarding Integration

The onboarding tool automatically writes a summary entry under the topic "onboarding". This entry contains language detection results, detected entry points, and a system prompt draft for the routing plugin. You do not need to write it manually.

Further Reading

• Memory Tools — full reference for memory(action: "read/write/list/delete/remember/recall/forget/refresh_anchors")
• Dashboard — the Memories page lets you browse and edit topics in a browser UI
• Workflow & Config Tools — onboarding integrates with memory at session start

After Onboarding: Slimming Your Config File

Running onboarding for the first time writes memories for architecture, entry points, conventions, and gotchas. Many projects also have a hand-written config file — CLAUDE.md, AGENTS.md, .cursorrules, or .github/copilot-instructions.md — that predates codescout and repeats a lot of the same information.

Keeping both is redundant. Every session the agent reads the config file eagerly (full cost, always) and then reads memories on demand. When the same fact lives in both places, you pay for it twice and get two sources of truth that can drift apart.

This page walks through how to trim your config file after onboarding so it carries only what it should.

What belongs where

The rule of thumb: if a fact describes how the codebase is built, it belongs in memory. If it describes how you want the agent to behave, it belongs in the config file.

The audit workflow

After onboarding completes, ask the agent to do a one-time audit:

Now that codescout memories are written, please audit CLAUDE.md:
1. List all memory topics with `memory(action: "list")`
2. Read each topic with `memory(action: "read", topic: "...")`
3. For each block in CLAUDE.md that is fully covered by a memory, either delete it
   or replace it with a one-line reference: "See codescout memory '<topic>'"
4. Keep anything that is a workflow rule or behavior instruction

The agent will compare each section against the memory store and propose edits. Review and apply.

Example: before and after

Before (verbose, duplicated in memory):

## Project Structure

The main entry point is `src/main.rs`. The server is wired in `src/server.rs` via
`CodeScoutServer::from_parts`, which registers all 29 tools. Tools are implemented in
`src/tools/` grouped by category. The `Agent` struct in `src/agent.rs` holds project
state and is accessible to all tools via `ctx.agent`. Error routing goes through
`route_tool_error` in `src/server.rs`: `RecoverableError` maps to `isError: false`,
all other errors to `isError: true`.

After (slim, memory carries the detail):

## Architecture

See codescout memory "architecture".

Or if the memory coverage is complete, delete the section entirely and trust the agent to read the memory at session start.

Per-agent config file names

The audit workflow is the same regardless of which file your agent uses.

When to repeat the audit

• After adding a significant new module or subsystem (onboarding will have written new memories — check if the config file still duplicates them)
• After onboarding a multi-project workspace (each project gets its own memories; workspace-level config can often shed per-project sections entirely)
• When context window pressure becomes noticeable — a bloated config file is often the first place to reclaim tokens

Further reading

• Memory — what makes a good memory entry and the full memory tool reference
• Onboarding — what onboarding writes and when to re-run it
• Multi-Project Workspace — per-project memory scoping in workspace setups

Memory Sections Filter

memory(action="read") now accepts a sections parameter that returns only the ### Heading blocks you need, instead of the full memory file.

Usage

{
  "action": "read",
  "topic": "language-patterns",
  "sections": ["Rust", "TypeScript"]
}

The response contains the file preamble (text before the first ### heading) plus each matched section in file order. Heading matching is case-insensitive.

Why this matters

Large memory files like language-patterns can hold hundreds of lines across many languages. Passing sections slashes context cost when you only need one language’s patterns — the server does the filtering before the result reaches the model.

Parameters

Return value

When sections is supplied and at least one heading matches, the response contains the filtered content. When a heading is requested but not found, a RecoverableError is returned that lists:

• missing — requested section names that had no match.
• available — all section headings present in the file, so you can correct the call.

{
  "error": "sections not found: [\"Go\"]",
  "missing": ["Go"],
  "available": ["Rust", "TypeScript", "Python"]
}

Limitations

• Only ### (H3) headings are treated as section boundaries. ## and # headings are part of the preamble or carried inside a section body.
• Sections are returned in file order, not request order.
• The filter applies to topic-based reads only (action="read"). Semantic recall (action="recall") is unaffected.

Dashboard

The dashboard is a local web UI that gives you a live view of your project’s health, tool usage, and memories. It runs as a separate process — no MCP server, no LSP, no tool machinery — just the data already on disk in .codescout/.

codescout dashboard --project .
# opens http://127.0.0.1:8099

Pages

Overview

Project health at a glance:

• Project — root path, detected languages, entry points
• Configuration — active settings from .codescout/project.toml
• Semantic Index — chunk count, last-indexed commit, staleness relative to HEAD
• Drift — files with high semantic drift since last index (files where meaning changed significantly, not just bytes)
• Libraries — registered third-party libraries and their index status

Tool Stats

Usage telemetry for every tool call the MCP server has handled:

• Summary — total calls, error rate, overflow rate for the selected window
• Calls by Tool — bar chart ranked by call volume
• Per-Tool Breakdown — table with calls, errors, Err%, overflows, Ovf%, p50 and p99 latency
• Recent Errors — last N errors with full input/output, searchable and collapsible by duplicate group

The time window selector covers 1h / 24h / 7d / 30d and updates all panels simultaneously.

Memories

Read and edit the project’s persistent memory store directly in the browser:

• Browse topics in the sidebar
• View raw markdown content
• Create, update, or delete topics without touching the filesystem manually

Options

codescout dashboard --project . --port 9000

Notes

• The dashboard reads .codescout/ directly; the MCP server does not need to be running
• Static assets (HTML, CSS, JS) are embedded in the binary — no separate serving step
• Theme toggle (light/dark) persists across page loads via localStorage

Further Reading

• Memory Tools — the memory tool that backs the Memories browser
• Semantic Search Tools — workspace(action: status) is the data source for the index health and drift panels on the Overview page
• Workflow & Config Tools — usage data from .codescout/usage.db backs the Tool Stats page
• Project Configuration — the Overview page shows your active configuration from .codescout/project.toml

LSP Startup Statistics

codescout records LSP cold-start timing to .codescout/usage.db and surfaces it in the project dashboard under “LSP Startup”.

What is recorded

Each cold start records:

• Language — which LSP server was started
• Reason — new_session, idle_evicted, lru_evicted, or crashed
• Handshake duration — time for the LSP initialize round trip
• First response duration — time for the first real tool request (symbols, hover, etc.)

Viewing the data

Open the dashboard (codescout dashboard --project .) and look for the “LSP Startup” section. It shows per-language averages/p95 and a recent event list.

Limitations

• first_response_ms may be null if no tool call followed the cold start in the same server process.
• Events are only recorded when the project root is known at startup time.

Git Worktree Support

The Core Problem

Claude Code’s EnterWorktree creates an isolated git worktree for feature work, and the shell’s working directory moves into it. The MCP server does not follow.

codescout’s project root is set when the server starts (or when workspace(action: activate) is called). It has no visibility into where the shell is currently pointed. So after EnterWorktree, write tools — edit_file, create_file, edit_code — are still targeting the main repo. The AI writes to the wrong tree, silently, with no error, because the path is valid in both contexts.

The Fix: workspace(action: activate)

After EnterWorktree, always call workspace(action: activate) with the absolute worktree path before doing any writes:

workspace(action: activate, path: "/abs/path/to/.claude/worktrees/my-feature")

All subsequent reads, writes, symbol navigation, and shell commands then target that tree. Switch back to the main repo when done:

workspace(action: activate, path: "/abs/path/to/main-repo")

Layer 1 — Write Guard (Hard Block)

If the AI enters a worktree but hasn’t called workspace(action: activate), write tools detect the mismatch and raise a hard error rather than silently writing to the wrong place. The error message lists the detected worktree paths and the exact workspace(action: activate) call needed to unblock.

Layer 2 — Navigation Exclusions

Worktree directories (.claude/worktrees/, .worktrees/) are excluded from tree (with glob) and tree results. Without this, file searches and directory listings in the main project would surface duplicate copies of every source file from every active worktree — polluting navigation and confusing symbol lookups.

Cleanup Gotcha

git worktree remove <path> requires the directory to still exist. If the worktree directory was already deleted (e.g. by the agent or a cleanup script), worktree remove will fail. The correct command for an already-gone directory is:

git worktree prune

Run this from the main repo root, not from inside the (now-deleted) worktree.

Plan Execution Gotcha: Start a New Session in the Worktree

When using a workflow like Superpowers writing-plans and choosing the Parallel Session option, don’t try to launch executing-plans from the same session that created the worktree. The EnterWorktree + workspace(action: activate) dance is easy to miss, and subagents spawned from the current session won’t automatically inherit the right project root.

The cleanest approach — one that sidesteps all of this — is:

cd /path/to/.worktrees/<feature-branch>
claude

Open a new terminal, cd into the worktree, and start Claude there. The session is rooted in the worktree from the first message. No workspace(action: activate) call needed, no stale context from the planning session, no risk of writes going to the main repo.

Other approaches can work, but this one always does.

Further Reading

• Superpowers Workflow — how the Superpowers plugin integrates worktrees into a full TDD + parallel-agent development workflow
• Workflow & Config Tools — workspace(action: activate) reference: the required call after entering a worktree

Security & Permissions

codescout is designed to be safe to run autonomously: an agent can explore any codebase it needs to understand, but it cannot write outside its current project without explicit opt-in. This page explains the model, the defaults, and the configuration knobs.

The Core Model

The permission model is asymmetric by design:

This asymmetry is intentional. An agent doing code intelligence work legitimately needs to read widely — library source, system headers, adjacent repositories. But writes touching unrelated projects or system files would be a serious mistake. The boundary keeps agents capable and safe simultaneously.

Why Write Restriction Matters for Agents

When an agent runs autonomously with multiple parallel tool calls in flight, a write-boundary violation produces a RecoverableError — not a fatal crash. This means:

• The agent receives a clear error message and a corrective hint
• Sibling parallel tool calls are not aborted — the rest of the work continues uninterrupted
• The user is never asked to intervene mid-task for a permissions issue

Writes outside the project root are blocked, not just warned about. This is intentional: the boundary needs to be hard for the safety guarantee to hold.

Read Policy

read_file, grep, tree (with glob), and all symbol tools can read from any path on the filesystem, subject to one restriction: the built-in deny list.

Built-in Read Deny List

These locations are always blocked, regardless of configuration:

~/.ssh
~/.aws
~/.gnupg
~/.config/gcloud
~/.config/gh
~/.docker/config.json
~/.netrc
~/.npmrc
~/.kube/config

On Linux, /etc/shadow and /etc/gshadow are also blocked. On macOS, /etc/master.passwd is blocked.

This list cannot be overridden. It exists to prevent an agent from accidentally leaking credentials even if pointed at a project that tries to read them.

Extending the Deny List

To block additional paths specific to your environment, add them to project.toml:

[security]
denied_read_patterns = [
    "~/.config/my-app/credentials",
    "/etc/internal",
]

Entries are prefix-matched, so "~/.config/my-app" blocks everything under that directory.

Write Policy

create_file, edit_file, and edit_code (all actions — replace, insert, remove, rename) enforce a project root boundary. The check happens before any I/O:

1. Deny list first — the target path is checked against the built-in deny list and denied_read_patterns. Even extra_write_roots cannot bypass this.
2. Boundary check — the canonicalized path must fall under the project root or an explicitly configured extra_write_roots entry.
3. Symlink escape prevention — the parent directory is canonicalized (not the target file, which may not exist yet), so symlinks pointing outside the root are caught.

Allowing Writes Outside the Project Root

For multi-repo setups where the agent legitimately needs to write across repositories, add the target directory to extra_write_roots:

[security]
extra_write_roots = [
    "/home/user/other-project",
]

The deny list still applies first. extra_write_roots only extends where writes land — it cannot unlock credential paths.

Disabling Writes Entirely

For read-only sessions:

[security]
file_write_enabled = false

Shell Policy (run_command)

Shell execution is disabled by default and requires explicit opt-in:

[security]
shell_enabled = true
shell_command_mode = "warn"   # or "unrestricted"

Both fields must be set. The two-field design lets you grant shell access while keeping a reminder in every response ("warn"), which is recommended for shared or CI environments.

Shell Sandbox

Even with shell enabled, the cwd parameter is restricted to subdirectories within the project root — path traversal (../) is rejected. The shell command itself is unrestricted (it can reference any absolute path), but the working directory anchor is always the project.

Dangerous commands (rm -rf, dd, mkfs, etc.) require acknowledge_risk: true to run. See Workflow & Config for the full list.

Per-Tool Switches

Individual feature categories can be toggled independently:

[security]
file_write_enabled = true    # create_file, edit_file, symbol writes
shell_enabled      = false   # run_command
indexing_enabled   = true    # index(action: build), workspace(action: status)

Disabling a category returns a RecoverableError with a hint explaining which config field to set — the agent understands why it was blocked without user intervention.

Summary

• Reads: anywhere except the built-in credential deny list
• Writes: project root only, by default — hard boundary, not a warning
• Shell: off by default; two-field opt-in; cwd sandboxed to project
• Violations: RecoverableError → agent gets a hint, no user interruption, no sibling call cancellation

→ Configuration reference: [security] → Troubleshooting access errors

Security Profiles

codescout now supports a profile field in the [security] section of .codescout/project.toml. The profile controls how strictly path validation and shell command safety checks are enforced.

Profiles

default (standard sandbox)

This is the profile used when no profile key is present.

• Read deny-list active — system paths (.ssh/, /etc/passwd, etc.) are blocked regardless of the calling tool.
• Writes restricted to the project root and the system temp directory. Additional directories can be added via extra_write_roots.
• Dangerous shell commands (e.g. rm -rf, dd, mkfs) require acknowledge_risk: true in run_command.

root (unrestricted)

For system-administration projects that legitimately need full filesystem access.

• No read deny-list — any path readable by the OS user can be read.
• Writes allowed anywhere the OS user has permission.
• Dangerous command check bypassed — run_command executes without a speed bump.

Source-file shell access guidance (prefer read_file/symbols over cat) remains active in both profiles. It improves tool output quality, not security.

Configuration

Add a [security] section to .codescout/project.toml:

[security]
profile = "root"

The default value is "default" — omitting the field is equivalent to profile = "default".

When to use root mode

Only switch to root if your project genuinely needs it:

• System administration scripts that read /etc, /var, or write outside the project tree.
• Dotfile managers, backup tools, or package managers where restricting paths would prevent the tool from functioning.

For regular application development, keep profile = "default". The sandbox prevents accidental reads of SSH keys or credential files and catches destructive shell commands before they run.

Limitations

• The profile is per-project, not per-tool. There is no way to lift the sandbox for a single tool call.
• profile = "root" does not bypass OS-level permissions — codescout can still only access paths the running user is allowed to read or write.

Compact Tool Schemas & workspace(action: activate) Safety

Two related improvements land together: tool schema descriptions were trimmed by ~24% (~1,763 tokens), and a new Iron Law + server guidance was added for safe cross-project navigation with workspace(action: activate).

Compact tool schemas

Parameter descriptions in all tool schemas previously repeated usage guidance that already lives in server_instructions.md. They now answer only “what is this parameter?” — not “how should you use the tool?”. The system prompt is the right place for workflow guidance; schemas are for type/shape information.

Net effect: ~1,763 fewer tokens injected on every MCP request, partially offset by ~448 tokens added for the new Iron Law. Net saving across a typical session is significant since server_instructions.md is injected on every tool call.

workspace(action: activate) safety — Iron Law #4

A new Iron Law was added to server_instructions.md:

ALWAYS RESTORE THE ACTIVE PROJECT. After workspace(action: activate) to a different project, you MUST workspace(action: activate) back to the original before finishing your task. The MCP server is shared state — forgetting to return silently breaks all subsequent tool calls for the parent conversation.

Cross-project navigation patterns

Two patterns are now documented and enforced via anti-pattern guidance:

Subagents are especially risky — they share the MCP server instance with their parent conversation. A subagent that calls workspace(action: activate) and exits without restoring leaves the parent’s subsequent tool calls operating against the wrong project root, with no error.

workspace(action: activate) response hint

When switching away from the home project, the workspace(action: activate) response now includes a reminder to restore:

Active project: other-project (/path/to/other)
⚠ You switched away from home-project. Remember to workspace(action: activate) back when done.

Workspace system prompt

build_system_prompt_draft (the generated per-project system prompt) now includes a cross-project navigation section when the workspace has more than one project registered. This ensures the guidance is present in project-specific contexts, not just the global server instructions.

PostCompact Hook — LSP Cache Flush

After Claude Code compacts the context window, cached LSP symbol positions can become stale: the LSP server still holds the old line numbers from before compaction, and the next navigation call may resolve to the wrong location.

This feature adds a two-part fix:

Server side: workspace(action: status, post_compact: true)

workspace(action: status) accepts a new boolean parameter post_compact. When true, all active LSP clients are shut down immediately and the call returns early:

{ "flushed": true, "hint": "LSP position caches cleared. Clients restart automatically on the next navigation call..." }

LSP clients restart lazily on the next symbol_at or references call — there is no manual restart step and no disruption to the session. The normal status fields (project_root, languages, etc.) are not included in the flush response.

Plugin side: PostCompact hook

The companion plugin (codescout-companion) adds a PostCompact hook that fires automatically after every context compaction. Because hooks run outside the MCP transport and cannot call tools directly, the hook injects an additionalContext directive:

codescout PostCompact: context was compacted.
→ Call workspace(action: status, post_compact: true) as your FIRST action to flush stale LSP position caches.
   LSP clients restart lazily — no disruption to the session.

The agent sees this as the first message of the new turn and calls workspace(action: status, post_compact: true) before any navigation work.

When is this useful?

Long coding sessions where the context is compacted mid-task — especially when there are open LSP-backed files (Rust, TypeScript, Kotlin) and the agent immediately needs accurate symbol_at results after compaction.

Upgrade path

Requires:

• codescout ≥ 0.4.1 (server-side post_compact parameter)
• codescout-companion plugin with the PostCompact hook registered in hooks/hooks.json

Cross-Process Write Serialization

When multiple codescout MCP server instances run against the same project directory simultaneously (e.g. two IDE windows, two Claude Code sessions, or a background indexer alongside an active session), write-tool calls are now serialized so they cannot corrupt each other.

How It Works

Two lock layers protect each write:

1. In-process mutex — tokio::sync::Mutex<()> per ActiveProject. Acquired first. Serializes concurrent write-tool calls within a single codescout process.
2. Cross-process flock — fs4 advisory lock on .codescout/write.lock. Acquired second. Serializes writes across all codescout instances on the same project.

The lock is held for the full duration of the tool call and released on drop (WriteGuard RAII).

Behavior on Contention

If a write-tool call cannot acquire the cross-process lock within the timeout, it returns a RecoverableError (MCP isError: false). The agent receives a message:

another codescout instance is writing to this project
Retry in a moment — the holder should release shortly.

Because isError is false, sibling tool calls in the same MCP batch continue normally.

Configuration

Set write_lock_timeout_secs in .codescout/config.toml under [security]:

[security]
write_lock_timeout_secs = 10  # default: 5

Covered Write Tools

The following tools acquire the write lock: create_file, edit_file, edit_markdown, edit_code, and memory write actions (write, remember, forget, delete, refresh_anchors).

Read tools (read_file, symbols, symbols, etc.) skip the lock entirely — no overhead on reads.

Lock File

The lock file lives at .codescout/write.lock inside the project root. It is created automatically on workspace(action: activate) and is gitignored.

Routing (codescout-companion Plugin)

Why It Exists

The MCP server delivers 28 tools and a detailed server_instructions block that tells the AI when to use each one. In a single-agent session this works well — the main agent receives the instructions and generally follows them.

The problem is subagents.

Every time Claude Code spawns a subagent (a code reviewer, a parallel worker, a debugging agent), that subagent starts with a blank slate. It has the MCP tools available, but it has never seen the server_instructions. Its default instinct is to reach for the native tools it was trained on: Read, Grep, Glob, Bash cat. Without intervention it will happily read whole files, grep walls of text, and never touch symbols or semantic_search.

The codescout-companion plugin exists to close that gap. It injects guidance into every agent and every subagent, and hard-blocks the native tool patterns that codescout is designed to replace.

How It Integrates with the MCP Server

The plugin is intentionally tightly coupled to codescout:

• It reads codescout’s SQLite embeddings DB to check index staleness and surface drift warnings at session start
• It calls the codescout CLI binary to trigger background reindexing when the index is behind HEAD
• It injects the .codescout/system-prompt.md file — generated by the onboarding() tool — verbatim into every agent’s context. This file contains project-specific navigation hints, entry points, and memory pointers that onboarding() tailored to the codebase.

The plugin should be updated whenever codescout adds features that affect exploration workflows.

Hooks

Why Hard Blocks, Not Soft Warnings

The plugin went through a soft-warning phase (v1.1–v1.4): a PostToolUse hook would fire after a Read or Grep call and append a message suggesting codescout alternatives. This did not work.

By the time the PostToolUse hook fires, the tool output is already in context. The AI has the file contents or grep results it was looking for — the warning is noise it ignores, and the damage (token waste, context pollution) is already done.

Switching to PreToolUse hard blocks (v1.5) fixed this. The block fires before the tool executes. No output lands in context; the AI is forced to re-plan with a codescout tool instead. This is the approach that actually changes behaviour.

The Subagent Coverage Problem

SubagentStart guidance (v1.5.3) always fires, even when .codescout/system-prompt.md doesn’t exist. Before this fix, the hook silently exited when the file was absent — leaving subagents (code reviewers, design agents, parallel workers) with no guidance at all. The result was that subagent behaviour was completely inconsistent: the main agent used codescout correctly, subagents fell back to native tools immediately.

The fix was simple: always inject a minimal tool-use directive into subagents, regardless of whether a project-specific system prompt exists.

Auto-Reindex and Drift Warnings

At SessionStart, the plugin checks whether the semantic index is behind HEAD:

1. Queries the embeddings DB for the last-indexed commit
2. Compares against git rev-parse HEAD
3. If stale, triggers codescout index --project . in the background (non-blocking)
4. If high-drift files are detected (files where meaning changed significantly since last index), surfaces a warning in the session context

This means the index is usually up to date by the time the AI needs it, without requiring a manual index(action: build) call.

Installation

/plugin marketplace add mareurs/sdd-misc-plugins
/plugin install codescout-companion@sdd-misc-plugins

See the Routing Plugin setup guide for configuration options.

Further Reading

• Routing Plugin Setup Guide — installation steps, configuration options, and verification
• Superpowers Workflow — the Superpowers plugin that pairs with codescout-companion for full lifecycle development

Superpowers Workflow

What Is Superpowers

Superpowers is a Claude Code plugin that wraps the full development lifecycle in composable skills that trigger automatically. Rather than jumping straight into code, Claude steps back, clarifies requirements, writes a spec, produces a detailed implementation plan, then executes it task by task via subagents — each with two-stage review (spec compliance, then code quality).

The core skill chain:

1. brainstorming — refines rough ideas, explores alternatives, validates design
2. using-git-worktrees — creates an isolated workspace on a new branch
3. writing-plans — breaks the design into 2–5 minute tasks with exact file paths and verification steps
4. subagent-driven-development / executing-plans — dispatches fresh subagents per task, or works in human-checkpoint batches
5. finishing-a-development-branch — merges, creates a PR, or discards; cleans up the worktree

The Manual Worktree Workflow

For large implementation plans — or when working on two or three separate issues on the same repo simultaneously — the safest approach is to skip EnterWorktree entirely and do it manually:

# create the worktree on a new branch
git worktree add .worktrees/my-feature my-feature

# cd into it and launch Claude from there
cd .worktrees/my-feature
claude

Claude starts with its CWD already set to the worktree. The MCP server needs one workspace(action: activate) call to follow:

workspace(action: activate, path: "/abs/path/to/.worktrees/my-feature")

After that, every read, write, and shell command targets the worktree automatically — no EnterWorktree inside the session, no risk of writing to the main repo, no mid-session project-switch to forget.

Why this beats EnterWorktree inside a running session:

• The session CWD matches the project root from the start — there’s no window where writes could land in the wrong tree
• You can run multiple independent Claude sessions in parallel, each in its own worktree, each working a different branch of the same repo
• The terminal tab itself is the isolation boundary — clear, auditable, easy to kill

Running Parallel Sessions

When a plan is large and there are also 2–3 smaller issues to knock out at the same time, parallel worktrees let you do all of it concurrently:

# terminal 1 — big feature
git worktree add .worktrees/big-feature big-feature
cd .worktrees/big-feature && claude

# terminal 2 — hotfix
git worktree add .worktrees/hotfix-auth hotfix-auth
cd .worktrees/hotfix-auth && claude

# terminal 3 — docs update
git worktree add .worktrees/docs-update docs-update
cd .worktrees/docs-update && claude

Each session is fully isolated. They share the object store (fast) and can see each other’s commits once pushed, but their working trees never interfere.

The Prune Bug in finishing-a-development-branch

When the finishing-a-development-branch skill cleans up, it runs:

git worktree remove <worktree-path>

This works when Claude was launched from the main repo and entered the worktree via EnterWorktree. It fails when you launched Claude from inside the worktree — because git worktree remove refuses to remove a worktree whose path is the current working directory of any running process.

The symptom: the skill completes the merge or PR, then hangs or errors on cleanup, leaving a stale worktree entry in .git/worktrees/.

The correct cleanup command when CWD is inside the worktree:

# from the main repo — NOT from inside the worktree
git -C /abs/path/to/main-repo worktree prune

git worktree prune doesn’t require the directory to exist or to be reachable as CWD — it just reconciles .git/worktrees/ against what’s actually on disk. If the worktree directory was already deleted (by the skill or manually), prune clears the stale entry cleanly. git worktree remove cannot do this.

Practical fix: After a session that was launched from inside a worktree, if cleanup fails, exit back to the main repo and run git worktree prune manually. The branch itself may need a separate git branch -d my-feature if you want it gone entirely.

Further Reading

• Git Worktrees — two-layer protection (write guard + navigation exclusions) that prevents silent cross-worktree edits
• Routing Plugin — how the plugin’s worktree-activate.sh hook auto-calls workspace(action: activate) when EnterWorktree fires

Project Configuration

Every project managed by codescout has an optional configuration file at .codescout/project.toml. The file uses TOML syntax.

File Location and Auto-Creation

The file lives at:

<project-root>/.codescout/project.toml

If the file does not exist when a project is first activated, codescout creates it with sensible defaults derived from the directory name. You can also create it manually before activating a project.

The configuration is loaded by ProjectConfig::load_or_default: if the file is present it is parsed, otherwise defaults are applied. All sections except [project] are fully optional — omit any section and its defaults take effect silently.

[project] — General Settings

[project]
name = "my-service"
languages = ["rust", "toml", "markdown"]
encoding = "utf-8"
tool_timeout_secs = 60

Note: languages is populated by the onboarding tool and written back to the config file. You rarely need to set it by hand.

[embeddings] — Semantic Search Settings

Controls which embedding model is used and how source files are chunked before embedding.

[embeddings]
model = "ollama:mxbai-embed-large"
drift_detection_enabled = true

Note — chunk size is automatic. codescout derives the chunk budget directly from the model’s published context window using a conservative max_tokens × 3 chars/token formula at 85 % utilisation. There is no chunk_size or chunk_overlap setting — they were removed because manual tuning was error-prone and the model string already encodes everything needed. Existing project.toml files containing these keys are silently ignored.

Changing the model after indexing: If you change model, you must rebuild the index (index(action: build) with force: true). codescout detects model mismatches and will warn rather than return wrong results.

[ignored_paths] — Indexing Exclusions

Glob patterns for directories and files that should be excluded from semantic search indexing, tree, and file traversal.

[ignored_paths]
patterns = [
    ".git",
    "node_modules",
    "target",
    "__pycache__",
    ".venv",
    "dist",
    "build",
    ".codescout",
]

The default list covers common build artifact and dependency directories. To add your own exclusions, replace the entire patterns array — there is no “append” mode:

[ignored_paths]
patterns = [
    ".git",
    "node_modules",
    "target",
    "__pycache__",
    ".venv",
    "dist",
    "build",
    ".codescout",
    "vendor",
    "generated",
    "*.pb.go",
]

[security] — Access Controls

See Security & Permissions for the rationale behind these settings and how the permission model works end-to-end.

Controls what operations the AI agent is permitted to perform. These settings are intentionally conservative by default: shell execution is off, file writes are on, git reads are on.

[security]
denied_read_patterns = []
extra_write_roots = []
shell_command_mode = "warn"
shell_output_limit_bytes = 102400
shell_enabled = false
file_write_enabled = true
indexing_enabled = true

Built-in Read Deny-List

Regardless of denied_read_patterns, codescout always blocks reads from these locations:

~/.ssh
~/.aws
~/.gnupg
~/.config/gcloud
~/.config/gh
~/.docker/config.json
~/.netrc
~/.npmrc
~/.kube/config

On Linux, /etc/shadow and /etc/gshadow are also blocked. On macOS, /etc/master.passwd is blocked.

Use denied_read_patterns to extend this list with additional secrets or sensitive files specific to your environment:

[security]
denied_read_patterns = [
    "~/.config/my-app/credentials",
    "/etc/private",
]

Shell Command Mode

The shell_command_mode field fine-tunes what happens when run_command is called (assuming shell_enabled = true):

Enabling Shell Execution

Shell execution requires two settings to both be enabled:

[security]
shell_enabled = true
shell_command_mode = "warn"   # or "unrestricted"

The two-field design means you can grant shell access (shell_enabled = true) while still keeping the warning visible (shell_command_mode = "warn"), which is recommended for shared or CI environments.

Complete Example

A complete project.toml for a Rust service that uses local CPU embeddings and has shell execution enabled for running tests:

[project]
name = "payment-service"
languages = ["rust", "toml", "sql", "markdown"]
encoding = "utf-8"
tool_timeout_secs = 120

[embeddings]
model = "local:AllMiniLML6V2Q"
drift_detection_enabled = true    # set to false to opt out of semantic drift scoring

[ignored_paths]
patterns = [
    ".git",
    "node_modules",
    "target",
    "__pycache__",
    ".venv",
    "dist",
    "build",
    ".codescout",
    "vendor",
    "migrations/archive",
]

[security]
denied_read_patterns = ["~/.config/stripe"]
shell_command_mode = "warn"
shell_output_limit_bytes = 204800
shell_enabled = true
file_write_enabled = true
indexing_enabled = true

How Configuration Is Loaded

At startup and whenever workspace(action: activate) is called, codescout:

1. Looks for .codescout/project.toml in the project root.
2. If found, parses it. Any section that is missing falls back to its defaults.
3. If not found, constructs a default config using the directory name as the project name.

The effective configuration is always visible via the workspace(action: status) tool:

{ "name": "workspace(action: status)", "arguments": {} }

Changes to project.toml take effect the next time the project is activated — either by restarting the MCP server or by calling workspace(action: activate) again with the same path.

Workspace Configuration

For multi-project repos, create .codescout/workspace.toml alongside project.toml:

[[project]]
id = "backend"
root = "services/backend"

[[project]]
id = "frontend"
root = "apps/frontend"
depends_on = ["backend"]

Fields

Each project gets its own LSP servers, memory store, and semantic index. See Multi-Project Workspaces for usage details.

Global Config

A two-layer configuration system that merges a user-level global config with the per-project .codescout/config.toml, so workspace-wide defaults can be set once without touching every project.

File locations

Project-level values always win. Any key present in the project config overrides the global value for that project.

Supported fields

All fields from the project config are supported in the global config. Common use cases:

# ~/.config/codescout/config.toml

[embeddings]
model = "jinaai/jina-embeddings-v2-base-code"
chunk_size = 1024

[security]
max_index_bytes = 524288000   # 500 MB
write_lock_timeout_secs = 30

Load behaviour

• Missing global config file is silently ignored (not an error).
• Malformed TOML propagates as an error (fail-fast rather than silent misconfiguration).
• File-size guard rejects configs over 64 KB.
• HOME fallback used when XDG_CONFIG_HOME is not set.

Merge semantics

Tables are merged key-by-key; scalar values are overridden wholesale. There is no deep-merge within nested tables — if a project config sets [embeddings], the entire [embeddings] table from the global config is replaced, not merged field-by-field.

Embedding Backends

Semantic search requires converting source code into vector embeddings. codescout supports four backends, selected at runtime by the model field in [embeddings] inside .codescout/project.toml. The prefix before the colon determines which backend is used.

[embeddings]
model = "ollama:nomic-embed-text"   # recommended when Ollama is available

The onboarding tool detects your hardware at setup time and writes the best model for your machine into this field automatically. You rarely need to set it manually — see Choosing a Backend if you want to override it.

Backend Comparison

Recommended Models

onboarding picks the best model for your machine automatically. This table is a reference for manual overrides or when comparing options.

Switching models requires a full reindex — see Rebuilding After a Model Change below. Scores are not comparable across models; a score of 0.75 means different things with different models.

Ollama

Uses a locally running Ollama daemon. No API key is required.

Model string format: "ollama:<model-name>"

Endpoint: $OLLAMA_HOST/v1/embeddings (default: http://localhost:11434/v1/embeddings)

Setup

1. Install Ollama from ollama.com.

2. Pull the embedding model:

   ollama pull mxbai-embed-large
   

3. Make sure the daemon is running:

   ollama serve
   

Configuration

[embeddings]
model = "ollama:mxbai-embed-large"

To use a different Ollama host (e.g. a remote machine or a custom port), set the OLLAMA_HOST environment variable before starting the MCP server:

export OLLAMA_HOST=http://192.168.1.50:11434

Automatic CPU Fallback

If Ollama is not running when codescout tries to connect, you’ll see a clear error:

Ollama is not reachable at http://localhost:11434

Options:

• Start Ollama: ollama serve
• Switch to bundled ONNX: set model = "local:AllMiniLML6V2Q" in [embeddings]
• Use a different server: set url = "http://your-server:port/v1" in [embeddings]

Recommended Ollama Models

OpenAI

Calls the OpenAI embeddings API. Requires an active OpenAI account and an API key.

Model string format: "openai:<model-name>"

Endpoint: https://api.openai.com/v1/embeddings

Authentication: $OPENAI_API_KEY environment variable (required)

Setup

Set your API key in the environment before starting the MCP server:

export OPENAI_API_KEY=sk-...

Configuration

[embeddings]
model = "openai:text-embedding-3-small"

Recommended OpenAI Models

Custom Endpoint

Points at any OpenAI-compatible embeddings API — useful for self-hosted models, Azure OpenAI, Together AI, or other third-party providers.

Model string format: "custom:<model-name>@<base-url>"

codescout appends /v1/embeddings to <base-url>, so a base URL of http://localhost:1234 becomes http://localhost:1234/v1/embeddings.

Authentication: $EMBED_API_KEY environment variable (optional — set it if the server requires a bearer token)

Setup

Start your compatible server, then set the API key if needed:

export EMBED_API_KEY=your-token-here

Configuration

[embeddings]
model = "custom:mxbai-embed-large@http://localhost:1234"

Examples for common providers:

# Azure OpenAI
model = "custom:text-embedding-3-small@https://my-resource.openai.azure.com/openai/deployments/my-deployment"

# Together AI
model = "custom:togethercomputer/m2-bert-80M-8k-retrieval@https://api.together.xyz"

# Hugging Face Text Embeddings Inference (TEI)
model = "custom:BAAI/bge-large-en-v1.5@http://localhost:8080"

Local (fastembed)

Runs entirely on-device using fastembed-rs and ONNX Runtime. No external daemon, no API key, and no network traffic after the initial model download.

Model string format: "local:<EmbeddingModel-variant>"

Requires: building from source with the local-embed Cargo feature. This backend is not available in the published cargo install codescout binary because ONNX Runtime is a native system library that cannot be bundled through crates.io.

Looking for free local embeddings without building from source? Use Ollama instead — it is the recommended path for most users.

Model cache: ~/.cache/huggingface/hub/ — downloaded on first use, then fully offline

Build

Clone the repository and build with local embedding support:

git clone https://github.com/mareurs/codescout.git
cd codescout
cargo install --path . --features local-embed

Or, to have both local and remote backends available simultaneously:

cargo install --path . --features remote-embed,local-embed

Configuration

[embeddings]
model = "local:AllMiniLML6V2Q"

Supported Local Models

For most local setups, AllMiniLML6V2Q gives the best tradeoff: small download, CPU-safe inference, and solid retrieval quality. Use JinaEmbeddingsV2BaseCode when search quality on code is the priority and the larger download is acceptable.

Error When Feature Is Missing

If you try to use a local: model without the local-embed feature compiled in, you will see an error like:

Local embedding requires the 'local-embed' feature.
Rebuild with: cargo build --features local-embed

Batching

All backends send texts in batches of 8. This avoids HTTP 400 errors from servers that have payload size limits (Ollama is particularly strict about this) and keeps per-request latency manageable. The batch size is fixed and not configurable.

Rebuilding After a Model Change

The embedding index stores which model was used to build it. If you change the model field in project.toml, you must rebuild the index with the force flag to avoid mixing vectors from different models:

{ "name": "index(action: build)", "arguments": { "force": true } }

codescout will warn if it detects a mismatch between the configured model and the model recorded in the existing index.

Choosing a Backend

In most cases you do not need to choose — onboarding probes your hardware and writes the recommended model into .codescout/project.toml automatically. The decision tree below is for manual overrides.

• Default / getting started → local:AllMiniLML6V2Q — bundled, 22 MB, no setup. Already active out of the box; no config change needed.
• Better code search, can build from source → local:JinaEmbeddingsV2BaseCode (code-specific, 8192-token context, ~300 MB). Build with --features local-embed from the repository. Outperforms general-purpose models on code.
• Ollama is already running → ollama:nomic-embed-text (fast, 8192-token context, 137 MB). Upgrade to ollama:bge-m3 for higher retrieval quality at the cost of a 1.2 GB download.
• Best search quality, cloud acceptable → openai:text-embedding-3-small.
• Air-gapped or full data privacy required → local:JinaEmbeddingsV2BaseCode or local:AllMiniLML6V2Q (already the default — no external calls are made).
• Self-hosted TEI, vLLM, or similar → set url = "http://your-server:port/v1" in [embeddings].

Embeddings

codescout uses embeddings for semantic search — finding code by meaning rather than exact text matches. This guide covers how to configure the embedding backend.

⚠ This page describes the pre-v0.12 single-service embedding model and is being phased out. As of v0.12 the default substrate is the Retrieval Stack (Qdrant + dense embedder + sparse SPLADE + cross-encoder reranker, configured via CODESCOUT_* environment variables, not [embeddings] in project.toml). The [embeddings] config block still loads but only the model = "local:..." path is honoured — and only when the binary was built with the local-embed Cargo feature.

If you are setting up a fresh install: read Retrieval Stack instead. It covers the docker-compose stack, Ollama / llama.cpp / OpenAI integration, and the benchmark we used to pick defaults.

If you are upgrading from <v0.12: the model / url / api_key fields in project.toml no longer drive search. Run codescout migrate-memories to move legacy memory data into Qdrant, then bring up the stack.

The remainder of this page is kept as a reference for the legacy code path; treat it as historical.

Quick Start

codescout works out of the box with a bundled embedding model. No setup needed.

On first index(action: build), it downloads all-MiniLM-L6-v2 (~22 MB, quantized) to ~/.cache/huggingface/hub/ and runs it locally via ONNX. This is a one-time download.

# .codescout/project.toml (default — no changes needed)
[embeddings]
model = "local:AllMiniLML6V2Q"

This is fine for single-project use or getting started. For better performance with multiple projects, see the next section.

Recommended: External Embedding Server

The bundled model loads into memory per codescout instance. With multiple projects open, this duplicates memory (~22 MB each for the default model). A dedicated embedding server avoids this:

• One process serves all codescout instances
• No memory duplication — the model loads once
• Faster queries — the model stays warm
• Model freedom — use any model and quantization

Configuration

Point codescout at your server with two fields:

[embeddings]
model = "nomic-embed-text-v1.5"          # model name (sent in API request)
url = "http://127.0.0.1:43300/v1"        # your server's base URL
# api_key = "optional-key"               # or set EMBED_API_KEY env var

The url field works with any server implementing the OpenAI /v1/embeddings API. codescout normalizes the URL automatically — all of these are equivalent:

• http://127.0.0.1:43300
• http://127.0.0.1:43300/v1
• http://127.0.0.1:43300/v1/embeddings

Setup Examples

llama.cpp

Download a GGUF model and start the server:

# Download (example: nomic-embed-text quantized)
wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q8_0.gguf

# Start server
llama-server -m nomic-embed-text-v1.5.Q8_0.gguf --embeddings --port 43300

[embeddings]
model = "nomic-embed-text-v1.5"
url = "http://127.0.0.1:43300/v1"

Ollama

ollama pull nomic-embed-text
ollama serve  # if not already running

[embeddings]
model = "nomic-embed-text"
url = "http://127.0.0.1:11434/v1"

vLLM

vllm serve nomic-ai/nomic-embed-text-v1.5 --task embed --port 43300

[embeddings]
model = "nomic-embed-text-v1.5"
url = "http://127.0.0.1:43300/v1"

TEI (HuggingFace Text Embeddings Inference)

docker run -p 43300:80 ghcr.io/huggingface/text-embeddings-inference \
  --model-id nomic-ai/nomic-embed-text-v1.5

[embeddings]
model = "nomic-embed-text-v1.5"
url = "http://127.0.0.1:43300/v1"

OpenAI

[embeddings]
model = "text-embedding-3-small"
url = "https://api.openai.com/v1"
api_key = "sk-..."  # or set EMBED_API_KEY env var

Configuration Reference

[embeddings] fields

Resolution Order

When codescout needs to embed text, it resolves the backend in this order:

1. url is set → use it as an OpenAI-compatible endpoint
2. model starts with local: → bundled ONNX model via fastembed
3. model starts with ollama: → Ollama API (deprecated — use url instead)
4. model starts with openai: → OpenAI API with OPENAI_API_KEY
5. No url, no prefix → try as a local model name, then error with suggestions

Environment Variables

Model Recommendations

Minimum recommended: 768 dimensions for good code search quality.

Bundled Local Models

These work with the local: prefix (no server needed):

How It Works

1. AST-aware chunking — tree-sitter extracts top-level definitions (functions, classes, structs). Each chunk is a complete semantic unit, not an arbitrary text window.

2. Chunk size auto-derived — codescout calculates chunk size from the model’s context window. No manual tuning needed.

3. Vector storage — embeddings are upserted into Qdrant’s code_chunks collection over gRPC (default localhost:6334). Both a dense and a sparse vector are stored per chunk; query-time hybrid search fuses them via RRF inside Qdrant. See Hybrid Dense + Sparse Retrieval for the topology.

4. Bundled model lifecycle — when using the local: prefix (compile-time local-embed feature), the ONNX model is loaded lazily on first semantic_search or index(action="build"), cached for 5 minutes, then unloaded to free memory. The default substrate is the HTTP dense embedder service, not the bundled ONNX path.

Choosing a Model

Not sure which model to use? See the Embedding Model Comparison for benchmark results across three models, real-world usage data, and recommendations.

TL;DR: The default (local:AllMiniLML6V2Q) is within 2 points of the best model on a 60-point benchmark, indexes 21x faster, and requires zero setup. Keep it unless you have a specific reason to change.

Troubleshooting

Model mismatch after changing config

If you change the model or url after indexing, the stored vectors are incompatible. Rebuild the index:

index(action: build, force: true)

Endpoint unreachable

Check that the server is running and the URL is correct:

curl http://127.0.0.1:43300/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"nomic-embed-text","input":["test"]}'

Corporate proxy blocking downloads

The bundled model downloads from HuggingFace. If your proxy blocks this:

1. Download the model on an unrestricted machine
2. Copy to ~/.cache/huggingface/hub/models--nomic-ai--nomic-embed-text-v1.5/
3. Or use an external server instead (set url)

Migration from Prefix Syntax

The ollama: prefix is deprecated and will be removed in a future version. Migrate to the url field:

# Before (deprecated)
[embeddings]
model = "ollama:nomic-embed-text"

# After
[embeddings]
model = "nomic-embed-text"
url = "http://localhost:11434/v1"

The custom: prefix has been removed. Migrate to the url field:

# Before (removed)
[embeddings]
model = "custom:my-model@http://my-server:8080"

# After
[embeddings]
model = "my-model"
url = "http://my-server:8080/v1"

Embedding Model Comparison

Which embedding model should you use with codescout? This page summarizes benchmark results and real-world usage data to help you choose.

This comparison is based on the codescout codebase (417 files, ~32K chunks) as of 2026-04-03. Results may vary with different codebases. We will update this page as we collect more real-world data.

Models Tested

Benchmark Results

We tested 20 queries across 4 complexity tiers, scoring each 0-3 based on whether the expected source files appeared in the top 10 results.

Overall Scores (max 60)

nomic-embed-code ████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░  36/60
AllMiniLML6V2Q   ██████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  34/60
nomic-embed-text ████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  32/60

By Complexity Tier

No single model dominates all tiers.

Practical Metrics

How Agents Actually Use Semantic Search

Analysis of 31,674 tool calls across 70+ real projects:

• symbols — 17.8% of all calls (the workhorse)
• grep — 2.3%
• semantic_search — 1.1% (349 calls total)

Agents use semantic search as a last resort — when they don’t know the exact name of what they’re looking for. The typical query is a short 3-6 word concept phrase:

"error handling and recovery from tool failures"
"embedding index build and incremental update"
"security path validation and write access control"
"ollama embedding configuration"
"intent classifier ONNX model prediction"

These are mostly Tier 1-2 queries (direct concept or two-concept composition). Tier 3-4 queries (complex architectural questions) are rare in organic usage.

Recommendation

Use the default: local:AllMiniLML6V2Q.

The 7B code-specialized model’s 2-point advantage doesn’t justify 21x slower indexing, 5x more storage, and a GPU requirement. For the 1.1% of calls that reach semantic search, the bundled model is good enough.

When to consider alternatives

• nomic-embed-text via Ollama — if Ollama is already running for other tasks, add url = "http://localhost:11434/v1" and model = "nomic-embed-text" for slightly better Tier 1 results at the same speed. Smallest storage footprint (55 MB).

• nomic-embed-code via llama.cpp — if you have a GPU and primarily use semantic search for concept-level exploration (architecture questions, onboarding to a new codebase). Best at Tier 2-3 queries.

Methodology

Full benchmark details, per-query scores, and test case definitions are in docs/research/2026-04-03-embedding-model-benchmark.md.

The benchmark will be updated as we collect more real-world query data via the --debug flag’s usage traceability feature (see Debug Mode).

Language Support

codescout provides three tiers of support depending on which backends are available for a given language.

• Full support — LSP server + tree-sitter grammar. All symbol tools work, and richer AST extraction is available internally. Semantic search is also available after indexing.
• LSP only — LSP server configured, no tree-sitter grammar. Symbol navigation, references, and rename work.
• Detection only — Language is recognized for chunking and file detection. No LSP server and no tree-sitter grammar. Only file operations and semantic search (after indexing) are available.

Supported Languages

Detection-Only Languages

These languages are recognized for chunking and file detection. No LSP server is configured and no tree-sitter grammar is bundled.

Feature Matrix

Installing LSP Servers

codescout looks for each LSP server binary on PATH. The quickest way to get started is the bundled install script:

# See what's installed and what's missing
./scripts/install-lsp.sh --check

# Install all supported LSP servers
./scripts/install-lsp.sh --all

# Install specific languages only
./scripts/install-lsp.sh rust python typescript go

The script supports Linux and macOS, detects your package managers, and skips servers that are already installed. For manual installation, see the per-language instructions below.

Rust

rustup component add rust-analyzer

Binary: rust-analyzer

Python

npm install -g pyright

Binary: pyright-langserver, invoked with --stdio.

TypeScript, JavaScript, TSX, JSX

npm install -g typescript-language-server typescript

Binary: typescript-language-server, invoked with --stdio. One installation covers TypeScript, JavaScript, TSX, and JSX.

Go

go install golang.org/x/tools/gopls@latest

Binary: gopls. Ensure $(go env GOPATH)/bin is on PATH.

Java

jdtls (Eclipse JDT Language Server) is distributed as a standalone archive from the Eclipse downloads page. Unpack and place the launcher script on PATH.

Binary: jdtls

Kotlin

kotlin-lsp (JetBrains) is distributed as a release archive on the GitHub releases page. Unpack and place the kotlin-lsp script on PATH.

Binary: kotlin-lsp, invoked with --stdio. Each codescout instance automatically passes --system-path to isolate its workspace cache.

C and C++

clangd is shipped with LLVM/Clang. Install via your system package manager:

# Debian/Ubuntu
sudo apt install clangd

# macOS
brew install llvm   # or: xcode-select --install

# Fedora/RHEL
sudo dnf install clang-tools-extra

Binary: clangd. One installation covers both C and C++.

C#

OmniSharp is bundled with the .NET SDK or available as a standalone binary. The standalone build can be downloaded from the OmniSharp releases page. Place the binary on PATH.

Binary: OmniSharp (note the capital O), invoked with -lsp.

Ruby

gem install solargraph

Binary: solargraph, invoked with stdio (no leading --).

HTML and CSS

npm install -g vscode-langservers-extracted

One package installs both servers. Binaries: vscode-html-language-server (HTML) and vscode-css-language-server (CSS, SCSS, Less), each invoked with --stdio.

Bash

npm install -g bash-language-server

Binary: bash-language-server, invoked with start (positional argument — not --stdio).

Known Quirks

jdtls requires a data/workspace directory for project indexes. Some wrapper scripts accept --data to specify this path. If symbol tools return empty results, check whether jdtls started correctly by examining the server log. The JAVA_HOME environment variable should point to a JDK 17+ installation.

OmniSharp binary name starts with a capital O (OmniSharp, not omnisharp). On case-sensitive filesystems the name must match exactly. Some distributions ship a lowercase alias; check with which OmniSharp before assuming the server is unavailable.

solargraph takes a positional argument (stdio) rather than a flag (--stdio). This differs from most other servers. The invocation is solargraph stdio, not solargraph --stdio.

kotlin-lsp (JetBrains) has a single workspace session limitation: only one kotlin-lsp process can serve a given project directory at a time. If another codescout instance or editor is already running kotlin-lsp for the same project, new instances fail with “Multiple editing sessions for one workspace are not supported yet”. codescout detects this and fails fast with a clear error. Workaround: close the other session first, or use a single codescout instance for Kotlin projects. JetBrains plans to lift this restriction in a future release.

kotlin-lsp also builds a project index on first startup (JVM bootstrap + Gradle import), which takes 8–15 seconds. codescout retries the LSP handshake during this window automatically.

typescript-language-server handles JavaScript and JSX in addition to TypeScript and TSX. The LSP languageId sent for TSX files is typescriptreact and for JSX files is javascriptreact — this is handled internally and requires no configuration.

Bash language support

What it does

Bash and shell scripts (.sh, .bash) now receive full language support: symbol extraction via tree-sitter and LSP navigation via bash-language-server.

Previously Bash was detection-only — file contents were indexed for semantic search but no symbols were extracted and no LSP server was started.

Capabilities

Setup

Install bash-language-server:

npm install -g bash-language-server

No project configuration needed — codescout detects .sh / .bash files and starts the server automatically.

Known limits

• bash-language-server is invoked with start (positional argument), not --stdio — the invocation differs from most other LSP servers.
• Symbol extraction covers function_definition nodes only. Variable declarations and sourced scripts are not indexed as symbols.
• Large generated shell scripts may produce many small symbol chunks in semantic search results.

Kotlin LSP Multiplexer

Problem

Multiple codescout instances targeting the same Kotlin project cause severe degradation. JetBrains’ kotlin-lsp allows only one LSP process per workspace, and two instances compete for Gradle daemon locks, consuming 3-4GB RAM with duplicate project models and causing 120s+ timeouts.

Solution

codescout now runs a detached multiplexer process (codescout mux) that manages a single kotlin-lsp instance and allows multiple codescout sessions to share it via a Unix socket.

┌─────────────┐     ┌─────────────┐
│ codescout-A  │     │ codescout-B  │
└──────┬───────┘     └──────┬───────┘
       │ Unix socket        │
       └────────────┬───────┘
                    │
          ┌─────────▼──────────┐
          │  codescout mux     │
          └─────────┬──────────┘
                    │ stdio
          ┌─────────▼──────────┐
          │   kotlin-lsp       │
          │  (single JVM)      │
          └────────────────────┘

Activation

The multiplexer is automatic — no configuration required. When codescout detects that a project uses Kotlin, it starts or connects to a mux process transparently. No flags, no project.toml changes.

The codescout mux sub-command runs the mux process directly (for debugging), but in normal use it is spawned by codescout itself.

JVM Pre-warming

When a project declares java or kotlin in its language list, codescout spawns background LSP get_or_start tasks immediately on server startup and on every workspace(action: activate) call.

# .codescout/project.toml
[project]
languages = ["kotlin"]  # also triggers for "java"

Pre-warming eliminates the 8–15 s cold-start penalty that would otherwise occur on the first symbol query after startup. The warm-up runs in the background — server startup and workspace(action: activate) return immediately without waiting for the LSP to be ready.

Concurrency safety: LspManager’s watch-channel serialises parallel starters. Calling workspace(action: activate) from concurrent sessions cannot trigger duplicate LSP processes.

The multiplexer handles the rest of the connection lifecycle — see How It Works below.

How It Works

1. First codescout instance needing Kotlin LSP acquires an exclusive file lock (flock), spawns codescout mux, and connects as a client.
2. Subsequent instances find the lock held, skip spawning, and connect directly to the existing mux socket.
3. The mux handles ID remapping (so two clients can both send request ID 1 without collision), document state dedup (didOpen/didClose tracked per client), and version rewriting (monotonic per-URI versions for didChange).
4. When all clients disconnect, the mux stays alive for 5 minutes (idle timeout), then shuts down kotlin-lsp and exits.

Ownership & Crash Recovery

The mux process holds an exclusive flock on a lock file for its entire lifetime. If it dies — even via SIGKILL or OOM — the OS releases the lock. The next codescout instance detects the stale lock, cleans up, and spawns a fresh mux. No PID files, no heartbeats, no race conditions.

Gradle Isolation

Independently of the mux, kotlin-lsp now runs with an isolated GRADLE_USER_HOME to prevent Gradle daemon cache lock contention between instances.

Benefits

Limitations

• Unix only — uses Unix domain sockets. Windows support (named pipes) is planned but not yet implemented.
• Kotlin only — other languages use direct LSP connections. The mux flag in LspServerConfig makes it easy to opt in additional languages (e.g., jdtls for Java) in the future.
• Concurrent file edits — if two clients edit the same file simultaneously, the document state in kotlin-lsp may desync. This is inherent to LSP’s single-client design and is acceptable since two agents editing the same file is already a bug.
• Rename serialization — workspace/applyEdit (used by rename) is routed to the client that initiated the rename. Concurrent renames from different clients are serialized through an edit lock.

Diagnostics

The mux spawn/connect is visible in codescout diagnostic logs:

INFO codescout::lsp::manager: mux process ready for kotlin at "/tmp/codescout-kotlin-mux-<hash>.sock"
INFO codescout::lsp::manager: mux already running for kotlin, connecting to "/tmp/codescout-kotlin-mux-<hash>.sock"

The mux process itself logs to .codescout/mux-kotlin-<hash>.log (or /tmp/ if .codescout/ does not exist in the workspace).

Design

Full design spec: docs/superpowers/specs/2026-03-24-kotlin-lsp-multiplexer-design.md

Rust LSP multiplexer

What it does

When two codescout instances open the same Rust project, they now share a single rust-analyzer process via the existing LSP multiplexer (first used for kotlin-lsp). This eliminates the stale-hover / stale-goto bug that appeared after a write in instance A was not reflected in instance B.

Footprint

• One rust-analyzer per (project-root) across all codescout instances on the machine.
• Idle-shutdown after 180 seconds with no connected clients.
• Memory saved: one full rust-analyzer (2–4 GB on a medium Cargo workspace) per extra codescout instance.

Opt out

Add to .codescout/project.toml:

[lsp.rust]
mux = false

Then /mcp restart. Codescout will fall back to spawning a dedicated rust-analyzer per instance, as before.

Known limits

• Unix only (the mux is #[cfg(unix)]).
• rust-analyzer must be on PATH.
• If two clients connect before rust-analyzer completes initialization, the second client waits on a 5-retry / 1-second backoff. No-op behaviourally; you may see a brief startup delay under heavy concurrency.

Tools Overview

codescout exposes 20 tools organized into seven categories. This page is a quick map. Each category has a dedicated reference page linked from the headings below.

Symbol Navigation

LSP-backed tools for locating and editing code by name rather than by line number. These tools require an LSP server to be running for the target language.

The navigation tools (symbols, references) accept an optional scope parameter to search library code as well as project code — see Library Navigation below.

File Operations

Read, list, and search files. These tools work on any file regardless of language support.

Semantic Search

Find code by meaning rather than by name or pattern. Requires an embedding index built with index(action: build) — see the Setup Guide. Use the optional scope parameter to search within a specific library (see Library Navigation).

Library Navigation

Navigate third-party dependency source code (read-only). Libraries are auto-registered when LSP symbol_at returns a path outside the project root; you can also register them manually.

Scope parameter — once a library is registered, pass scope to any navigation or search tool to target it:

All results include a "source" field ("project" or "lib:<name>") so you can tell where each result came from.

Memory

Persistent key-value store backed by markdown files in .codescout/memories/. Survives across sessions.

Workflow & Config

Project setup, shell execution, and server configuration.