New

Snout 0.3.3 is out: your agent can search this project's history, on your machine.

New

Snout 0.3.3 is out: your agent can search this project's history, on your machine.

Docs

Snout · for Claude Code and Codex

Snout is a local context layer for Claude Code and Codex. It classifies file reads, flags low-value bulk, stores local session cards, and reports estimates. Core features run on your machine; optional network features require opt-in.

Install

In Claude Code, add the marketplace, install the plugin, and restart Claude Code. In Codex, run npm install -g usesnout, then snout init codex in your project, trust the folder, and approve Snout’s hooks with /hooks. The public npm release is v0.3.3.

claude plugin marketplace add biffbuster/snout-context
claude plugin install snout@snout-context

Snout starts in observe mode: it records and flags, and blocks nothing.

Modes

Observe. Records every read and what Snout would hold back. Blocks nothing. This is the default.

Advise. Asks you before a low-value read goes ahead.

Enforce. Handles flagged reads according to the agent. Claude Code can return a bounded excerpt and hint; Codex can block an ambiguous bulk print or rewrite a supported PowerShell read. The agent can retry with a targeted search.

/snout:mode enforce

Commands

/snout:report what this session read, and how much was low-value
/snout:report --by-agent the same per subagent, plus reads one agent repeated
/snout:explain <path> why a file was classified: label, score, band
/snout:scan [dir] per-label distribution for a folder
/snout:allow <path> never flag this file again
/snout:apply suggested changes, previewed, applied on --yes
/snout:statusline a live token counter in your terminal
/snout:doctor is it installed, and is it firing?

What gets classified

Rules look at a file’s name, its path, and its first 2 KB. There’s no model and no network call, and a decision takes under a millisecond.

Lockfiles. package-lock.json, yarn.lock, Cargo.lock, and the rest of the family.

Generated code. Files that say they’re generated, with banners like @generated or DO NOT EDIT, plus generated JSON and YAML by naming convention.

Vendored code. vendor/, node_modules/, deps/, and other installed trees.

Build output. dist/, build/, out/, target/, and coverage/, but only when your .gitignore ignores them. A committed build/ folder is usually hand-written tooling.

Minified files. *.min.js, *.min.css, and source maps.

Secrets. .env files, keys, and credentials. Snout asks before these are read, in every mode.

Scoring and thresholds

Every file gets a score from 0 to 1 for every label. The strongest flag decides the band.

Act, 0.90 and up. Enforce trims the read; advise asks first.

Ask, 0.50 to 0.90. Snout checks with you before the read.

Read, below 0.50. Unsure means read. The agent gets the whole file.

Files under about 2k tokens and directories are never blocked, because a block costs the agent a turn. To preview other thresholds on a folder:

/snout:scan src --deny 0.95 --ask 0.6

Configuration

Settings resolve in order: built-in defaults, then ~/.snout/config.json, then .snout/config.json in your project, then environment variables. /snout:doctor shows where each setting came from.

{
"mode": "enforce",
"alwaysAllow": ["fixtures/**"],
"alwaysDeny": ["legacy/generated/**"]
}

Your data

Core records live as plain files in your project’s .snout/ folder, including decisions and local session cards that Claude Code or Codex may recall. Add .snout/ to .gitignore. Optional features such as the external preference judge can make network requests only when enabled.

Measured results

Snout 0.3.3 was benchmarked with Claude Code Sonnet on Windows across 14 authored tasks, five repeats per arm: 140 sessions. All 70 attempts passed in each arm. Cost per solved task fell 25.0% (95% CI: −38.2% to −9.5%). On 10 bulk-path tasks it fell 29.3%; on four control tasks the change was within noise. These results do not prove no quality loss, and Codex has not yet had a matched cost test.

Snout, a pink anteater in a cowboy hat
Snout, a pink anteater in a cowboy hat