🎯 the problem

# you copy this from ChatGPT
function generateToken(user, secret, expiresIn) {
  return jwt.sign({ id: user.id, email: user.email }, secret, { expiresIn })
}

# it works. you commit it.
git commit -m "add auth"

# 6 months later — production is down.
# nobody can explain what expiresIn does.
# including you.

explainit fixes this.

✨ how it works

git add .
git commit -m "add auth"

🧠 explainit — quick check before commit
──────────────────────────────────────────
  lib/auth.js — 18 lines changed

  What does the expiresIn parameter control in generateToken?

  Your answer: it sets how long the JWT token stays valid

  ✓ Exactly right — expiresIn defines the token lifetime in seconds.
    A high value means stolen tokens stay valid longer.

[main 3f2a1] add auth

One question. Fifteen seconds. You just learned something about the code you're shipping.

🚀 install

npm install -g explainit

requires Node.js 18+

⚡ quick start — 4 steps, under 2 minutes

step 1 — install

npm install -g explainit

step 2 — get a free Gemini API key

aistudio.google.com/apikey → sign in with Google → Create API key in new project → copy it

completely free · no credit card required · 1,500 requests/day per user

step 3 — connect your key

explainit setup

▸ setup — gemini api key
  ────────────────────────────────────────────
  get your free key at:
  → https://aistudio.google.com/apikey

  steps:
    1. sign in with google
    2. click 'create api key in new project'
    3. copy and paste below

  ◆ paste your gemini key: ████████████████████

  ✓ api key saved!
  you're all set — run explainit install to hook into git

step 4 — hook into git

explainit install

▸ installing git hook
  ────────────────────────────────────────────
  ✓ git hook installed
  ✓ run-quiz.js created

  ◆ every git commit will now trigger a quiz automatically

you're done. every git commit from now on will trigger a quiz automatically.

🔄 full workflow

npm i -g explainit
        ↓
explainit setup      ← paste your free Gemini API key
        ↓
explainit install    ← hooks into your git repo
        ↓
git add .
        ↓
git commit -m "your message"
        ↓
explainit detects changed files
        ↓
skips small changes ──→ commit goes through silently ✓
        ↓
Gemini reads your code
        ↓
1 question appears in terminal
        ↓
you type your answer
        ↓
instant AI feedback
        ↓
commit goes through regardless ✓

explainit never blocks your commit. it only teaches. adoption comes from being useful, not forceful.

📦 commands

| command | description | |---|---| | explainit setup | connect your free Gemini API key | | explainit install | hook into git (run once per project) | | explainit scan <file> | preview a file and its contents | | explainit quiz <file> | manually quiz yourself on any file | | explainit score | view your progress, history and streak |

📊 track your progress

explainit score

  total quizzes  12     correct  9      wrong  3

  score  75%   streak  4 days

  ████████████████████████░░░░░░  75%

▸ recent activity
  ─────────────────────────────────────────────────────────
  ✓  auth.js         27 Mar, 14:32    What does bcrypt.compare do?
  ✓  quiz.js         27 Mar, 12:10    Why is snippet sliced to 300...
  ✗  scores.js       26 Mar, 09:44    What does getStreak return?
  ✓  ai.js           25 Mar, 18:21    Why is code sliced to 300 chars?

▸ most quizzed files
  ─────────────────────────────────────────────────────────
  ◆  auth.js                   5 quizzes      80% correct
  ◆  quiz.js                   4 quizzes      75% correct
  ◆  ai.js                     3 quizzes      66% correct

🔑 api key — per user, always free

explainit uses a bring your own key model.

each user provides their own free Gemini API key. this means:

• ✓ no shared quota — your usage never affects anyone else
• ✓ completely free — 1,500 requests/day is more than enough
• ✓ scales to any number of users
• ✓ your key is stored locally at ~/.explainit/config.json
• ✓ nothing leaves your machine except API calls to Gemini

get your free key at aistudio.google.com/apikey

🏗️ architecture

explainit/
├── bin/
│   └── explainit.js      ← CLI entry point — all commands
├── lib/
│   ├── ai.js             ← Gemini API — generate & evaluate
│   ├── quiz.js           ← quiz loop — questions & answers
│   └── scores.js         ← local score storage & streak logic
├── run-quiz.js           ← git hook bridge (auto-created on install)
└── package.json

🛠️ tech stack

| tool | purpose | |---|---| | Node.js | runtime | | Commander.js | CLI framework | | Gemini API | AI question generation & evaluation | | Chalk | terminal colours & styling | | Ora | terminal spinner |

🤝 contributing

contributions, issues and feature requests are welcome!

# clone the repo
git clone https://github.com/shekharrs/explainit.git
cd explainit

# install dependencies
npm install

# link locally for development
npm link

# test your changes
explainit setup
explainit install
explainit scan bin/explainit.js
explainit score

to contribute:

1. fork the project
2. create your branch   git checkout -b feature/amazing-feature
3. commit your changes  git commit -m "add amazing feature"
4. push to the branch    git push origin feature/amazing-feature
5. open a pull request

📋 roadmap

• [x] auto-quiz on git commit via pre-commit hook
• [x] AI question generation with Gemini
• [x] answer evaluation with instant feedback
• [x] local score tracking and streak system
• [x] per-user API key — bring your own key model
• [x] first-time setup wizard
• [ ] VS Code extension
• [ ] support for more languages (Go, Rust, Java)
• [ ] team leaderboard mode
• [ ] weekly email digest of your weakest files
• [ ] --strict mode that requires 70%+ to commit

🐛 issues & support

found a bug? have a feature idea?

→ open an issue

📄 license

MIT © Shekhar

built for developers who actually want to understand their code

if explainit helped you — drop a ⭐ on the repo. it means a lot.