Git-Sensei

Smart Context. Universal AI Adapter. Professional Commits.

A CLI tool that generates professional commit messages using any AI provider (Antigravity, Claude Code, OpenAI, Ollama).

Features

• Universal Providers - Switch between Antigravity, Claude Code, OpenAI, or local LLMs with one command
• Secrets Shield - Scans diffs for API keys, tokens, passwords before sending to AI
• Smart Context - Auto-links commits to issue IDs from branch names (Jira, GitHub, GitLab, Linear, Azure DevOps)
• Branch Type Detection - Auto-detects commit type from branch prefix (feature/ → feat, fix/ → fix)
• Conventional Commits - Generates properly formatted commit messages
• Offline Fallback - Heuristic engine works when AI is unavailable
• Interactive Review - Edit, retry, or approve before committing
• Editor Integration - Edit commit messages in your preferred IDE (VS Code, PyCharm, etc.)

Installation

pip install git-sensei-ai

Requirements

• Python 3.9+
• Git
• One of the AI CLI tools:

Quick Start

sensei init      # First time setup (choose AI provider)
git add .        # Stage your changes
sensei commit    # Generate commit with AI

Git Hooks & Pre-commit

1. Traditional Git Hook

You can install a native Git hook in your local repository to automatically generate commit messages whenever you run git commit (without having to type sensei commit manually):

sensei install-hook

2. Pre-commit Framework Integration

To enforce Conventional Commits formatting across your team, you can use Git-Sensei as a linter inside the pre-commit framework.

Add the following to your project's .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Lukasz-Szymanski/git_sensei
    rev: v0.14.0  # Use the latest release version tag
    hooks:
      - id: git-sensei-lint

Then install the hook with:

pre-commit install --hook-type commit-msg

This hook will automatically validate all commit messages during the commit-msg git stage.

First Time Setup

$ sensei init
Welcome to Git-Sensei!

