> ## 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

> The four-step pipeline: observe, detect, write, prevent. How auto-sop turns Claude Code mistakes into enforced directives.

# 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

<Info>
  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.
</Info>

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`)

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

## 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:

```markdown theme={null}
- **[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.

<Tip>
  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.
</Tip>

## Privacy

The entire pipeline runs locally:

<CardGroup cols={3}>
  <Card title="Local captures" icon="hard-drive">
    All captures stay in `.auto-sop/captures/` on your machine. Nothing is uploaded on the free tier.
  </Card>

  <Card title="Local analysis" icon="microchip">
    LLM analysis uses your own Claude Max subscription via `claude -p`. No external API calls.
  </Card>

  <Card title="Optional cloud" icon="cloud">
    Pro tier cloud sync is opt-in and encrypted client-side (AES-256) before upload.
  </Card>
</CardGroup>

## 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
```