auto-git: A Git Workflow Automation Tool Designed for AI Agents

auto-git is a Codex skill suite designed specifically for AI agents to interact with Git repositories, aiming to solve challenges in version control for AI-generated code (e.g., unclear change intent, messy commit messages). Core features include intent-based commits, secure staging management, multi-worktree coordination, PR handover, and history rewriting.

Original Author/Maintainer: async, Source Platform: GitHub, Release Time: 2026-06-14, Project Link: https://github.com/async/auto-git

With the rise of AI coding assistants and agents, developers rely on AI to assist with code writing, but AI-generated code changes face version control challenges: unclear change intent, messy commit messages, difficulty splitting large modifications, and multi-branch coordination issues. Traditional Git workflows are not optimized for AI collaboration scenarios.

auto-git emerged as a solution—it is not a simple Git wrapper but a complete skill suite that enables AI agents to understand code change intent in a structured way and generate clear, traceable Git history.

auto-git includes three main skill modules:

1. auto-git (Core Skill)：Supports local review mode (single-session scenario, intent-based commits) and coordinated branch mode (multi-session/collaboration scenario, using isolated branches and worktrees, maintaining metadata via ledger.json).

2. git-intent-audit (Intent Audit)：A read-only tool that analyzes dirty worktree issues (e.g., unclear intent, oversized commits, mixed commits) and provides evidence for history rewriting.

3. git-history-rewrite (History Rewrite)：Replays local history based on audit evidence, preserves original author information, and does not force push by default.

auto-git is designed with an 'intent-driven' core philosophy and defines a complete commit type system:

Type Prefix	Description
feat:	New feature or capability
fix:	Fix error behavior
security:	Security vulnerability fix or reinforcement
perf:	Performance optimization
refactor:	Internal refactoring without behavior change
test:	Only test code changes
docs:	Only documentation changes
style:	Only format changes
deps:	Only dependency updates
build:	Build/packaging system changes
ci:	CI workflow changes
migrate:	Database/schema/data migration
release:	Version/changelog/release metadata
revert:	Revert previous commit
chore:	Maintenance work not belonging to above categories

The specification requires prioritizing the most specific intent prefix, using chore: only when unclassifiable, making Git history self-explanatory and easy to review and analyze.

auto-git has built-in multi-layer security protection:

Safety Gates: In fully automatic mode, pauses for user confirmation in the following cases: detection of sensitive information, destructive cleanup operations, validation failure, forced push, remote tag movement, missing release metadata.

Large Diff Splitting: Intelligently analyzes change relevance, splits large unstaged changes into multiple logically independent commits to avoid giant commits.

Unrelated Edit Protection: Automatically detects and prevents unrelated changes from being accidentally packed into the same commit.

Coordinated branch mode enables complex multi-workflow management:

1. Lease Management: Each work branch corresponds to a lease record to prevent simultaneous modification of the same branch by multiple sessions.
2. Ledger Tracking: ledger.json records all active and completed work states.
3. PR Handover: Completed branches can be safely pushed to remote and create PRs; the ledger records the handover status.
4. Trunk Protection: Does not automatically merge PRs by default; merging is bound to an explicit land intent.
5. Cleanup Guarantee: Automatically switches back to the trunk branch after work is completed to keep the environment clean.

Application Scenarios:

• AI-assisted programming: Helps AI tools like Codex and Cursor understand change intent and generate standardized commit history.
• Large refactoring projects: Phased, module-based commits using intent classification and diff splitting capabilities.
• Multi-feature parallel development: Isolates different workflows to avoid interference.
• Code review optimization: Optimizes commit history before PR to help reviewers understand logic.

Codex Integration:

• Skill definitions are located in the skills/auto-git/ directory.
• Generate installable gist packages via pnpm run gists:package.
• Provides the auto-git CLI tool, supporting operations like snapshot, gate check, and release pre-check.

auto-git represents an important direction for AI-assisted development tools: enabling AI to participate in the full software development process in a collaborative, reviewable, and traceable way.

Core Contributions:

1. Structured Intent: Converts vague requirements into clear change types and scopes.
2. Safety Boundaries: Balances automation and manual review.
3. History Maintainability: Generates human-friendly Git history for long-term maintenance.

For teams exploring AI-assisted development, auto-git provides a valuable practice paradigm.