# AI Commit Helper

A small Codex plugin that reads your staged changes and suggests three commit messages using your project's preferred format.

I built this to practise TypeScript and learn how MCP servers and Codex skills work together.

```text
$ai-commit-helper:commit-msg
```

It supports messages like `feat: add password reset` and `#234 Add password reset`. Each suggestion is checked against your repository's format and length limit before you see it.

## Installation

You'll need Git, Node.js, npm, and Codex CLI with plugin support. I used Node.js `26.6.0` and npm `11.18.0` during development.

Clone this repository and run these commands from its root:

```bash
npm ci
npm run build
npm link
codex plugin marketplace add .
codex plugin add ai-commit-helper@commit-helper-dev
```

To check the installation:

```bash
codex plugin list --marketplace commit-helper-dev
```

This installs from your local checkout. Keep that folder around, since `npm link` points to the built server inside it.

On macOS or Linux, if you get a permission error when starting the server, run:

```bash
chmod u+x build/mcp.js
```

## Using it

Stage the changes you want to describe, then open Codex in that repository:

```bash
git add README.md
codex
```

In Codex, run:

```text
$ai-commit-helper:commit-msg
```

On first use, it asks whether you want to save your commit rules or use the defaults. Once you've saved them, it reuses them on later runs.

For ticket messages, provide the ticket number in your request or answer when asked:

```text
$ai-commit-helper:commit-msg Use ticket 234.
```

For example, a staged password-reset feature might get these suggestions:

```text
1. #234 Add password reset flow
2. #234 Support resetting forgotten passwords
3. #234 Implement password recovery
```

Pick a message and commit it yourself. The plugin doesn't stage files, make commits, or push. If nothing is staged, it tells you and stops.

## Commit rules

Rules live in `.commit-helper.json` at the root of the repository you're working on. You can set them up through Codex:

```text
$ai-commit-helper:setup-commit-helper
```

Setup asks for the format and maximum length, then creates the file. You can run it even when nothing is staged. It won't overwrite an existing configuration; edit the file yourself if you want to change it later.

You can also create the file manually:

```json
{
  "format": "ticket",
  "maxSubjectLength": 100
}
```

There are two formats for now:

| Format | Example |
| --- | --- |
| `typed` | `feat: add password reset` or `fix(auth): handle expired tokens` |
| `ticket` | `#234 Add password reset` |

Messages must fit on one line. The length limit includes the prefix and spaces. Typed messages use a lowercase type with an optional scope; the validator currently doesn't support the breaking-change `!` marker.

Without a configuration file, the defaults are `typed` and `72`. If you choose defaults without saving them, you'll be asked again on a later run. Save them through setup to skip that question.

Both fields are required in a configuration file. Invalid JSON, unsupported formats, extra fields, and non-positive or non-integer length limits return an error. You can commit this file to share the same rules with your team.

## How it works

The MCP server handles Git commands, configuration, and validation. The skills tell Codex when to call those tools and how to produce the suggestions. Codex generates the text, so there's no separate AI API key to configure for this server.

The server exposes three tools:

| Tool | What it does |
| --- | --- |
| `get_commit_context` | Returns the staged diff, effective rules, and whether those rules came from a file or the defaults. |
| `validate_commit_message` | Checks a message and returns any validation errors. |
| `create_commit_rules` | Creates `.commit-helper.json` without replacing an existing file. |

The staged diff is sent to Codex as tool output. Unstaged changes aren't included. Validation checks format and length, so you should still review whether a suggestion accurately describes your changes.

## Development

Build the TypeScript and run the validation tests:

```bash
npm run build
node --test tests/validate.test.mjs
```

The tests use Node's built-in test runner and import from `build`, so rebuild after changing TypeScript.

To try the MCP tools directly:

```bash
npx @modelcontextprotocol/inspector ai-commit-helper-mcp
```

Use an absolute repository path in Inspector. Paths to subdirectories work too; the server finds the repository root. Try configuration creation in a test repository so you can check both creating a file and refusing to overwrite it.

If you change the plugin's skills or configuration, reinstall it from the updated checkout and open a fresh Codex session:

```bash
codex plugin remove ai-commit-helper@commit-helper-dev
codex plugin add ai-commit-helper@commit-helper-dev
```

A couple of things that caught me during development:

- **The server starts but prints nothing:** that's expected when launched on its own. It communicates over stdio and needs an MCP client such as Codex or Inspector.
- **Suggestions describe old edits:** check `git diff --staged`. Saving a file doesn't update its staged version, and asking for suggestions doesn't clear the staging area.
- **Codex can't find the server:** run `npm link` again and check that `ai-commit-helper-mcp` is on the PATH available to Codex.

## License

[ISC](LICENSE)