Git Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Git Integration system within Autohand provides an autonomous agent with the capability to interact with version control systems directly. It serves as a foundational layer for project awareness, safety enforcement, and automated workflows such as environment hygiene checks and auto-committing of changes. By wrapping standard Git commands into agent-accessible tools, the system allows the AI to perform complex repository management tasks ranging from simple status checks to advanced multi-worktree parallel execution.
This integration is governed by a strict safety configuration that prevents destructive operations on protected branches (e.g., main, master) and enforces commit limits to prevent accidental mass pushes. It also provides "Single Source of Truth" validation, ensuring the agent inspects the actual state of the repository before suggesting or implementing changes.
Sources: src/core/agent.ts:1083-1100, src/actions/git.ts:12-16, src/core/actionExecutor.ts:401-410
Core Architecture and Data Flow
The architecture consists of three main layers: the low-level command wrappers in src/actions/git.ts, the ActionExecutor which handles the logic and user confirmations for these actions, and the AutohandAgent which orchestrates Git tasks as part of its ReAct loop.
This diagram shows the flow of a Git request from the agent through the safety layer to the Git CLI.
Sources: src/core/actionExecutor.ts:105-110, src/actions/git.ts:180-184, src/core/agent.ts:140-160
Git Action Wrappers
The system implements a wide array of Git operations using node:child_process.spawnSync to interact with the system's Git binary. These are categorized into standard operations (commit, add, reset), branch management, stash operations, and remote synchronization.
| Category | Key Functions | Description |
|---|---|---|
| Status/Diff | gitStatus, gitDiffRange, diffFile | Retrieves repository state and changes. |
| State Mod | gitAdd, gitCommit, gitReset | Stages, commits, or reverts changes. |
| Sync | gitFetch, gitPull, gitPush | Interacts with remote repositories. |
| Advanced | gitStash, gitCherryPick, gitRebase | Handles complex history and temporary storage. |
Sources: src/actions/git.ts:55-150, src/actions/git.ts:325-360
Safety Mechanisms and Protections
Safety is a critical component of the Git integration to prevent the autonomous agent from corrupting repository history or losing work. The GIT_SAFETY configuration defines constants that are checked before any potentially dangerous operation is executed.
Protected Branches
Operations such as git push --force, git rebase, and git reset --hard are strictly blocked on branches designated as protected: main, master, develop, production, and staging.
The safety flow for push operations, highlighting the transition to --force-with-lease for safer updates.
Sources: src/actions/git.ts:12-18, tests/security/gitSafety.spec.ts:38-50, src/actions/git.ts:600-615
Commit and Push Limits
To prevent accidental bulk data loss or large-scale repository changes, the system limits the number of commits allowed in a single push operation to 50.
Sources: src/actions/git.ts:15, src/actions/git.ts:606-613
Automated Workflows
Environment Hygiene
The agent performs "Phase 1: Environment Hygiene" before starting implementation tasks. This involves running git_status to ensure there are no uncommitted changes or conflicts that might interfere with the new task.
Sources: src/core/agent.ts:1100-1110
Auto-Commit System
The Auto-Commit system allows the agent to generate conventional commit messages based on repository changes. It analyzes added, modified, deleted, and renamed files to suggest a prefix (feat, fix, docs, etc.).
The sequence of events during an auto-commit workflow.
Sources: src/actions/git.ts:460-490, tests/gitAutoCommit.spec.ts:80-100, src/core/agent.ts:250-280
Worktree Management
For parallel development, Autohand includes a WorktreeManager class. This allows the agent to create isolated environments for different tasks (e.g., feature development, PR reviews, or hotfixes) using Git worktrees.
Worktree Templates
Worktrees can be initialized using pre-defined templates that include specific setup commands like npm install.
| Template | Purpose | Path Pattern |
|---|---|---|
| feature | Feature development | ../{repo}-feature-{branch} |
| hotfix | Emergency fixes | ../{repo}-hotfix-{branch} |
| review | PR code reviews | ../{repo}-review-{branch} |
| experiment | Detached experiments | ../{repo}-experiment-{timestamp} |
Sources: src/actions/worktree.ts:70-100
Advanced Operations
The WorktreeManager supports high-level orchestration, such as running a command (e.g., tests) in parallel across all active worktrees and syncing changes from the main branch to all feature worktrees.
// Example of parallel command execution across worktrees
async runParallel(command: string, options: ParallelOptions): Promise<ParallelResult[]> {
const worktrees = this.list().filter(wt => !wt.bare);
// ... execution logic using maxConcurrent and timeout
}
Sources: src/actions/worktree.ts:260-300, src/core/actionExecutor.ts:470-495
Conclusion
Git Integration in Autohand transforms Git from a manual tool into an automated, safe, and context-aware system for an AI agent. By combining robust command wrapping with strict safety protocols and advanced features like worktree management and auto-committing, the project ensures that the agent can effectively manage code state while minimizing the risk of destructive actions.