axm-git 0.6.0

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
• 🔐 GitHub authentication declaration — Publishes the gh auth status probe and gh auth login recovery command through the axm.credentials registry, with distinct logged_in, logged_out, and not_installed states
• 🧭 Error Recovery — When called on a non-git directory, tools suggest nearby git repos
• 🪪 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). The whole schedule can be switched off with schedule.enabled = false (defaults to true), in which case resolution falls through to the default identity
• 🔎 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.

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.

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

git_commit

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

Each commit spec:

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.

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.

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

git_worktree

Add, remove, or list git worktrees.

git_pr

Create a GitHub pull request with optional auto-merge.

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