axm-git — Deterministic Git workflows for AI agents
Git workflow automation for AXM agents: inspect changes, stage explicit files, commit, manage branches and worktrees, and publish through Git and GitHub.
Features
- Inspect repository status, diffs and package release history.
- Commit explicit file batches with identity resolution and partial-result reporting.
- Manage branches, worktrees, clones and local merges.
- Push changes, create pull requests, publish tags and observe GitHub merge status.
Installation
Python 3.12+ and Git are required. GitHub operations also need the gh CLI
and an authenticated session. In a Python project managed by uv:
uv add axm-git
Quick Start
From an existing Git repository, use the installed project environment:
uv run axm git_preflight --path . --diff-lines 0
This command reads the current repository and reports changed files and a diff summary without patch content. A package subdirectory limits preflight's status and diff scope; use the repository root for a repository-wide check. It does not stage, commit or publish anything.
Usage
CLI and MCP
The axm CLI and MCP use the same tools registered under axm.tools.
There is no separate axm-git executable. See the
CLI and MCP guide and
complete tool contracts.
| Operation | Tools | Effects |
|---|---|---|
| Inspect locally | git_preflight, git_release_diff, git_worktree(action="list") |
Read repository state |
| Change locally | git_branch, git_commit, git_merge, worktree add/remove |
Change branches, index, files or commits |
| Obtain remote content | git_clone, git_pull |
Read remote; write local checkout |
| Publish | git_push, git_pr, git_tag |
Change remote state |
| Observe GitHub | git_await_merge |
Poll a PR; does not merge it |
Commit and release boundaries
git_commit processes a batch sequentially: earlier successful commits remain
if a later item fails. It stages declared paths, refuses unrelated staged
paths, and retries once on the commit-hook “files were modified” marker.
Commit recovery explains partial results and hook
observations.
git_tag creates an annotated local tag and pushes it to origin. It has
no list, preview, dry-run or local-only mode. Use git_release_diff for
read-only release analysis. The tag CI guard blocks only red, not
pending, error or skipped.
Release guide describes the current limitations.
Documentation
The site homepage is docs/index.md; this README is the repository entry point. Generated API documentation includes internal modules; generation does not make every Python symbol a public root export.
Development
Development takes place in the axm-forge workspace.
git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-packages --all-groups
uv run --package axm-git --directory packages/axm-git pytest
Tests live in tests_axm_git/. From packages/axm-git, build the package
documentation with mkdocs build --strict in an environment containing its
docs dependencies.
License
Licensed under Apache-2.0. See LICENSE.
1 maintainer
Release files for axm-git 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| axm_git-0.7.0.tar.gz | 134.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| axm_git-0.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 204.4 kB
Release files / axm_git-0.7.0.tar.gz
| Download URL | axm_git-0.7.0.tar.gz |
|---|---|
| Size | 134.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5354302fe0ed94412e33618e1cf874cb8c394b15c3dc4a1a88e8c64b9b7403da
|
|
BLAKE2b-256 checksum How to use checksums |
b5e8a225d24983958dd47796c48bfca029d2cd73541fdc9f420ec31fe1511837
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / axm_git-0.7.0-py3-none-any.whl
| Download URL | axm_git-0.7.0-py3-none-any.whl |
|---|---|
| Size | 69.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f3b16516d4eefc34b60daa641fc7bcb1e2fab0adbf3000f1841fda6bc5c7ff8c
|
|
BLAKE2b-256 checksum How to use checksums |
51ae0db7842a5f93df307ae37ed445e866ef8174e1fc8d060a89a5c9f2c27b40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