Select your AI provider:

  1. Google Antigravity (npm i -g @google/antigravity-cli)
  2. Claude Code (npm i -g @anthropic-ai/claude-code)
  3. OpenAI GPT-4 (pip install chatgpt-cli)
  4. Ollama (https://ollama.ai)

Select provider [1]: 2

Selected: Claude Code
Testing connection... OK

Config saved to ~/.sensei.toml
Default provider: claude

Ready! Run: git add . && sensei commit

The wizard will:

• Detect existing configuration and ask before overwriting
• Test the connection with a real AI request
• Show installation instructions if the provider is not found

Commands

Examples

sensei commit                 # Use default provider (Antigravity CLI)
sensei amend                  # Rewrite last commit message
sensei squash                 # Auto-squash commits against the base branch
sensei pr                     # Generate and create PR via GitHub CLI
sensei commit -p gemini-api   # Use Native Gemini API (requires GEMINI_API_KEY)
sensei commit --emoji         # Generate with emojis (e.g. ✨ feat: add login)
sensei commit -d              # Preview without committing
sensei use gemini-api         # Set Gemini API as default
sensei ls                     # List providers (* = default)
sensei check                  # Check default provider
sensei install-hook           # Set up standard git hook

Configuration

Sensei loads configuration from (in order of priority):

1. ~/.sensei.toml (user config - highest priority)
2. ./.sensei.toml (project config)
3. Package defaults

Example .sensei.toml

[core]
default_provider = "claude"

[providers.claude]
description = "Claude Code CLI"
command = "claude --print \"{system}\""
prompt = """OUTPUT ONLY THE COMMIT MESSAGE. NO EXPLANATIONS.

Format: type(scope): summary

- bullet points for details

Types: feat, fix, docs, refactor, chore
Start DIRECTLY with type."""

• {system} - replaced with the prompt
• prompt - custom prompt per provider (optional)
• Git diff is piped to stdin

Custom OpenAI-Compatible & Local LLM (Ollama) Setup

You can configure Git-Sensei to use local models running via Ollama or custom OpenAI-compatible endpoints (like DeepSeek, Groq, OpenRouter) natively or via CLI.

Add the following to your ~/.sensei.toml:

Option A: Local Ollama via Native HTTP API (Recommended)

This uses Ollama's built-in OpenAI-compatible endpoint. No API key is required.

[providers.ollama_api]
description = "Local Llama 3 via Ollama API"
api_url = "http://localhost:11434/v1/chat/completions"
model = "llama3"

Option B: Local Ollama via CLI Command

This pipes the diff directly into the ollama command line tool.

[providers.ollama_cli]
description = "Local Llama 3 via CLI"
command = "ollama run llama3 \"{system}\""

Option C: Custom OpenAI-Compatible API (e.g. DeepSeek)

You can point to any external API and map its API key to a custom environment variable.

[providers.deepseek]
description = "DeepSeek Coder API"
api_url = "https://api.deepseek.com/v1/chat/completions"
api_key_env = "DEEPSEEK_API_KEY"
model = "deepseek-coder"

Tuning Prompts

Use dry run to test your prompt without committing:

sensei commit -d          # Preview generated message
# Edit .sensei.toml prompt if needed
sensei commit -d          # Test again
sensei commit             # Commit when satisfied

Each AI model may need different prompting style. Adjust per provider in config.

Interactive Workflow

After generating a message, you'll see:

Context: Type: feat; Closes issue #42
--------------------------------------------------
feat(auth): add user login endpoint

Implement JWT-based authentication with secure token handling.

- Add login endpoint with email/password validation
- Implement JWT token generation and verification
- Add middleware for protected routes

Closes #42
--------------------------------------------------
Action? [y]es, [n]o, [e]dit, [r]etry

• y - Commit with this message
• n - Abort
• e - Edit in external editor (VS Code, PyCharm, etc.)
• r - Regenerate with AI

Smart Context Detection

Sensei automatically detects context from your branch name:

This context is passed to the AI for better commit messages.

Editor Integration

When you press [e]dit, Sensei opens the commit message in your configured editor.

Setup your editor (one-time):

# VS Code
git config --global core.editor "code --wait"

# PyCharm
git config --global core.editor "pycharm --wait"

# Cursor
git config --global core.editor "cursor --wait"

# Vim
git config --global core.editor "vim"

Sensei uses this priority to find your editor:

1. $VISUAL environment variable
2. $EDITOR environment variable
3. git config core.editor
4. Platform default (notepad on Windows, nano on Linux/Mac)

CLI Commands & Diagnostics

Sensei provides several diagnostic and helper commands to ensure quality and track your AI usage.

$ sensei stats
Git-Sensei Statistics
──────────────────────
Commits generated:  42
Acceptance rate:    88% (37 accepted, 5 rejected)
Provider usage:     gemini-api (76%), openai (24%)
Most common type:   feat (52%), fix (30%), refactor (10%)
Average msg length: 145 chars

$ sensei log -n 5
* 79c5291 chore: remove PROJECT.md tracking and add to ignore  ✓
* fef09a0 chore: ignore .agents directory in gitignore  ✓
* f5838f7 feat(custom-api): implement custom API support and secret redaction  ✓
* bf4f1ef feat(split): implement atomic diff splitting  ✓
* 3a104f2 docs: update documentation with invalid markdown `formatting`  ✗

$ sensei lint "feat(auth): add google sign-in option"
✓ Commit message is valid.

$ sensei lint "feat: update `README` file with markdown"
✗ Commit message validation failed:
  - First line contains disallowed markdown formatting (backticks, bold, italic).

Advanced Workflow Tools

Git-Sensei provides advanced tools that leverage AI to automate tedious git tasks:

Auto-Squashing (sensei squash)

Uses AI to analyze your recent commits and automatically generates an interactive rebase plan (git rebase -i), picking the most important commits and squashing/fixupping the rest.

sensei squash --base main

Pull Request Generation (sensei pr)

Reads the diff and commit history of your branch, generates a professional markdown Pull Request description (including Title, Motivation, What changed, and Testing Instructions), and automatically creates the PR using the GitHub CLI (gh).

sensei pr --base main

Extended Smart Context (GitHub Issues)

If your branch name contains an issue ID (e.g., feature/123-login), Git-Sensei will use the GitHub CLI (gh issue view 123) to fetch the actual issue title and description, passing it to the AI as context for even better commit messages!

Project Structure

git_sensei/
├── main.py             # CLI entrypoint
├── config.py           # Configuration loader
├── constants.py        # Shared configuration and mappings
├── providers.py        # AI provider adapters
├── secrets_shield.py   # Security regex scanning
├── git_utils.py        # Git subprocess interactions
├── core/               # Core business logic
│   ├── editor.py       # External IDE editor integrations
│   ├── fallback.py     # Offline heuristic commit generator
│   └── stats.py        # Usage telemetry tracking
├── .sensei.toml        # Default configuration
├── tests/              # Unit tests
└── docs/               # Documentation

Changelog

License

MIT