✍️ Scribe

AI-powered Git Commit Assistant that generates clean, meaningful commit messages from your staged changes using LLMs.

Generate meaningful Git commit messages instantly from your staged changes using OpenAI, Claude, Gemini, or Ollama.

🧩 Use Scribe Your Way

Scribe is designed to fit into your existing Git workflow:

• 💻 CLI: Generate commit messages directly from your terminal, no matter which IDE or editor you use.
• 🪝 Git Hook: Integrate Scribe into your native git commit workflow and generate commit messages automatically.
• 🧩 VS Code Extension: If you use VS Code, generate commit messages directly from the Source Control panel using the dedicated Scribe extension.

The Scribe CLI is the core of the project, while the VS Code extension provides a convenient native experience for VS Code users.

👉 Get the Scribe VS Code Extension

---

📚 Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• ⚙️ Configuration
• 📖 Usage
• 🔗 Git Hook Integration
• ⚡ Performance & Caching
• 🛠️ Project Structure
• ⭐ Support
• 📄 License

---

✨ Features

• 🤖 Multi-Provider Support: OpenAI, Anthropic Claude, Google Gemini, and Ollama.
• 💬 Interactive CLI: Built with Cobra and Survey.
• 🏷️ Context Awareness: Detects ticket IDs from branch names.
• ⚡ SHA-256 Caching: Reuses responses for identical staged diffs.
• 🧩 Large Diff Handling: Chunking and summarization for large changes.
• 🔗 Git Hook Support: Works as both a CLI and pre-commit hook.

💡 At a Glance

Capability	Details
🤖 AI Providers	OpenAI, Claude, Gemini, Ollama
⚡ Performance	SHA-256 caching for identical staged diffs
🏷️ Context	Automatically detects ticket IDs from branch names
🧩 Large Changes	Chunking and summarization for large diffs
🪝 Git Integration	CLI and pre-commit hook support

---

📦 Installation

Option 1: Pre-compiled Binaries (Recommended for Windows / Mac / Linux)

Download the latest binary from Releases.

For macOS / Linux:

tar -xzf scribe_*_linux_amd64.tar.gz
sudo mv scribe /usr/local/bin/

For Windows:

Extract the .zip file, open PowerShell in that directory, and run:

.\install.ps1

(Or manually add the extracted folder containing scribe.exe to your system's PATH)

Option 2: Using Go Install

If you have Go 1.21+ installed, this is the easiest way:

go install github.com/alan-shabrandi/scribe/cmd/scribe@latest

Note for Go developers: If you previously installed Scribe via go install, make sure your $GOPATH/bin doesn't conflict with system PATH binaries.

Option 3: Build from Source

Prerequisites

• Go 1.21+
• Git

git clone https://github.com/alan-shabrandi/scribe.git
cd scribe

# Linux / macOS:
go build -o scribe ./cmd/scribe

# Windows (PowerShell):
go build -o scribe.exe ./cmd/scribe
.\install.ps1

---

🚀 Quick Start

Once Scribe is installed, configure your provider and generate your first commit message:

scribe config set provider openai
scribe config set api_key YOUR_API_KEY

git add .
scribe generate

That's it — Scribe analyzes your staged changes and generates clean commit message candidates for you to choose from.

Need more configuration options? See the Configuration section below.

---

⚙️ Configuration

Scribe stores its configuration in:

~/.scribe.yaml

Setting	Description	Example
provider	LLM provider used to generate commit messages	openai
model	Model used by the selected provider	gpt-4o
style	Commit message style	conventional
api_key	API key for the selected provider	your-api-key

Configure Scribe using:

scribe config set provider openai
scribe config set api_key "your-api-key"
scribe config set model "gpt-4o"
scribe config set style "conventional"

---

📖 Usage

1. Stage Your Changes

git add .

2. Generate Commit Messages

scribe generate

3. Choose a Commit Message

Scribe analyzes your staged changes and presents multiple candidates:

🔍 Fetching staged git changes...
📌 Detected Context: Branch 'feature/PROJ-892-add-cache'
✔ Generating candidate commit messages via 'openai'...

? Select a commit message option:

▸ feat(cache): add SHA-256 caching for staged diffs (PROJ-892)
  perf(diff): skip LLM invocation on identical git diff (PROJ-892)
  ✏️ Edit custom message in system editor
  🚫 Cancel

---

🔗 Git Hook Integration

Integrate Scribe directly into your native Git workflow. Once installed, simply run git commit as usual and let Scribe generate candidates for you automatically.

scribe hook install

To remove the hook:

scribe hook uninstall

This lets Scribe integrate into your commit workflow without requiring you to manually run the generation command every time.

---

⚡ Performance & Caching

Scribe uses SHA-256 caching to avoid repeated LLM requests for identical staged diffs.

Cached responses are stored in:

~/.scribe_cache.json

This helps reduce unnecessary LLM calls and makes repeated commit message generation faster.

---

🛠️ Project Structure

scribe/
├── cmd/
│   └── scribe/
├── internal/
│   ├── cache/
│   ├── config/
│   ├── git/
│   └── llm/
├── go.mod
└── README.md

---

💖 Support & Contributing

If Scribe saves you time and makes your commits cleaner, please consider giving it a ⭐!

• 🐛 Found a bug? Open an issue on GitHub Issues.
• 💡 Have an idea or fix? Contributions are always welcome! Check out our CONTRIBUTING.md.

---

📄 License

Licensed under the MIT License.

See LICENSE for details.