Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auto-sop.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
  1. Receives the tool call as JSON on stdin
  2. Scrubs any secrets or sensitive data
  3. Writes the capture atomically to .auto-sop/captures/
  4. 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 on a schedule (hourly via launchd on macOS or systemd on Linux) or 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)_
FieldPurpose
Severity[error] or [warning] — how strictly Claude should follow it
DescriptionClear, actionable rule in natural language
IDUnique identifier (sop:sop-xxxx) for tracking and reverting
EvidenceNumber 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    │  hourly (launchd/systemd) 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