# pr-commit-ai-agent

> A Bun-friendly CLI that reads the real git diff before drafting the commit, branch, or PR text.

`pr-commit-ai-agent` is a CLI for the part of shipping that people rush when they are tired: reading the diff, naming the change, writing the commit, and drafting a pull request that says what actually happened.

## Why it exists

Commit and PR text is not paperwork. It is the audit trail the next engineer reads during an incident, review, or follow-up fix. The tool keeps that work close to git instead of turning it into a chat exercise detached from the patch.

The important boundary is that the diff remains the source of truth. The agent can help with language, but it has to read the actual change, respect what is staged, and produce something a human can reject quickly. I do not want a poetic PR description. I want a useful one: what changed, why it matters, and exactly how it was verified.

```mermaid
flowchart LR
  A[git diff] --> B[classify change]
  B --> C[draft commit]
  B --> D[draft PR body]
  C --> E[human accepts or edits]
  D --> E
```

<Decision title="The diff is the source of truth">
  The model can improve the words, but it does not get to invent scope. The commit and PR text must
  be explained by the patch in front of it.
</Decision>

## The useful boundary

- Read the staged and unstaged diff before writing anything.
- Keep the human in control of the final commit and PR.
- Prefer boring conventional commits over clever summaries.
- Support local or remote model providers without changing the workflow.
- Use GitHub CLI as the integration boundary instead of hiding auth and repository state inside the
  model layer.
- Let local models handle privacy-sensitive repos when the workflow allows it.

## Where it can help without taking over

The best use case is a tired engineer at the end of a real change. The diff exists. The verification
exists. The missing piece is clear language: branch name, commit message, PR title, body, and a
checklist that matches what actually ran.

That is a narrow enough job for an agent. It can classify the patch, suggest the phrasing, and remind
the author to include verification. It should not decide that unrelated files are part of the story,
invent tests, or turn a risky change into confident prose.

## The engineering habit

AI tooling is best when it shortens a real feedback loop without stealing ownership. This is a good place for it: the input is bounded, the output is reviewable, and the quality bar is practical.

The same rule applies to larger agent workflows. Give the agent scoped access, force it to inspect the artifact that matters, require verification, and keep the human decision close to the code. That is how AI becomes part of shipping instead of a parallel chat transcript nobody trusts.