axm-git 0.5.0

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
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

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)

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