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:

Built-in called	Redirected to
`grep`	`grep`
`Read`	`symbols` or `symbols` (for source files)
`cat`	`symbols` or `symbols` (for source files)
`find`	`tree` (with glob)
`ls`	`tree`

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

codescout Manual