This commit is contained in:
310
.README.md
310
.README.md
@@ -1,329 +1,53 @@
|
||||
# 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
|
||||
A CLI tool that manages isolated git worktrees for AI coding agents.
|
||||
|
||||
## 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
|
||||
## Usage
|
||||
|
||||
1. **Initialize in a git repository:**
|
||||
### Create a new agent workspace
|
||||
|
||||
```bash
|
||||
cd your-git-repo
|
||||
git-agent-sync init
|
||||
git-agent-sync create <agent-name>
|
||||
```
|
||||
|
||||
2. **Create a workspace for an agent:**
|
||||
This creates an isolated git worktree for the specified AI agent.
|
||||
|
||||
### List all workspaces
|
||||
|
||||
```bash
|
||||
git-agent-sync create claude-code
|
||||
git-agent-sync list
|
||||
```
|
||||
|
||||
3. **Work in the workspace:**
|
||||
### Check workspace status
|
||||
|
||||
```bash
|
||||
cd .agent-workspaces/agent-claude-code
|
||||
# Make your changes
|
||||
git status
|
||||
git-agent-sync status <agent-name>
|
||||
```
|
||||
|
||||
4. **Generate a diff for review:**
|
||||
### Generate diff for review
|
||||
|
||||
```bash
|
||||
git-agent-sync diff claude-code
|
||||
git-agent-sync diff <agent-name>
|
||||
```
|
||||
|
||||
5. **Merge changes back to main:**
|
||||
### Merge changes back to main
|
||||
|
||||
```bash
|
||||
git-agent-sync merge claude-code
|
||||
git-agent-sync merge <agent-name>
|
||||
```
|
||||
|
||||
6. **Clean up when done:**
|
||||
### Destroy a workspace
|
||||
|
||||
```bash
|
||||
git-agent-sync destroy claude-code
|
||||
git-agent-sync destroy <agent-name>
|
||||
```
|
||||
|
||||
## 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.
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user