stagepen 0.1.0

Write a clean conventional-commit message from your staged diff — an AI git commit helper you run as a hook or CLI.

stagepen

Writes a clean conventional-commit message from your staged diff. Run it as a CLI or wire it into a git hook so you never stare at a blank commit prompt again.

I write a lot of commits, and I noticed I either dashed off a lazy "fix stuff" message or wasted a minute crafting the perfect conventional-commit line. Pasting every diff into a chat window each time isn't it either. So I built stagepen: it reads what you've staged and proposes a proper message, right there in the terminal.

$ git add .
$ stagepen

✍  Proposed commit message:

  feat(auth): add refresh-token rotation

  - rotate the refresh token on every use
  - revoke the prior token family when reuse is detected

The point isn't "ask an AI to write a commit." It's that this lives in your flow — one command, or a hook that fires on every commit — so you don't context-switch at all.

Why it's a tool and not just ChatGPT

Because you'd never paste every diff into a chat window. The value is that it runs where you already are:

• one command in the repo, no copy-paste
• can auto-create the commit (-c)
• works offline with --provider mock or a local model, so nothing has to leave your machine
• reads only your staged diff, and redacts secrets before sending anything

Install

git clone https://github.com/jay-tank/stagepen.git
cd stagepen
pip install .
# for the Claude / OpenAI providers:
pip install '.[claude]'   # or '.[openai]'

Using it

# stage something, then:
stagepen                     # prints the proposed message
stagepen -c                  # prints it, asks, then commits
stagepen -c -y               # commit without the confirmation prompt
stagepen --provider mock     # offline demo, no key
stagepen --provider ollama   # local model, no key

If you like it, drop it in a git hook so it runs on its own — see docs/USAGE.md.

Providers

Defaults to Claude, but it's provider-agnostic: claude, openai, ollama (local, no key), or mock (offline). Details in docs/PROVIDERS.md.

A note on your secrets

Diffs sometimes contain a stray key or password. stagepen redacts common secret patterns before the diff is ever sent to a model, and it only ever reads your staged changes.

Limitations

• It writes the message from the diff, so a huge diff gets truncated to keep the prompt sane. For sprawling commits the message is a strong starting point, not gospel.
• Quality tracks the diff quality: tiny, focused commits get the best messages (which is how you should be committing anyway).

License

MIT — see LICENSE.