Skip to content

Learn

Jump to bottom
Edouard CLAUDE edited this page Sep 3, 2026 · 1 revision

Learn

snip learn mines your agent session history for CLI error-correction patterns: a command that failed, followed by a corrected version of the same command that succeeded. It turns those pairs into rules your agent can read, so it stops repeating the same mistake.

Where Gain Dashboard measures tokens saved on output, snip learn targets the other waste: the round-trips burned re-running a command until it works.

snip learn reads session files only. It never runs a command, and it works in both the full and the -tags lite build (no SQLite involved).

Default view

snip learn

Scans the current project's sessions over the last 30 days:

snip learn - CLI error pattern analysis

Scanned: 14 sessions, 26 errors with corrections

Common patterns:
  git (15 occurrences)
    Error: internal/config/config_test.go:1985:6: undefined: reflect -> fixed by /usr/bin/git add internal/config/config.go ...
    Error: FAIL -> fixed by /usr/bin/git add internal/cli/cli.go internal/cli/cli_test.g...

  go (3 occurrences)
    Error: FAIL -> fixed by go test -run TestConfigShowsMergedConfig ./internal/cli/ -v ...

Use --generate to create .claude/rules/cli-corrections.md

Patterns are grouped by base command and sorted by occurrence count, so the noisiest habit shows up first.

Flags

Flag Description
--since N Scan the last N days (default 30)
--all Scan every project, not just the current working directory
--generate Write the detected patterns to .claude/rules/cli-corrections.md 
snip learn --since 7        # last week only
snip learn --all            # every project in the sessions directory
snip learn --generate       # emit the rules file

Generated rules file

--generate writes a project-relative .claude/rules/cli-corrections.md (it lives with the repo, not in CLAUDE_CONFIG_DIR), which Claude Code picks up as project context:

# CLI Corrections (auto-generated by snip learn)

## Common patterns detected in your coding sessions

### go failures
- When `go` fails with: FAIL
  - Fix: `go test -run TestConfigShowsMergedConfig ./internal/cli/ -v`

The file is overwritten on each run. Review it before committing: the detection is heuristic (see below), so prune the noise and keep the corrections that are genuinely worth teaching the agent.

How detection works

  1. Read sessions. Every .jsonl under the project's session directory, including nested subagents/ files. Entries older than the --since cutoff are skipped.
  2. Extract Bash commands. tool_use entries named Bash are paired with their tool_result by tool_use_id, keeping session order.
  3. Drop what never ran. A rejected or interrupted tool call carries is_error, but nothing executed: such entries are removed entirely, so they are neither a failure nor a candidate fix.
  4. Flag failures. The is_error flag decides when the result carries one, which is nearly always. The marker heuristic (command not found, undefined:, ENOENT, exit status, build failed, ...) is only the fallback for results without the flag, so a command that merely prints an error string is no longer counted as a failure.
  5. Find the correction. Within the next 5 commands, the first one with the same base command that succeeded is recorded as the fix. Base command extraction reuses the hook's shell parser and walks past shell scaffolding, so /usr/bin/git, env FOO=1 git ..., git ... | grep and cd /path && git ... all normalize to git, and SCRATCH=/tmp/x && python3 ... reports python3.
  6. Aggregate. Identical failing commands are merged with a count, grouped by base command.

Limits

The detection is still a heuristic, and it optimizes for recall:

  • The 5-command window is arbitrary. An unrelated later invocation of the same tool can be picked as the "fix"; identical error and fix commands are reported as retrying the same command.
  • No confidence score. A pattern seen once and a pattern seen twenty times differ only by their count.
  • Bash tool only. Commands run outside the agent's Bash tool are invisible.
  • Results without an is_error flag fall back to the marker heuristic, which cannot tell a failure from a command that prints the word FAIL.
  • Credentials are copied verbatim. A failing command carrying an inline secret (PGPASSWORD=..., a connection string) appears as-is in the report and in the generated file.

Treat the report as a shortlist to review, not as ground truth, and always read the generated rules file before committing it.

Filtering out shell scaffolding and trusting the is_error flag landed in v0.25.1. On an earlier binary the same sessions produce cd and path-fragment groups, and successful commands whose output quotes an error marker are reported as failures.

Where sessions come from

snip learn reads from CLAUDE_CONFIG_DIR/projects/ (default ~/.claude/projects/), the same source as snip discover. The current project directory is resolved by mapping the working directory path to Claude Code's naming scheme (every non-alphanumeric character becomes a dash). See Configuration.

See also

Clone this wiki locally