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.
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.
Commands
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:
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.
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.

