commitcraft：从 git diff 生成 conventional commit 消息的 AI CLI

An AI-powered CLI that drafts conventional commit messages from your staged git diff. Stage your changes, run commitcraft, get a clean feat(scope): ... message — optionally commit with it.

No runtime dependencies — the LLM calls are plain urllib over HTTPS.

Install

Requires Python 3.10+.

git clone https://github.com/GuillermoBarreto/commitcraft
cd commitcraft
pip install -e .

For development (runs the test suite):

pip install -e ".[dev]"
pytest

Usage

Stage some changes, then:

commitcraft

Example output:

fix(parser): guard against empty input lines

The tokenizer crashed on trailing newlines because it assumed every
line had at least one character. Skip blank lines before tokenizing.

Commit with the suggested message after a confirmation prompt:

commitcraft --apply

Skip the confirmation prompt for non-interactive use:

commitcraft --apply --yes

Show recently generated messages (newest first):

commitcraft --history
commitcraft --history --history-limit 10

Print the installed version:

commitcraft --version

Choose the backend and model:

commitcraft --backend ollama --model codellama
commitcraft --backend openai --model gpt-4o-mini
commitcraft --backend local            # no network or API key: interactive type picker

Configuration

commitcraft reads everything from environment variables. Never commit secrets — set them in your shell profile instead.

Variable	Backend	Description
`OPENAI_API_KEY`	openai	Required for the default backend.
`OPENAI_BASE_URL`	openai	Optional. Any OpenAI-compatible chat API (default: `https://api.openai.com/v1`).
`OLLAMA_BASE_URL`	ollama	Optional (default: `http://localhost:11434`).

export OPENAI_API_KEY="..."            # keep this out of your shell history / repos
commitcraft --backend ollama           # or run fully local with Ollama

How it works

gitutil reads git diff --cached and truncates it to a sane size.
prompts wraps the diff with a system prompt that teaches conventional commits.
backends sends the request — OpenAI-compatible chat API or local Ollama.
cli prints the suggestion, or commits it with --apply.

Roadmap

Message history / regeneration (--retry) — done
Emoji conventional commits (--emoji) — done
Commitizen-style interactive type picker fallback when offline — done (--backend local)