Understand your code before you ship it.

Quiz your staged Git changes, understand AI-generated code, scan files, and generate clear commit messages.

A lightweight developer CLI that adds an understanding check to your Git workflow. It inspects staged diffs, scans files for line statistics and risk metrics, asks a quick multiple-choice question in the terminal, and helps developers review AI-generated code before committing.

Table of contents

• The problem
• Features
• Requirements
• Quick start
• How it works
• Usage
• Command reference
• Tracking your progress
• Inspecting and scanning files
• API key and privacy
• Project structure
• Technology stack
• Troubleshooting
• Development
• Contributing
• Roadmap
• Issues and support
• License

The problem

AI coding tools can generate working code quickly, but working code is not always code you fully understand. When a change causes problems later, it can be hard to remember why a particular implementation was added.

explainit helps you pause and review your changes before they become part of your codebase.

Features

• Quiz staged changes: generate a short multiple-choice question from your staged Git diff.
• Explain code changes: get a readable summary of changes, key decisions, and potential concerns.
• Generate commit messages: create a commit message from the staged diff.
• Scan and inspect files: preview target files, view line statistics, and assess risk levels before committing (explainit scan).
• Track quiz progress: view previous quiz results and your score history.

The quiz is a check on your own understanding. It does not replace tests, code review, or security checks.

Requirements

• Node.js and npm (see the Node.js badge above for the supported version)
• Git
• A Gemini API key from Google AI Studio

Quick start

Follow these four steps to set up explainit in a Git repository.

Step 1: Install explainit

Install the package globally with npm:

npm install -g explainit

Check that the command is available:

explainit --help

Step 2: Get a Gemini API key

1. Open Google AI Studio and sign in with your Google account.
2. Select Create API key in new project.
3. Copy the generated key.

Gemini API access, quotas, and pricing vary by account and may change. Check Google's current terms in AI Studio before use.

Step 3: Connect your API key

Run the setup command and follow the prompts:

explainit setup

Example output:

Setup — Gemini API key
--------------------------------------------
Get your API key at:
https://aistudio.google.com/apikey

Steps:
  1. Sign in with Google
  2. Select "Create API key in new project"
  3. Copy and paste the key below

Paste your Gemini API key: [input hidden]

API key saved.
You're all set — run explainit install to connect it to Git.

The key is stored locally in ~/.explainit/config.json.

Security note: the key is stored as plain text. Keep the file private (for example, chmod 600 ~/.explainit/config.json on macOS/Linux) and never share it in logs, screenshots, or issue reports.

Step 4: Connect explainit to Git

From the repository where you want the automatic quiz, run:

explainit install

Example output:

Installing Git hook
--------------------------------------------
Git hook installed
run-quiz.js created

Every Git commit can now trigger a quick understanding check.

You are ready to go. Stage your changes and commit as usual:

git add .
git commit -m "describe your changes"

During the pre-commit step, explainit asks a short question. Answer it, or enter s to skip. The hook does not block your commit.

To bypass all Git hooks for a single commit, use Git's standard flag:

git commit --no-verify -m "describe your changes"

How it works

1. You stage changes with git add.
2. explainit reads the staged diff using git diff --cached.
3. If the Git hook is installed, a short quiz is shown during the pre-commit step.
4. You answer the question or skip it, and the commit proceeds.

The quiz may skip small changes and documentation-only edits.

Install explainit
       |
       v
Configure the Gemini API key
       |
       v
Install the Git hook in your repository
       |
       v
Make changes and stage files
       |
       v
Commit your changes
       |
       v
explainit reviews the staged diff
       |
       v
Answer the quiz or skip it
       |
       v
The commit proceeds

Usage

You can run commands directly instead of relying only on the Git hook.

Explain your staged changes:

explainit explain

Explain a specific file:

explainit explain src/auth.js

Generate a commit message from the staged diff:

explainit msg

Run a quiz on your staged changes:

explainit quiz

Run a quiz on a specific file:

explainit quiz src/auth.js

View your quiz history:

explainit score

Preview and scan a file:

explainit scan src/auth.js

Command reference

