Skip to content

AXM Logo

axm-git

Deterministic Git workflows for AI agents.

CI axm-audit axm-init Coverage PyPI Python 3.12+

What it does

axm-git provides deterministic, structured Git operations designed for AI agents. Instead of parsing raw git CLI output, agents get typed JSON responses with clear success/failure semantics and automatic retry on pre-commit hook fixes.

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 pre-commit fixes
  • 🏷️ 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
  • 🪝 Hooks — Lifecycle hook actions (preflight, create-branch, commit-phase, merge-squash, worktree-add, worktree-remove) auto-discovered via entry-points

Installation

uv add axm-git

Quick Start

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

# 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"},
])

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

Learn More