vibe-learn: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Project Is

vibe-learn is a coding assistant plugin that observes what the AI does during a development session and helps users understand what was built. It works by registering lifecycle hooks that capture tool use events (file writes, edits, bash commands) into an append-only JSONL session log, then surfaces summaries at natural pause points.

Product principle: users can outsource thinking to an assistant, but they cannot outsource understanding. The project should make AI-assisted work easier to learn from, not just easier to accept.

It supports Claude Code, GitHub Copilot CLI, Codex App/CLI, OpenCode, Grok Build, and Cursor, with a generic adapter system for adding new assistants.

It requires no external API calls. Hooks are mechanical (bash + jq). The learning commands/prompts (/learn, /digest, /quiz, and the Copilot/Codex/Grok/Cursor skills) leverage the AI's own context window to generate explanations and reports.

Multi-Assistant Architecture

The project is split into a generic core and per-assistant adapters:

.claude-plugin/   ← Claude Code plugin packaging (the repo root is the plugin root)
  plugin.json     ← manifest; points commands/hooks at adapters/claude-code/
  marketplace.json ← single-plugin marketplace so `/plugin marketplace add gkaria/vibe-learn` works
bin/              ← on the Bash tool PATH while the plugin is enabled
  vibe-learn      ← → scripts/cli.sh
  vibe-learn-knowledge ← → scripts/knowledge.sh

scripts/          ← assistant-agnostic core (host payload translation stays in adapters)
  bootstrap.sh    ← SessionStart hook
  capture-prompt.sh ← UserPromptSubmit hook
  observe.sh      ← PostToolUse hook (<50ms, append-only)
  pause-summary.sh ← Stop hook
  setup.sh        ← global installer
  install.sh      ← per-project installer
  cli.sh          ← `vibe-learn` command dispatcher; `vibe-learn completion bash|zsh` is generated from its dispatch case labels and usage lines
  doctor.sh       ← `vibe-learn doctor`: read-only checks of jq, the install, each host's hooks, config keys, and the last session
  briefing.sh     ← `vibe-learn briefing`: static HTML session briefing + NotebookLM pack
  audio-prep.sh   ← `vibe-learn audio-prep`: finds the pack and walks through the NotebookLM upload
  knowledge.sh    ← knowledge ledger helper (record/touch/forget/list/due)
  recap.sh        ← `vibe-learn recap`: weekly "what I learned" markdown (read-only)
  identity.sh     ← sourced helper: harness, model, effort, version from payloads and host files
  health.sh       ← session log + meta → one assistant-health row per session segment (read-only)
  usage.sh        ← sourced helper: tool families and skills per session from the host's own session record
  health-report.sh ← `vibe-learn health`: before/after-change comparison of health rows (read-only)
  lib/session.jq  ← shared jq module: learning turns (`learning_prompt`, `work_events`) and `session_facts` (goal, files, failures) for the pause summary and briefing
  lib/briefing.jq ← `briefing_facts` (session_facts + timeline, ledger, diff, pause summary) and the page renderers that fill the templates
  lib/pack.jq     ← the NotebookLM pack, rendered from the same facts
  lib/briefing-{session,index,health}.html ← briefing page templates (static HTML with `{{name}}` placeholders)

adapters/
  claude-code/    ← Claude Code adapter
    hooks.json    ← hook registration template
    commands/     ← /learn, /digest, /quiz, and /explain slash command files
    install.sh    ← hook registration into ~/.claude/settings.json
  codex/          ← Codex App/CLI adapter
    hooks.toml    ← hook registration template (TOML)
    prompts/      ← learn, digest, quiz, and explain prompt-file fallbacks
    skills/       ← global Codex vibe-learn skill
    install.sh    ← hook registration into ~/.codex/config.toml
  opencode/       ← OpenCode adapter
    plugins/      ← local plugin for event capture
    commands/     ← /learn, /digest, /quiz, and /explain markdown commands
    install.sh    ← plugin/command install into .opencode or ~/.config/opencode
  grok/           ← Grok Build adapter
    hooks.json    ← hook registration template
    commands/     ← /learn, /digest, /quiz, and /explain slash command files
    skills/       ← /vibe-learn skill
    install.sh    ← hook file + skill/command install into ~/.grok or .grok
  cursor/         ← Cursor adapter
    hooks.json    ← hook registration template (merged into hooks.json)
    hooks/        ← vibe-learn.sh payload shim (Cursor envelope → core scripts)
    skills/       ← learn, digest, quiz, explain (slash-style) and vibe-learn skills
    install.sh    ← shim + hooks.json merge + skill install into ~/.cursor or .cursor
  copilot-cli/     ← GitHub Copilot CLI adapter
    hooks.json    ← native camelCase hook template
    hooks/        ← vibe-learn.sh payload shim (Copilot envelope → core scripts)
    skills/       ← learn, digest, quiz, explain, and vibe-learn skills
    install.sh    ← dedicated hook file + skill install into ~/.copilot or .github