| Command | Alias | Description | | ------------------------ | ----- | -------------------------------------------------------------- | | explainit setup | n/a | Configure your Gemini API key. | | explainit install | n/a | Install the Git hook for the current repository. | | explainit explain [file] | exp | Explain staged changes or a specific file, including key decisions and potential risks. | | explainit msg | m | Generate a commit message from the staged diff. | | explainit quiz [file] | q | Quiz yourself on staged changes or a specified file. | | explainit score | sc | View quiz results, history, and streak information. | | explainit scan <file> | s | Preview a file, inspect line statistics, additions, and risk metrics. |

Run explainit --help to see the commands and aliases available in your installed version.

Tracking your progress

explainit score

The score command shows your quiz history and progress, including correct and incorrect answers and streak information.

Inspecting and scanning files

Inspect any source file before staging or committing:

explainit scan src/auth.js

Example terminal output:

  🧠 explainit  ·  understand your code  ·  v2.0.4

  ▸ file info
  ────────────────────────────────────────────
  📄  path                src/auth.js
  📏  lines               85
  💾  size                2.8 kb

  ▸ preview
  ────────────────────────────────────────────
    1 │ import jwt from "jsonwebtoken";
    2 │ import { db } from "../config/db.js";
    3 │ 
    ...
  ... 65 more lines

  ✓ scan complete  →  explainit explain src/auth.js

The scan command previews a target file with line statistics, addition metrics, and quick risk level insights before committing or pushing.

API key and privacy

explainit uses a bring-your-own-key model: each user configures their own Gemini API key.

• Your API key is stored locally in ~/.explainit/config.json.
• AI-powered features may send staged diffs or file content to the Gemini API to generate questions, explanations, or commit messages.
• Avoid using the tool on confidential or sensitive code unless your organization's policies allow sending that content to the configured AI provider.
• Never share your API key in logs, screenshots, or issue reports.
• Gemini API quotas and pricing can change. Consult Google's current documentation.

Project structure

explainit/
├── bin/
│   └── explainit.js    # CLI entry point and commands
├── lib/
│   ├── ai.js           # Gemini API integration
│   ├── diff.js         # Staged Git diff processing
│   ├── quiz.js         # Quiz prompts and answer checking
│   └── scores.js       # Quiz history and streak tracking
└── package.json

Technology stack

| Technology | Purpose | | ------------------------------------------------ | ----------------------------------------------- | | Node.js | JavaScript runtime | | Commander.js | Command-line interface | | Gemini API | Quiz questions, explanations, and commit messages | | Chalk | Terminal output styling | | Ora | Terminal spinner |

Troubleshooting

explainit is not recognized

Reinstall the package:

npm install -g explainit

Restart your terminal and run explainit --help. If the command is still unavailable, check that npm's global executable directory is in your PATH.

The API key is missing or invalid

Run setup again:

explainit setup

Check that the key was copied correctly and that your Gemini API access is enabled.

The quiz does not reflect my changes

The quiz uses staged changes. Check what is staged and add the files you want to review:

git status
git add <file>
git diff --cached
explainit quiz

The Git hook does not run

Run the install command from the repository where you want the hook enabled:

explainit install

Then check your Git hook configuration and read any messages printed by explainit.

Development

To work on the project locally:

git clone https://github.com/shekharrs/explainit.git
cd explainit
npm install
npm link

npm link links your local checkout so you can run the development version as a global command. Verify it with:

explainit --help

Contributing

Contributions, bug reports, and feature requests are welcome.

1. Fork the repository.

2. Create a feature branch:

   git checkout -b feature/your-feature

3. Make and test your changes.

4. Commit your changes:

   git commit -m "describe your changes"

5. Push the branch and open a pull request.

When reporting a bug, include your operating system, Node.js version, the command you ran, and the relevant error output. Remove API keys and sensitive code before sharing logs.

Roadmap

• [ ] Model Context Protocol (MCP) support for AI coding environments
• [ ] Visual Studio Code extension
• [ ] Team leaderboard
• [ ] Optional strict mode with additional commit controls

Issues and support

Found a bug or have a feature request? Open an issue on GitHub.

License

MIT. See the LICENSE file.

Built for developers who want to understand the code they ship.

GitHub repository · npm package