Skip to main content

​
Prerequisites

  • Bun — worker runtime and build tool
  • Node.js 18+ — for npm tooling
  • Git

​
Build from Source

git clone https://github.com/anergcorp/vibelearn.git
cd vibelearn
npm install
npm run build-and-sync
build-and-sync runs scripts/build-hooks.js (via Bun) which:
  1. Compiles TypeScript hooks → ESM scripts → bundles with esbuild
  2. Bundles worker-service.cjs (~1.7MB)
  3. Bundles vl-cli.cjs (~10KB)
  4. Syncs built artifacts to ~/.claude/plugins/marketplaces/vibelearn/
  5. Restarts the worker

​
Build Artifacts

OutputSourcePurpose
plugin/scripts/*-hook.jssrc/hooks/*.tsHook scripts
plugin/scripts/worker-service.cjssrc/services/worker-service.tsWorker bundle
plugin/scripts/vl-cli.cjssrc/cli/vl/index.tsvl CLI bundle
plugin/scripts/worker-wrapper.cjspre-builtBun process manager

​
Development Workflow

# Make changes to src/

# Rebuild hooks only (fast)
bun scripts/build-hooks.js

# Full build + restart worker
npm run build-and-sync

# Watch worker logs
tail -f ~/.vibelearn/logs/vibelearn-$(date +%Y-%m-%d).log

​
Adding a New Analysis Step

  1. Create src/services/analysis/MyAnalyzer.ts
  2. Add a new route in src/services/worker/http/routes/VibeLearnRoutes.ts
  3. Call it from src/hooks/summarize.ts (the Stop hook dispatcher)
  4. Add any new columns to src/services/sqlite/migrations.ts (increment migration ID)

​
Adding a New vl CLI Command

Edit src/cli/vl/index.ts. The CLI uses bun:sqlite directly — no HTTP to worker. 
async function cmdMyCommand() {
  const db = new Database(`${homedir()}/.vibelearn/vibelearn.db`);
  const rows = db.query('SELECT * FROM vl_concepts LIMIT 10').all();
  // ...
}

​
Database Migrations

Add migrations to the array in src/services/sqlite/migrations.ts: 
{ id: 9, sql: `ALTER TABLE vl_concepts ADD COLUMN my_new_column TEXT` }
Migrations run automatically on worker startup. Never modify existing migration IDs.

​
Code Style

  • TypeScript strict mode
  • ESM modules throughout (import/export, no require)
  • Hooks: always exit 0 (never block the IDE)
  • Worker errors: log at ERROR level, continue execution
  • Analysis steps: independent — step failure must not block subsequent steps

​
Testing

VibeLearn uses real-world testing: install the plugin, run coding sessions, check vl quiz. The analysis pipeline is LLM-dependent and not meaningfully unit-testable. For worker endpoint testing: 
# Test session init
curl -X POST http://127.0.0.1:37778/api/sessions/init \
  -H "Content-Type: application/json" \
  -d '{"contentSessionId":"test-123","project":"test","prompt":"test"}'

# Test health
curl http://127.0.0.1:37778/api/health | jq .

​
Publishing

npm run build-and-sync
# Artifacts in plugin/ are ready to publish to the marketplace
Plugin identity: vibelearn@anergcorp