Metadata-Version: 2.4
Name: stagepen
Version: 0.1.0
Summary: Write a clean conventional-commit message from your staged diff — an AI git commit helper you run as a hook or CLI.
Author-email: Jay Tank <tankjai24@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jay-tank/stagepen
Project-URL: Repository, https://github.com/jay-tank/stagepen
Project-URL: Issues, https://github.com/jay-tank/stagepen/issues
Keywords: git,commit,conventional-commits,ai,llm,cli,developer-tools,git-hook
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Provides-Extra: claude
Requires-Dist: anthropic>=0.40; extra == "claude"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 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.

[![CI](https://github.com/jay-tank/stagepen/actions/workflows/ci.yml/badge.svg)](https://github.com/jay-tank/stagepen/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

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.

```text
$ 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

```bash
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

```bash
# 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](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](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](LICENSE).
