How It Works

auto-sop runs a four-step pipeline that turns recurring Claude Code mistakes into enforced directives — automatically and locally.

Observe → Detect → Write → Prevent

Step 1: Capture (Observe)

When you run auto-sop install, a lightweight hook shim is registered with Claude Code’s hook system (PreToolUse, PostToolUse, Stop events). Every time Claude Code invokes a tool, the shim:

Receives the tool call as JSON on stdin
Scrubs any secrets or sensitive data
Writes the capture atomically to .auto-sop/captures/
Returns control to Claude Code

The shim uses a double-fork architecture — it spawns a child process and exits immediately. This keeps overhead under 50ms per tool call, so your Claude Code experience stays fast.

Captures are stored per-project with timestamps and protected by lockfiles to prevent corruption during concurrent sessions.

.auto-sop/
  captures/
    2026-05-02T14-23-01-tool-bash.json
    2026-05-02T14-23-05-tool-read.json
    ...

Step 2: Learn (Detect)

The learner runs automatically during your session (every 10 turns) and once daily via a background sweep (launchd on macOS, systemd on Linux). You can also trigger it on demand with auto-sop learn-now. It processes captures through two stages:

Rule-based detection

Detectors scan captures for patterns that appear 3 or more times. Built-in detectors look for:

Same Bash command used when a dedicated tool exists (e.g., cat instead of Read)
Repeated error patterns (same error message across sessions)
Reverted changes (edits that get undone in the same session)
Anti-patterns in tool usage sequences

LLM validation

Candidate patterns are validated by Claude (via claude -p, using your Claude Max subscription at $0 cost). The LLM:

Confirms the pattern is a genuine recurring mistake
Writes a clear, actionable directive
Assigns a severity level (error or warning)

Only patterns with 3+ evidence occurrences reach LLM validation. Single mistakes are not promoted to directives — auto-sop waits for a real pattern.

Step 3: Write (Directive creation)

Validated directives are written to a managed section in your project’s CLAUDE.md. The managed section is:

Hash-checked — auto-sop detects manual edits and handles merges gracefully
Git-aware — directives respect your repository structure
Revertible — any directive can be rolled back with auto-sop revert <id>
TTL-pruned — stale directives that stop matching can be automatically retired

Each directive includes:

- **[warning]** Never use sleep-then-read-file loops to poll for
  background command output. Use Bash with run_in_background to get
  automatic completion notification. [sop:sop-2fa5]
  _(evidence: 3 sessions)_

Field	Purpose
Severity	`[error]` or `[warning]` — how strictly Claude should follow it
Description	Clear, actionable rule in natural language
ID	Unique identifier (`sop:sop-xxxx`) for tracking and reverting
Evidence	Number of sessions where the pattern was observed

Step 4: Prevent

Claude Code reads CLAUDE.md at the start of every session. When it encounters auto-sop directives, it follows them as project-level instructions. When a directive is applied, Claude Code emits a marker:

[sop:applied:sop-2fa5]

These markers let auto-sop track which directives are actively preventing mistakes and which may have become stale.

The full cycle — from first mistake to enforced prevention — typically takes 3-5 sessions. auto-sop waits for a genuine pattern before creating a directive.

Privacy

The entire pipeline runs locally:

Local captures

All captures stay in .auto-sop/captures/ on your machine. Nothing is uploaded on the free tier.

Local analysis

LLM analysis uses your own Claude Max subscription via claude -p. No external API calls.

Optional cloud

Pro tier cloud sync is opt-in and encrypted client-side (AES-256) before upload.

Architecture diagram

  Claude Code hooks (PreToolUse / PostToolUse / Stop)
          │
          ▼
  ┌───────────────┐
  │   Hook Shim   │  <50ms overhead, double-fork
  │  (capture)    │
  └───────┬───────┘
          │  stdin JSON → scrub secrets → write atomically
          ▼
  ┌───────────────┐
  │ Capture Store │  per-project, timestamped, lockfile-protected
  └───────┬───────┘
          │
          ▼
  ┌───────────────┐
  │    Learner    │  event-driven + daily sweep, or on-demand
  │               │  rule-based detectors (N≥3 evidence)
  │               │  + LLM analysis (claude -p, $0 via Max)
  └───────┬───────┘
          │  validated directives
          ▼
  ┌───────────────┐
  │  CLAUDE.md    │  managed section: hash-checked, git-aware,
  │  Editor       │  revertible, TTL pruning, drift detection
  └───────────────┘
          │
          ▼
    Claude Code reads CLAUDE.md on every session
    → same mistake never happens again

Getting Started

CLI Reference

Dashboard

Resources

How It Works

How It Works

Step 1: Capture (Observe)

Step 2: Learn (Detect)

Rule-based detection

LLM validation

Step 3: Write (Directive creation)

Step 4: Prevent

Privacy

Local captures

Local analysis

Optional cloud

Architecture diagram

​How It Works

​Step 1: Capture (Observe)

​Step 2: Learn (Detect)

​Rule-based detection

​LLM validation

​Step 3: Write (Directive creation)

​Step 4: Prevent

​Privacy

Local captures

Local analysis

Optional cloud

​Architecture diagram

How It Works

Step 1: Capture (Observe)

Step 2: Learn (Detect)

Rule-based detection

LLM validation

Step 3: Write (Directive creation)

Step 4: Prevent

Privacy

Architecture diagram