> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibelearn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How VibeLearn Uses Hooks

> Lifecycle-driven learning capture — observe sessions from outside, analyze in background

## Core Principle

**Observe the session from the outside, analyze in the background, quiz yourself after.**

VibeLearn never modifies your prompts or the AI's responses. It attaches to 5 lifecycle events, captures what you build, and runs a local analysis pipeline when the session ends.

## The 5 Hooks

```
Session
       │
       ├── SessionStart      → check worker health, initialize session
       ├── UserPromptSubmit  → capture prompt, strip <private> tags
       ├── PostToolUse       → capture file edits, bash commands, tool outputs
       ├── Stop              → trigger 5-step analysis pipeline
       └── SessionEnd        → cleanup
```

### SessionStart

* Ensures the worker service is running (polls up to 15s with retries)
* Checks if the project is excluded via `VIBELEARN_EXCLUDED_PROJECTS`
* Never blocks session start — always exits 0

### UserPromptSubmit

* Strips `<private>...</private>` tags from the prompt before storage
* Initializes the session in the worker (`POST /api/sessions/init`)
* Returns `{"continue": true}` immediately — never delays prompts
* Does **not** inject any content into the prompt

### PostToolUse

* Captures every **Write**, **Edit**, **Bash** tool call
* Records: `tool_type`, `file_path`, `content` (up to 10KB), `cwd`
* Sends to worker as observations (fire-and-forget, non-blocking)
* Skips tools listed in `VIBELEARN_SKIP_TOOLS`

### Stop (Analysis Trigger)

Called when the agent loop ends. Triggers the 5 analysis steps sequentially:

```
1. POST /api/vibelearn/analyze/stack    detect tech stack
2. POST /api/vibelearn/analyze/static   AST pattern analysis
3. POST /api/vibelearn/analyze/concepts LLM: session summary + concepts
4. POST /api/vibelearn/analyze/quiz     LLM: quiz questions per concept
5. POST /api/vibelearn/sync             HMAC-signed sync to vibelearn.dev
```

Each step is independent — a failure in one does not block the next. Each step has a 60s timeout.

### SessionEnd

* Final cleanup
* Exits with code 0 (never blocks the IDE from closing)

## Exit Code Philosophy

| Code | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| `0`  | Success or graceful error — session continues normally          |
| `1`  | Non-blocking error — shown to user on stderr, session continues |
| `2`  | Blocking error — fed to the AI for processing (rare)            |

All hook errors exit with code `0` to prevent Windows Terminal tab closures.

## Privacy Flow

```
UserPromptSubmit hook
    │
    ├── Strip <private>...</private> tags from input
    │
    └── Send sanitized data to worker
              │
              └── Database (no private content stored)
```

The stripping happens at `src/utils/tag-stripping.ts` before any data reaches the worker or SQLite.