# 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

```bash
# 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

```bash
npm install -g git-agent-sync
```

## Quick Start

1. **Initialize in a git repository:**

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

2. **Create a workspace for an agent:**

```bash
git-agent-sync create claude-code
```

3. **Work in the workspace:**

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

4. **Generate a diff for review:**

```bash
git-agent-sync diff claude-code
```

5. **Merge changes back to main:**

```bash
git-agent-sync merge claude-code
```

6. **Clean up when done:**

```bash
git-agent-sync destroy claude-code
```

## Commands

### create

Create an isolated worktree for an AI agent.

```bash
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:**
```bash
git-agent-sync create claude-code --env API_KEY=abc123
```

### list

List all active agent workspaces.

```bash
git-agent-sync list [options]
```

**Options:**
- `--json` - Output as JSON
- `--verbose` - Show detailed information

**Example:**
```bash
git-agent-sync list --verbose
```

### status

Show detailed changes for a specific agent workspace.

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

**Options:**
- `--short` - Show short summary only
- `--output <file>` - Export to file

**Example:**
```bash
git-agent-sync status claude-code --short
```

### diff

Generate unified diffs for code review.

```bash
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:**
```bash
git-agent-sync diff claude-code --output diff.md
```

### merge

Safely merge agent changes back to main branch.

```bash
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:**
```bash
git-agent-sync merge claude-code --dry-run
```

### destroy

Safely remove an agent workspace.

```bash
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:**
```bash
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`

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

### Workspace Config

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

```json
{
  "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

```bash
# 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

```bash
# 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:

```bash
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.