learning-first

Learning-First 🎓

Your AI pair programmer becomes your AI mentor — with a live visual dashboard.

A plugin for GitHub Copilot CLI and Claude Code that transforms your coding agent from "I'll build it for you" into "Let me help you understand it so you can build it yourself."

"The best AI assistant isn't the one that writes the most code — it's the one that makes you need it less."

✨ Visual First

The dashboard at http://localhost:3142 auto-starts with every session — your learning progress, quiz performance, spaced repetition schedule, and achievements update live via SSE as you work in the CLI. No manual server management needed.

---

What It Feels Like

First time in a new repo

You:  Add JWT authentication to the API

Agent: 👋 Welcome! This is your first time in payments-api with learning-first.
       Would you like learning mode active for this repository?
       - Yes — I'll teach concepts before you implement (recommended)
       - No — I'll work normally

You:  Yes

Agent: I'm using learning-first to teach the relevant concepts before we implement.

       To build JWT auth well, you'll need to understand 4 things about this codebase:

       📚 Learning Path:
       1. How the existing auth layer works (this codebase)
       2. JWT fundamentals (tokens, claims, signatures)
       3. Express middleware patterns
       4. Security considerations

       Some of these may be familiar — we'll adjust as we go. Ready?

The teaching flow

Agent: Let me show you how auth currently works here.

       📄 src/middleware/auth.ts (lines 12-28)
       [shows actual code from the codebase]

       What do you notice about how this middleware handles the request?

You:  It checks for a session cookie and validates it against the database

Agent: Exactly. Now — JWT would replace that database lookup. Why might that
       be useful? What trade-off are you making?

You:  It's faster because you don't hit the DB, but you can't revoke tokens easily

Agent: 🎯 That's the core trade-off. You just identified the #1 design decision
       you'll need to make for this feature.

       Quick check — which part of a JWT contains the user's data?
       A) Header
       B) Payload
       C) Signature
       D) All three

You:  B

Agent: ✅ Right — the payload carries claims. The header says "how it's signed"
       and the signature proves it wasn't tampered with.

When you're stuck (graduated help)

Agent: Looking at the existing middleware, how would you modify it to
       validate a JWT instead of a session cookie?

You:  ...I'm not sure where to start

Agent: That's okay — think about it for a moment.
       What does the current middleware receive as input?        ← Level 0: encourage

You:  The request object with headers

Agent: Good. And where would a JWT typically be in those headers?  ← Level 1: reframe

You:  The Authorization header?

Agent: Exactly. So what would your first line of code do?          ← Level 2: hint

You:  Extract the token from the Authorization header

Agent: 🎯 Now you're rolling. The pattern is:
       `const token = req.headers.authorization?.split(' ')[1]`
       What would you do with it next?

When you know your stuff (progressive assistance)

As you demonstrate mastery, the agent gives you more runway:

Agent: Based on your quiz results (92% accuracy, 8 topics mastered in this repo),
       you're at Level 3. I'll provide scaffolding — you fill in the logic.

       Here's the middleware structure:

       // src/middleware/jwt-auth.ts
       // TODO: Extract token from Authorization header
       // TODO: Verify token with secret
       // TODO: Attach decoded payload to req.user
       // TODO: Handle expired/invalid tokens

       I've also set up a failing test:

       // tests/jwt-auth.test.ts
       test('rejects request when token is expired', async () => {
         // TODO: Your assertion here
       });

       Go for it — I'll review when you're ready.

When you want to skip

You:  I know JWT well, skip

Agent: Got it — skipping JWT module. Moving to Express middleware patterns.
       [no guilt, no pushback, recorded for next time]

When you want to override

You:  I'm under deadline pressure, just build it

Agent: Got it — switching to implementation mode.
       Would you like me to:
       - Use a structured workflow (brainstorming → planning → TDD)
       - Just implement directly

       I'll prepare a catch-up curriculum for next time. 📝

       [next session]
Agent: Welcome back! Last time you used override for JWT auth.
       Want a quick catch-up on the concepts? (Just say 'catch up' anytime)

---

Achievements 🏆