Clean commit histories and polished documentation, without the manual overhead.
- Overview
- Features
- Tech Stack
- Project Structure
- Installation
- Configuration
- Usage & Commands
- How It Works
- Security Notice
- Contributing
- License
git-commit-craft is a production-ready CLI tool built on Node.js ESM that uses Google's Gemini 3.5 Flash model via the official @google/genai SDK to automate two of the most tedious parts of software development:
- ✅ Writing structured, standards-compliant Conventional Commit messages from your
git diff - ✅ Generating comprehensive, professional README.md files from your project's structure and metadata
No more staring at a blank commit prompt or a blank README file.
| 🤖 AI-Generated Commits | Analyzes staged (or unstaged) git diff output and produces a fully compliant Conventional Commit message |
| 🔄 Interactive Commit Workflow | Accept, edit, regenerate, or cancel the AI-suggested commit directly from the terminal |
| 📄 Smart README Generation | Scans your directory tree, detected language, and package.json to draft a complete README |
| ⚡ Powered by Gemini 3.5 Flash | Frontier-level intelligence with sub-second response times, running with thinking disabled for maximum speed |
| 🔐 Secure Config Management | Caches your Gemini API key locally at ~/.git-commit-craft/config.json, or reads it from GEMINI_API_KEY |
| 🎨 Polished Terminal UX | Custom-rendered boxes, spinners, and color-coded success/warning/error indicators |
| Category | Technology |
|---|---|
| Runtime | Node.js >=18.0.0 (ESM) |
| AI Engine | @google/genai — Gemini 3.5 Flash |
| CLI Framework | commander |
| Interactive Prompts | inquirer |
| Terminal Spinners | ora |
| Terminal Styling | chalk |
git-commit-craft/
├── package.json
└── src/
├── cli.js
├── config.js
├── ai.js
├── git.js
├── scanner.js
└── ui.js
| File | Responsibility |
|---|---|
src/cli.js |
CLI entry point — defines craft-commit and craft-readme commands |
src/config.js |
Secure API key storage and retrieval (env var or local config file) |
src/ai.js |
Gemini 3.5 Flash prompt engineering and generation pipeline via @google/genai |
src/git.js |
Native Git operations — diffing and committing |
src/scanner.js |
Project directory analysis, language detection, package.json parsing |
src/ui.js |
Terminal rendering — boxes, spinners, and status messages |
flowchart LR
A[git-commit-craft CLI] --> B{Command}
B -->|craft-commit| C[git.js: Get Diff]
C --> D[ai.js: Generate Commit Message]
D --> E[ui.js: Interactive Review]
E -->|Confirm| F[git.js: Commit]
B -->|craft-readme| G[scanner.js: Analyze Project]
G --> H[ai.js: Generate README]
H --> I[Write README.md to Disk]
git clone https://github.com/pegasusdev18/git-commit-craft.git
cd git-commit-craft
npm install
npm linkOnce linked, the git-commit-craft command becomes available globally from any Git repository on your machine.
npm unlink -g git-commit-craftYou'll need a free Gemini API Key from Google AI Studio.
Run any command below and the tool will securely prompt you for the key on first use, saving it locally at:
~/.git-commit-craft/config.json
export GEMINI_API_KEY="your_actual_api_key_here"🔒 The
GEMINI_API_KEYenvironment variable always takes priority over the locally cached config file.
| Command | Description |
|---|---|
git-commit-craft craft-commit |
Analyzes staged changes and guides you through an interactive AI-assisted commit |
git-commit-craft craft-readme |
Scans the project directory and generates a complete README.md file |
git add .
git-commit-craft craft-commit✔ Commit message generated.
┌──────────────────────────────────────────────┐
│ Generated Commit Message │
├──────────────────────────────────────────────┤
│ feat(auth): add JWT-based session validation │
│ │
│ - Implement token verification middleware │
│ - Attach decoded user to socket session │
└──────────────────────────────────────────────┘
? Do you want to commit with this message?
❯ Yes, commit now
Edit message
Regenerate message
Cancel
If no staged changes exist, the CLI will offer to analyze unstaged changes instead.
git-commit-craft craft-readme✔ Project structure scanned.
✔ README.md generated successfully.
✔ Saved to /path/to/project/README.md
If a README.md already exists in the current directory, you'll be prompted before it's overwritten.
- Reads
git diff --cached(falls back togit diffif nothing is staged). - Sends the diff to Gemini 3.5 Flash with a strict system prompt enforcing the Conventional Commits v1.0.0 specification.
- Runs with
thinkingConfig: { thinkingBudget: 0 }to disable extended reasoning and maximize response speed. - Strips any accidental code fences from the model's response.
- Presents the result in an interactive review loop — accept, edit, regenerate, or cancel.
- On confirmation, runs
git commit -m "<message>"natively.
- Recursively scans the project directory (up to a bounded depth, skipping
node_modules,.git,dist, etc.). - Detects the dominant programming language by counting file extensions.
- Parses
package.json, if present, for name, dependencies, and scripts. - Sends this metadata to Gemini 3.5 Flash with a system prompt tailored for professional README generation.
- Writes the raw Markdown response directly to
README.md.
Starting June 19, 2026, Google requires all Gemini API keys to be restricted to generativelanguage.googleapis.com. Unrestricted keys will be rejected.
- Keys generated directly from Google AI Studio are restricted by default — no extra action needed.
- If your key was generated from a Google Cloud project, restrict it manually under API restrictions in Google Cloud Credentials.
Contributions are welcome and appreciated.
- Fork the repository
- Create a feature branch —
git checkout -b feature/amazing-feature - Commit your changes —
git-commit-craft craft-commit - Push the branch —
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
⭐ If this tool saves you time, consider giving it a star! ⭐