gitspeak

AI-powered Git companion CLI. Commit messages, PR descriptions, branch names, and diff explanations — from any AI provider.

Demo

▶ gitspeak commit
─
feat(auth): add JWT refresh token rotation

- Implement token rotation endpoint
- Update session handling to use new tokens
─
Run git commit with this message? [y/N]: y
✓ Committed successfully.

Install

pip install gitspeak

(or: pip install -e . for local dev; legacy: python gitspeak.py also works)

Quick Start

export OPENAI_API_KEY=sk-...
git add -p
gitspeak commit

Commands

Command	What it does	Key Options
commit	Generate a commit message from staged changes	--apply, --style, --amend, --edit
pr	Generate a PR description from staged changes	--all, --base, --copy, --output
branch	Generate a branch name	--checkout
explain	Explain a diff	--file, --unstaged, --base
config	Manage configuration	show, set, reset, providers

Configuration

Env Var	Config Key	Default	Description
GITSPEAK_PROVIDER	provider	openai	AI Provider (openai, anthropic, gemini, ollama)
GITSPEAK_MODEL	model	(varies)	AI Model
GITSPEAK_STYLE	style	conventional	Commit style
GITSPEAK_AUTO_APPLY	auto_apply	false	Apply commits without prompt
GITSPEAK_MAX_DIFF	max_diff	14000	Max chars of diff sent
GITSPEAK_TEMPERATURE	temperature	0.15	Model temperature
GITSPEAK_API_BASE	api_base	(provider default)	Custom API base URL
GITSPEAK_TRUST_REPO	—	false	Allow repo .gitspeak.json to override api_base / provider
GITSPEAK_HOOK_ENABLED	hook_enabled	true	Run AI generation when the git hook fires
GITSPEAK_HOOK_FORCE	hook_force	false	Overwrite an existing non-gitspeak hook without prompting

Set values in ~/.gitspeak.json, repo .gitspeak.json, or env vars. Env wins over repo, repo over home.

PR diff source

By default, gitspeak pr sends only staged changes (same as commit). Use --all to include the full branch diff vs --base:

git add -p
gitspeak pr              # staged changes only
gitspeak pr --all        # full branch diff vs main
gitspeak pr --all -b develop

AI Providers

Provider	Env Var	Default Model	Notes
OpenAI	OPENAI_API_KEY	gpt-4o	Standard compatible API
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-6	Claude models
Gemini	GOOGLE_API_KEY	gemini-1.5-pro	Google generative language
Ollama	(none)	llama3	Runs locally via http://localhost:11434

Commit Styles

Style	Description	Example Output
conventional	Conventional Commits 1.0.0	feat(auth): add refresh token
angular	Angular format	feat(auth): add refresh token
emoji	Gitmoji style	✨ feat: add refresh token
semantic	semantic-release style	feat: ... \n\n# Release-As: minor

Git Hook

You can install gitspeak as a prepare-commit-msg git hook to automatically generate commit messages.

Installation

To install the hook in the current repository:

gitspeak hook install

Uninstall

To safely remove the hook:

gitspeak hook uninstall

Status

To view hook status:

gitspeak hook status

Privacy

The hook sends your staged git diff to your configured AI provider on every commit. gitspeak hook install asks you to confirm this before installing.

gitspeak scans diffs for potential secrets (API keys, tokens, passwords) before sending them. If matches are found, the hook refuses to proceed unless you bypass the scan.

Hook configuration

Disable the hook without uninstalling it:

gitspeak config set hook_enabled false
# or: export GITSPEAK_HOOK_ENABLED=false

Overwrite an existing third-party hook without a confirmation prompt:

gitspeak config set hook_force true
# or: export GITSPEAK_HOOK_FORCE=true
gitspeak hook install

Bypassing

To bypass the hook for a specific commit and write the message manually:

GITSPEAK_SKIP=1 git commit

To bypass the secret scan during a hook-triggered commit (after reviewing the diff yourself):

GITSPEAK_SKIP_SECRET_SCAN=1 git commit

To bypass the secret scan from the CLI directly:

GITSPEAK_SKIP_SECRET_SCAN=1 gitspeak commit

Plugin System

You can write and install custom plugins for gitspeak. Create a Python package named {style}_gitspeak that exposes a get_prompt() -> str function and STYLE_NAME: str. Install via pip and gitspeak will auto-discover it.

CI Integration

You can use gitspeak in GitHub Actions by exporting OPENAI_API_KEY or equivalent in your workflow.

Contributing

See CONTRIBUTING.md for details on how to set up the dev environment, run tests, and write plugins.

License

MIT