axm-git 0.5.1

Git workflow automation for AXM agents

axm-git — Deterministic Git workflows for AI agents

---

Features

• 🔍 Preflight — Structured working tree status with diff summary
• 🌿 Branch — Create or checkout branches with one call
• 📦 Commit — Batched atomic commits with auto-retry on commit-hook fixes and optional author identity injection
• 🏷️ Tag — One-shot semver tagging from Conventional Commits
• 🚀 Push — Push with dirty-check, auto-upstream detection, and force support
• 🌲 Worktree — Add, remove, or list git worktrees
• 🔀 PR — Create GitHub pull requests with optional auto-merge
• 🧭 Error Recovery — When called on a non-git directory, tools suggest nearby git repos
• 🪝 Hooks — Lifecycle hook actions (preflight, create-branch, branch-delete, commit-phase, merge-squash, worktree-add, worktree-remove, push, create-pr, await-merge, pull-main) with enabled guard, auto-discovered via entry-points
• 🪪 Identity — Resolve git author from git-profiles.toml with schedule-based or explicit profile selection. Schedule rules apply only under user-configured workspace_paths; comparison is timezone-aware via the optional timezone field (default Europe/Paris)
• 🔎 Phase Lookup — get_phase_commit() retrieves commit hashes for protocol phases

Installation

uv add axm-git

Quick Start

# Check what changed
git_preflight(path="/path/to/repo")
# → {files: [{path: "foo.py", status: "M"}, ...], clean: false, text: "git_preflight | 1 files · dirty\n..."}

# Create or switch branch
git_branch(name="feat/new-feature", path="/path/to/repo")
# → {branch: "feat/new-feature"}

# Commit in batches
git_commit(path="/path/to/repo", commits=[
    {"files": ["src/foo.py"], "message": "feat: add foo"},
    {"files": ["tests/test_foo.py"], "message": "test: add foo tests"},
])
# → {results: [{sha: "abc1234", precommit_passed: true}, ...]}

# Tag a release
git_tag(path="/path/to/repo")
# → {tag: "v0.2.0", bump: "minor", pushed: true}

# Push to remote
git_push(path="/path/to/repo")
# → {branch: "main", remote: "origin", pushed: true}

MCP Tools

git_preflight

Report working tree changes so the agent can plan commits.

Parameter	Default	Description
path	.	Project root directory
diff_lines	200	Max diff lines to include (0 to disable)

Returns: file list with status (M, A, D, ??), diff stat, clean flag, and a compact text summary for agent display.

git_branch

Create or checkout a git branch.

Parameter	Default	Description
name	required	Branch name
from_ref	None	Ref to branch from (tag, commit, branch)
checkout_only	False	If True, checkout existing branch without creating
delete	False	If True, delete the branch (git branch -D) instead of creating/checking out
path	.	Project root directory

Returns: {branch: "<current branch>"} on success.

git_commit

Execute one or more atomic commits with commit-hook handling.

Parameter	Default	Description
path	.	Project root directory
commits	required	List of commit specs (see below)
profile	None	Identity profile name — overrides schedule-based resolution from git-profiles.toml
strict	False	When True, a non-Conventional-Commit message is a hard failure instead of a warning

Each commit spec:

Field	Required	Description
files	✅	Files to stage
message	✅	Commit summary (Conventional Commits)
body		Extended commit body

When a commit hook auto-fixes files (e.g. ruff --fix), the tool re-stages and retries once automatically.

Identity is resolved once per call (not per commit). When resolved, each commit includes --author="Name <email>". The result includes an author key ({name, email} or null).

git_tag

Compute the next semver version from Conventional Commits, create and push the tag.

Parameter	Default	Description
path	.	Project root directory
version	auto	Override the computed version (e.g. "v1.0.0")

Pipeline: clean tree check → CI status check → semver bump → annotate tag → hatch-vcs verify → push.

git_push

Push the current branch to a remote after verifying a clean working tree.

Parameter	Default	Description
path	.	Project root directory
remote	origin	Remote name
set_upstream	True	Auto-set upstream for new branches
force	False	Force-push using --force-with-lease (safe: only overwrites if the remote has not advanced past our tracking ref)
force_unconditional	False	When True (and force set), use a bare --force instead — unconditional overwrite (data-loss risk)

Pipeline: repo check → dirty check → detect branch → detect upstream → push.

git_worktree

Add, remove, or list git worktrees.

Parameter	Default	Description
path	.	Project root directory
action	required	add, remove, or list
worktree_path	None	Path for the new or existing worktree
branch	None	Branch name for add
base	None	Base ref for add (defaults to repo default)
force	False	Force removal for the remove action

git_pr

Create a GitHub pull request with optional auto-merge.

Parameter	Default	Description
path	.	Project root directory
title	required	Pull request title
body	None	Pull request description
base	None	Base branch (defaults to repo default)
auto_merge	False	Enable auto-merge when checks pass

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm-git --directory packages/axm-git pytest -x -q

📖 Full documentation

License

Apache-2.0 — © 2026 axm-protocols