git-afm

On-device Conventional Commits, pull request descriptions, and diff explanations — powered by Apple Foundation Models.

git-afm reads your staged git diff and produces structured output locally on Apple Silicon. No API keys, no cloud inference, no token costs.

Type: feat | Scope: auth
feat(auth): implement token verification logic

- Add authenticate_user helper function
- Validate token length and admin identity

[c] commit   [e] edit   [r] regenerate   [y] copy   [q] quit

Contents

• Requirements

• Features

• Installation

• Usage

• CLI reference

• Commit types

• MCP server

• How it works

• Development

• License

Related MCP server: Git Commit MCP Server

Requirements

The Apple Foundation Models framework is only available on supported Macs with Apple Intelligence turned on. If the model is unavailable, git-afm exits with a clear error instead of falling back to a remote API.

Features

• Conventional Commits from the staged diff (feat, fix, refactor, perf, test, docs, chore, build, ci), including optional scope and breaking-change (!) markers.

• Constrained decoding via @fm.generable — the model fills a typed schema, so you get a real commit object instead of brittle JSON parsing.

• Pull request descriptions (--pr / git-afm-pr) as Markdown with summary, key changes, and a verification checklist.

• Diff explainer (--explain) in English or Portuguese, without committing.

• Interactive terminal UI (Rich): commit, edit in $EDITOR, regenerate, copy, or quit.

• macOS clipboard integration through pbcopy.

• Local MCP server (afm-mcp) so Cursor, Claude Desktop, Windsurf, and similar clients can call the same on-device tools.

Lockfiles and minified bundles are omitted from the prompt; oversized diffs are truncated so they fit the on-device context window.

Installation

Clone and install in editable mode:

git clone https://github.com/meschkemaes/git-afm.git
cd git-afm
python3 -m pip install -e .

Directly from GitHub:

python3 -m pip install "git+https://github.com/meschkemaes/git-afm.git"

Optional extras:

python3 -m pip install -e ".[mcp]"   # MCP server
python3 -m pip install -e ".[dev]"   # test suite

Git on macOS discovers executables named git-<command>, so after install both of these work:

git afm
git-afm

The package also installs git-afm-pr (shortcut for git-afm --pr) and afm-mcp.

Usage

Interactive commit

Stage the files you want in the commit, then generate a message:

git add -p
git afm

If nothing is staged but unstaged changes exist, git-afm asks whether to stage everything first.

Stage all and generate

git afm -a

Equivalent to git add -A followed by generation.

Portuguese output

git afm --pt

Commit subjects, bullet points, PR copy, and the action menu are generated in Portuguese. The Conventional Commit type (feat, fix, …) stays in English, as the spec requires.

Pull request description

git afm --pr
# or
git-afm-pr

Output is Markdown ready for GitHub or GitLab:

## Summary
…

## Key Changes
- …

## Verification & Testing
- [ ] …

Explain the diff

git afm --explain
git afm --explain --pt

Prints a short natural-language explanation and exits without committing.

Extra context

Guide the model with intent the diff does not make obvious:

git afm -m "this is a hotfix for the login timeout in production"

Non-interactive and dry-run

git afm -y                 # commit immediately
git afm --dry-run          # print only
git afm --dry-run --copy   # print and copy

CLI reference

Commit types

Breaking changes get a ! after the type (or type(scope)!) and a BREAKING CHANGE footer.

MCP server

git-afm can expose the same on-device model as a Model Context Protocol server.

python3 -m pip install -e ".[mcp]"
afm-mcp

Tools

Each tool accepts diff (required), language (en or pt, default en), and — except explain_diff — optional context.

Client configuration

Add the server to mcp.json (Cursor, Windsurf) or claude_desktop_config.json:

{
  "mcpServers": {
    "apple-foundation": {
      "command": "python3",
      "args": ["-m", "git_afm.mcp_server"]
    }
  }
}

If the afm-mcp script is on your PATH:

{
  "mcpServers": {
    "apple-foundation": {
      "command": "afm-mcp"
    }
  }
}

The Python used in command must be the same environment where git-afm (and the mcp extra) is installed.

How it works

flowchart LR
  A["git diff --cached"] --> B["Filter lockfiles<br/>and truncate"]
  B --> C["Apple Foundation Models<br/>constrained decoding"]
  C --> D["Commit · PR · Explain"]

1. The CLI reads the staged diff (git diff --cached).

2. Noise is stripped: lockfiles (package-lock.json, pnpm-lock.yaml, Cargo.lock, …), minified assets, and source maps are omitted; large file hunks are truncated.

3. Apple Foundation Models fills a @fm.generable schema (ConventionalCommit or PullRequestSummary) through constrained decoding.

4. The result is rendered in the terminal. You commit, edit, regenerate, copy, or abort.

Inference runs on the Apple Neural Engine. Diffs never leave the machine.

Privacy

There is no network client for generation. git-afm does not send diffs, commit messages, or prompts to a third-party API. Availability still depends on Apple Intelligence being enabled on the local Mac.

Development

See CONTRIBUTING.md.

python3 -m pip install -e ".[dev]"
python3 -m pytest tests/ -v -m "not integration"

test_engine.py talks to the real Foundation Models runtime and is skipped when Apple Intelligence is unavailable. GitHub Actions runs the unit tests only.

License

MIT © 2026 Lucas Meschke