✍️ GitScribe

AI-powered CLI tool for generating commit messages, changelogs, and release notes.

GitScribe analyzes your Git diffs through LLMs and generates precise, Conventional Commits-compliant commit messages — so you never write "fix stuff" again.

✨ Features

• 🤖 AI Commit Messages — Analyze staged diffs → generate conventional commits → confirm → done
• 📋 Changelog Generation — Auto-generate CHANGELOG.md from commit history (Keep a Changelog format)
• 📝 Release Notes — Human-readable, narrative release notes for stakeholders
• ✅ Commit Validation — CI-friendly validation with exit codes (0/1)
• 🔒 Secret Detection — Scans diffs for leaked API keys, tokens, passwords before sending to LLM
• 🔌 Multi-Provider — OpenAI, Anthropic (Claude), Google Gemini, Ollama (local)
• 🛡️ Security-First — Input sanitization, response validation, no telemetry, local-only mode

🚀 Quick Start

# Try without installing
npx gitscribe commit

# Global install
npm install -g gitscribe

# First-time setup
gitscribe init

# Generate a commit message
git add .
gitscribe commit

# Generate changelog
gitscribe changelog

# Validate last commit
gitscribe validate

📸 How It Works

$ gitscribe commit

  ✅ 3 files changed: src/auth/login.ts, src/auth/token.ts, tests/auth.test.ts

  🤖 Suggested commit message:

  ┌─────────────────────────────────────────────────────┐
  │  feat(auth): add JWT refresh token rotation         │
  │                                                     │
  │  - Implement automatic token refresh on expiry      │
  │  - Add rotation to prevent replay attacks           │
  │  - Add unit tests for token refresh flow            │
  └─────────────────────────────────────────────────────┘

  ? What would you like to do?
    ❯ ✅ Accept and commit
      ✏️  Edit message
      🔄 Regenerate
      ❌ Cancel

🧰 Commands

| Command | Description | | ------------------------- | ------------------------------------------------- | | gitscribe init | Interactive setup wizard | | gitscribe commit | Generate AI commit message from staged changes | | gitscribe changelog | Generate CHANGELOG.md from commit history | | gitscribe release-notes | Generate human-readable release notes | | gitscribe validate | Validate commits against conventional commit spec |

Commit Options

gitscribe commit              # Interactive mode (default)
gitscribe commit --auto       # Auto-accept without confirmation
gitscribe commit --dry-run    # Preview without committing
gitscribe commit --force      # Skip secret detection warnings

Changelog Options

gitscribe changelog                    # Last tag → HEAD
gitscribe changelog --from v1.0.0      # From specific tag
gitscribe changelog --overwrite        # Regenerate entire file
gitscribe changelog -o RELEASE.md      # Custom output file

Release Notes Options

gitscribe release-notes                         # Markdown (default)
gitscribe release-notes --format json           # JSON output
gitscribe release-notes --from v1.0.0 --to v2.0.0
gitscribe release-notes -o release.md           # Write to file

Validate Options

gitscribe validate            # Validate last commit
gitscribe validate --last 5   # Validate last 5 commits

⚙️ Configuration

Create a .gitscriberc file in your project root:

{
  "provider": "openai",
  "model": "gpt-4o-mini",

  "conventions": {
    "types": ["feat", "fix", "docs", "refactor", "test", "chore"],
    "scopes": ["auth", "api", "ui"],
    "maxSubjectLength": 72,
    "requireScope": false
  },

  "security": {
    "scanForSecrets": true,
    "maxDiffLines": 10000
  }
}

Config Precedence

1. CLI flags (--provider openai)
2. Environment variables (GITSCRIBE_PROVIDER)
3. Project .gitscriberc
4. Global ~/.gitscribe/config.json
5. Built-in defaults

Environment Variables

| Variable | Description | | -------------------- | ------------------- | | GITSCRIBE_API_KEY | LLM API key | | GITSCRIBE_PROVIDER | Provider name | | GITSCRIBE_MODEL | Model name | | GITSCRIBE_VERBOSE | Enable verbose mode | | NO_COLOR | Disable colors |

🔌 Provider Setup

OpenAI (Default)

export GITSCRIBE_API_KEY="sk-..."
gitscribe init  # Select OpenAI

Anthropic (Claude)

export GITSCRIBE_API_KEY="sk-ant-..."
gitscribe init  # Select Anthropic

Google Gemini

export GITSCRIBE_API_KEY="AI..."
gitscribe init  # Select Gemini

Ollama (Local — Free, Private)

ollama serve                    # Start Ollama
ollama pull llama3              # Pull a model
gitscribe init                  # Select Ollama

No API key required. Your code never leaves your machine.

🔒 Security

• No telemetry — Zero data collection
• Secret scanning — Detects API keys, tokens, passwords in diffs before sending to LLM
• Input sanitization — Prevents shell injection via crafted filenames/branches
• Response validation — Strips prompt injection from AI responses
• Local mode — Use Ollama for fully offline operation
• No eval() — Zero dynamic code execution

🏗️ Tech Stack

| Layer | Technology | | ----------------- | ------------------------------------------------ | | Language | TypeScript | | Runtime | Node.js ≥ 18 | | CLI | Commander.js + Inquirer.js | | Git | simple-git | | LLM SDKs | openai, @anthropic-ai/sdk, @google/generative-ai | | Testing | Vitest (61 tests) | | Build | tsup | | Config Validation | Zod |

🧪 Development

git clone https://github.com/yourusername/gitscribe.git
cd gitscribe
npm install
npm test        # Run tests
npm run build   # Build

📄 License

MIT