Conventional Commits Plugin¶

The conventional_commits plugin provides the commit tool. It reads staged git changes, uses an LLM to generate a Conventional Commits-formatted message, and presents an interactive approval loop before running git commit.

Quick start¶

Ensure your settings declare an LLM and point the tool at it:

# ~/.config/aifred-tk/settings.yml
llms:
  my-llm:
    provider: openai
    model: gpt-4o-mini

tools:
  commit:
    llm:
      type: ref
      ref: my-llm

Stage your changes and run the tool:

git add -p
aifred-tk commit

Configuration¶

LLM setting¶

The tools.commit.llm key is required. It accepts a reference to a named LLM or an inline definition. See LLMs for the full format.

# Reference a named LLM
tools:
  commit:
    llm:
      type: ref
      ref: my-llm

# Or define inline
tools:
  commit:
    llm:
      type: custom
      provider: ollama
      model: gemma4:e4b
      host: 127.0.0.1
      port: 11434

Enabling and disabling¶

The tool respects the standard enabled flag:

tools:
  commit:
    enabled: false

Usage¶

CLI¶

aifred-tk commit [--repo-path PATH]

Option	Description
`--repo-path PATH`	Absolute path to the git repository root. Defaults to the current working directory.

MCP¶

The tool is registered automatically when the MCP server starts. Invoke it as aifred_commit with an optional repo_path argument.

The approval loop¶

After the LLM generates a message, the tool enters an interactive loop. Three actions are available:

Action	Behaviour
Approve	Runs `git commit -m <message>` and exits.
Regenerate	Sends a generic retry prompt in the same conversation thread and generates a new message.
Free-text input	Forwards your text as the next user message — use this to give specific guidance such as `"add the api scope"` or `"make the subject shorter"`.

The conversation history accumulates across iterations. Each refinement attempt has the full context of the prior exchange, so targeted feedback compounds across rounds.

Output¶

execute() always returns a JSON-serializable dict with a status key.

Committed:

{
  "status": "committed",
  "commit_message": "feat(api): add pagination support",
  "stdout": "[main abc1234] feat(api): add pagination support"
}

Cancelled (user dismissed the elicitation):

{"status": "cancelled"}

Error:

{
  "status": "error",
  "message": "No staged changes found. Stage files with 'git add' before running this tool."
}

{
  "status": "error",
  "message": "git commit failed",
  "returncode": 1,
  "stderr": "nothing to commit, working tree clean"
}

Commit message format¶

The LLM is prompted with the full Conventional Commits specification. Generated messages follow this structure:

TYPE[(SCOPE)][!]: SHORT_MESSAGE

[BODY]

[FOOTER]

Type	Meaning
`feat`	New feature — triggers MINOR version bump
`fix`	Bug fix — triggers PATCH version bump
`docs`	Documentation changes only
`style`	Formatting, whitespace, no logic change
`refactor`	Code change that is neither a fix nor a feature
`perf`	Performance improvement
`test`	Adding or correcting tests
`build`	Build system or dependency changes
`ci`	CI configuration changes
`chore`	Maintenance tasks, tooling, dependency updates

Breaking changes are marked with ! after the type/scope and a BREAKING-CHANGE: footer.