git-agent-sync/.README.md

Git Agent Sync

A CLI tool that manages isolated git worktrees for AI coding agents, enabling parallel development without conflicts.

Overview

Git Agent Sync solves the problem of managing multiple AI coding agents working on the same codebase. Each agent gets its own isolated git worktree, allowing parallel development without branch conflicts.

Key Features

• Per-Agent Worktree Isolation - Each agent works in a separate git worktree
• Automatic Environment Configuration - Environment variables and dependencies are auto-configured
• Change Tracking - Track agent-specific file changes with metadata
• Unified Diff Generation - Generate diffs for code review with agent attribution
• Safe Merge Workflows - Merge changes back to main with validation checks

Installation

From Source

# Clone and install
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-agent-sync.git
cd git-agent-sync
npm install
npm run build

# Link globally
npm link

Global Installation

npm install -g git-agent-sync

Quick Start

1. Initialize in a git repository:

cd your-git-repo
git-agent-sync init

2. Create a workspace for an agent:

git-agent-sync create claude-code

3. Work in the workspace:

cd .agent-workspaces/agent-claude-code
# Make your changes
git status

4. Generate a diff for review:

git-agent-sync diff claude-code

5. Merge changes back to main:

git-agent-sync merge claude-code

6. Clean up when done:

git-agent-sync destroy claude-code

Commands

create

Create an isolated worktree for an AI agent.

git-agent-sync create <agent-name> [options]

Options:

• -p, --path <path> - Custom path for the workspace
• -t, --template <template> - Path to environment template directory
• --no-install - Skip automatic dependency installation
• --env <key=value> - Set environment variable (can be used multiple times)

Example:

git-agent-sync create claude-code --env API_KEY=abc123

list

List all active agent workspaces.

git-agent-sync list [options]

Options:

• --json - Output as JSON
• --verbose - Show detailed information

Example:

git-agent-sync list --verbose

status

Show detailed changes for a specific agent workspace.

git-agent-sync status [agent-name] [options]

Options:

• --short - Show short summary only
• --output <file> - Export to file

Example:

git-agent-sync status claude-code --short

diff

Generate unified diffs for code review.

git-agent-sync diff [agent-name] [options]

Options:

• -o, --output <file> - Export diff to file
• --short - Show short summary only
• --json - Output as JSON
• --text - Output as plain text
• --compare <branch> - Compare to a specific branch

Example:

git-agent-sync diff claude-code --output diff.md

merge

Safely merge agent changes back to main branch.

git-agent-sync merge <agent-name> [options]

Options:

• --force - Force merge even with conflicts
• --dry-run - Preview merge without making changes
• --message <msg> - Custom merge commit message

Example:

git-agent-sync merge claude-code --dry-run

destroy

Safely remove an agent workspace.

git-agent-sync destroy <agent-name> [options]

Options:

• --force - Skip confirmation and remove without preservation
• --preserve - Preserve uncommitted changes as a patch file
• --output <path> - Path for patch file

Example:

git-agent-sync destroy claude-code --preserve

Configuration

Environment Variables

Variable	Description	Default
GIT_AGENT_SYNC_PATH	Custom path for agent workspaces	./.agent-workspaces
GIT_AGENT_SYNC_CONFIG	Path to global config file	~/.git-agent-sync/config.json
GIT_AGENT_SYNC_TEMPLATE	Path to environment template directory	~/.git-agent-sync/templates/default
GIT_AGENT_SYNC_AUTO_INSTALL	Auto-install dependencies (true/false)	true

Global Config

Location: ~/.git-agent-sync/config.json

{
  "workspacePath": "./.agent-workspaces",
  "defaultBranch": "main",
  "autoInstall": true,
  "templates": {
    "default": "~/.git-agent-sync/templates/default"
  }
}

Workspace Config

Location: .agent-workspace.json (in workspace root)

{
  "agentName": "claude-code-1",
  "branch": "agent-claude-code-1",
  "createdAt": "2024-01-15T10:30:00Z",
  "mainBranch": "main",
  "environment": {
    "AGENT_ID": "claude-code-1",
    "WORKSPACE_PATH": "/path/to/workspace"
  }
}

Examples

Parallel Agent Development

# Create workspaces for multiple agents
git-agent-sync create claude-1
git-agent-sync create claude-2
git-agent-sync create gpt-4

# Work in parallel
cd .agent-workspaces/agent-claude-1
# ... make changes

cd .agent-workspaces/agent-claude-2
# ... make changes

# Review changes
git-agent-sync diff claude-1
git-agent-sync diff claude-2

# Merge when ready
git-agent-sync merge claude-1
git-agent-sync merge claude-2

Custom Template

# Create a custom template
mkdir -p ~/.git-agent-sync/templates/nodejs
cat > ~/.git-agent-sync/templates/nodejs/.env.template <<EOF
NODE_ENV=development
AGENT_ID={agentName}
WORKSPACE_PATH={workspacePath}
EOF

# Use the template
git-agent-sync create my-agent --template ~/.git-agent-sync/templates/nodejs

Architecture

git-agent-sync/
├── src/
│   ├── commands/       # CLI command implementations
│   │   ├── create.ts   # Create worktree
│   │   ├── list.ts     # List workspaces
│   │   ├── status.ts   # Show changes
│   │   ├── diff.ts     # Generate diffs
│   │   ├── merge.ts    # Merge to main
│   │   └── destroy.ts  # Remove workspace
│   ├── config/         # Configuration management
│   ├── utils/          # Utility functions
│   │   ├── git-utils.ts    # Git operations
│   │   ├── file-utils.ts   # File operations
│   │   ├── env-utils.ts    # Environment setup
│   │   └── diff-utils.ts   # Diff formatting
│   └── types/          # TypeScript types
├── templates/          # Environment templates
├── tests/              # Test files
└── bin/                # CLI entry point

Troubleshooting

Common Errors

Error	Solution
Git repository not found	Run command from within a git repository or initialize one first
Agent workspace already exists	Use a different agent name or destroy existing workspace first
Merge conflicts detected	Resolve conflicts manually or use --force flag with caution
Invalid agent name format	Use alphanumeric characters and hyphens only
Permission denied for workspace directory	Check directory permissions or use --path flag for alternative location

Debug Mode

Enable verbose output with:

git-agent-sync --verbose <command>

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: npm test
6. Submit a pull request

License

MIT License - see LICENSE file for details.