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

# Introduction

> Learn from every coding session — automatically

# VibeLearn

VibeLearn is a plugin for Claude Code and Cursor IDE that captures what you build during coding sessions, extracts learning concepts, and generates quiz questions. Run `vl quiz` after a session to retain what you learned.

## How It Works

Every time a session ends, VibeLearn automatically runs a 5-step analysis pipeline:

<Steps>
  <Step title="Stack Detection">
    Reads `package.json`, `pyproject.toml`, `go.mod`, etc. to identify your frameworks, ORMs, and tools.
  </Step>

  <Step title="Static Analysis">
    AST-parses files you edited to identify code patterns — custom hooks, API routes, DB queries, auth patterns.
  </Step>

  <Step title="Concept Extraction">
    A single LLM call produces a session narrative and a list of concepts you encountered (e.g., "React Server Actions", "SQLite WAL mode", "HMAC signing").
  </Step>

  <Step title="Quiz Generation">
    A second LLM call generates targeted quiz questions per concept across 7 formats: `multiple_choice`, `code_reading`, `spot_the_bug`, `fill_in_blank`, `open_ended`, `true_false`, and `ordering`. Question type is selected based on concept difficulty (junior / mid / senior). Open-ended senior answers are evaluated by a 5-dimension rubric.
  </Step>

  <Step title="Sync">
    HMAC-signed sync to vibelearn.dev. Queued offline if unavailable — retried next session.
  </Step>
</Steps>

## Quick Start

```bash theme={null}
# Install the plugin (Claude Code)
/plugin install vibelearn

# Configure an AI provider (Gemini free tier recommended)
# Add VIBELEARN_GEMINI_API_KEY to ~/.vibelearn/settings.json

# Code normally — after your session ends, quiz yourself:
vl quiz
```

## The `vl` CLI

```bash theme={null}
vl quiz              # Interactive quiz — all pending questions
vl quiz --session    # Quiz from the last session only
vl status            # Sessions analyzed, top concept categories, mastery overview
vl gaps              # Concepts not yet mastered (score < 50%)
vl login <api-key>   # Connect to vibelearn.dev
vl login --status    # Check current auth status
```

## Adaptive Difficulty

VibeLearn tracks mastery per concept and adapts quiz difficulty automatically:

* **3 correct in a row** → promoted to the next level (junior → mid → senior)
* **1 wrong answer** → dropped back a level
* **Follow-up questions** are inserted mid-quiz when a junior question is answered correctly, to probe deeper understanding
* **Senior open-ended answers** are evaluated by a 5-dimension rubric: accuracy, depth, trade-offs, practical reasoning, and completeness

## Privacy

Wrap any content in `<private>` tags to prevent storage or sync:

```
Please review <private>my-api-key: sk-...</private> this config
```

Content inside `<private>` tags is stripped at the hook layer before reaching the worker or database.

## Architecture

VibeLearn runs as a plugin with 5 lifecycle hooks:

```
SessionStart → UserPromptSubmit → PostToolUse → Stop → SessionEnd
```

The **worker service** runs locally on port **37778**, handles the analysis pipeline asynchronously, and stores all data in SQLite at `~/.vibelearn/vibelearn.db`.

VibeLearn does **not** inject context into your prompts. It only observes sessions from the outside and analyzes them after they end.

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Get up and running in 5 minutes
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/architecture/overview">
    How the pipeline works end-to-end
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    AI providers and settings
  </Card>

  <Card title="Cursor Integration" icon="cursor" href="/cursor">
    Use VibeLearn with Cursor IDE
  </Card>
</CardGroup>