clash

KO | EN

gitlite — search

#python #react #javascript #swift #algorithm #android #golang #css #vue #data-structures #deep-learning #dart

★ 63 Open GitHub ↗

Avoid merge conflicts across git worktrees for parallel AI coding agents

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Clash</h1>

Avoid merge conflicts across git worktrees for parallel AI coding agents

Clash is an **open-source CLI tool** that helps avoid merge conflicts across **git worktrees**.

It's designed for developers running multiple AI coding agents (*Claude Code, Codex, Cursor*, etc.) in parallel — helping them identify **potential conflicts early** in the development process so they can work around them before it's too late.

## Table of Contents

- [Problem Statement](#problem-statement-with-some-context)
- [Clash - The Saviour](#clash---the-saviour)
- [Quick Start](#quick-start)
  - [Step 1: Quick Setup (Claude Code Recommended)](#step-1-quick-setup-claude-code-recommended)
  - [Step 2: Other Setups](#step-2-other-setups)
  - [Step 3: Manual CLI Usage](#step-3-manual-cli-usage)
- [Core Features](#core-features)
  - [Plugin Integration](#plugin-integration-claude-code--recommended)
  - [Check Command](#check-command-manual)
  - [Status Command](#status-command)
  - [Watch Mode](#watch-mode)
  - [JSON Output](#json-output)
- [Example: Multi-Agent Workflow](#example-multi-agent-workflow)
- [How It Works](#how-it-works)
- [Use Cases](#use-cases)
- [Architecture](#architecture)
- [Contributing](#contributing)
- [FAQ](#faq)

## Problem Statement with Some Context

AI coding agents like Claude Code have transformed software development as we know it. Developers now run **3-6+ agents simultaneously**, each working on a different feature/bug fix. The recommended approach put forward by most frontier labs is to isolate each agent in its own **git worktree** — essentially a separate working directory with its own branch.

When multiple AI agents (or developers) work in separate worktrees, they're **blind to each other's changes** and inevitably touch overlapping parts of the codebase. Conflicts only surface at feature completion, often after **significant work and time is wasted**. Current tools only catch these conflicts later down the line — we can do better by detecting them *earlier* in the process.

Clash surfaces **worktree-to-worktree conflicts early**, so you and your agents can be aware of overlapping changes and act on them before it's too late.

**Real quotes from developers:**

> *"Now you have created the fun new ability to create merge conflicts with yourself."*
> — GitButler Blog

> *"I now know to expect potential conflicts. This happened to me recently, which was a big learning moment."*
> — Developer on Medium

> *"If conflicts look tricky, I throw away the work."*
> — Developer workflow description

## Clash - The Saviour

Clash detects merge conflicts **between all worktree pairs** during development, helping you/agent:
- **Guard file writes via hooks** — automatic conflict check before every AI agent edit
- **See conflicts instantly** across all active worktrees
- **Visualize conflict matrix** showing which branches conflict
- **Monitor in real-time** as files change
- **Integrate with AI agents** via Claude Code hooks, CLAUDE.md instructions, or JSON output

### Clash in Action

**[Hook integration](#hook-integration-claude-code--recommended)** — Clash automatically detects conflicts before Claude Code writes a file. A single line in your settings and every file edit is guarded — no prompts to remember, no commands to run:

![Clash hook fires before Claude Code writes a conflicting file](https://clash.sh/demos/clash-check-hook-demo.gif)

*Automatic conflict detection — Clash prompts you before a conflicting edit goes through*

**Conflict warning in action** — When a file has conflicts with multiple worktrees, Clash surfaces a clear warning so you can coordinate:

![Clash warns about merge conflicts with multiple worktrees](https://clash.sh/demos/clash-hook-conflict-warning.png)

**CLI usage** — Ask your agent to use Clash directly for a full conflict overview:

![Clash alerts Claude Code to conflicts in another worktree, enabling smarter parallel development](https://clash.sh/demos/claude-using-clash-demo.gif)

*Clash alerts Claude Code to conflicts in another worktree, enabling smarter parallel development*

## Quick Start

### Step 1: Quick Setup (Claude Code Recommended)

Install Clash and the Claude plugin in one go:

```bash
curl -fsSL https://clash.sh/install.sh | sh && \
  claude plugin marketplace add clash-sh/clash && \
  claude plugin install clash@clash-sh
```

If `clash` is already installed, run plugin setup directly:

```bash
claude plugin marketplace add clash-sh/clash
claude plugin install clash@clash-sh
```

**That's it.** Clash will prompt you whenever Claude tries to edit a file that conflicts with another worktree.

### Step 2: Other Setups

**Not using Claude Code? Install Clash manually:**

```bash
curl -fsSL https://clash.sh/install.sh | sh    # Quick install (macOS/Linux)
brew tap clash-sh/tap && brew install clash    # Homebrew
cargo install clash-sh                         # From crates.io
```

**Claude Code (Alternative: Manual hook setup)**

<details>
<summary>Manual hook setup (without plugin)</summary>

If you prefer not to use the plugin, add the `hooks` key to your `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "clash check" }]
      }
    ]
  }
}
```

</details>

**Codex / Cursor / Windsurf / Other Agents (Manual)**

If hooks aren't available, add to your project instructions (e.g. `.claude/instructions.md`, `.cursorrules`):

```markdown
IMPORTANT: Before editing any file, run `clash check <file>` to check for merge conflicts
with other worktrees. If conflicts are detected, examine the conflicting files and adapt
your approach to avoid or minimize them.

Run `clash status` periodically (especially before and after commits) to get a full
conflict overview across all worktrees.

Run `clash --help` for all available commands.
```

### Step 3: Manual CLI Usage

```bash
# Check a single file for conflicts
clash check src/main.rs

# Check conflicts across all worktrees
clash status

# Output as JSON for scripts/agents
clash status --json

# Watch for conflicts in real-time
clash watch
```

![Quick demo showing clash status in action](https://clash.sh/demos/clash-status-demo-short.gif)

## Core Features

### Plugin Integration (Claude Code) — Recommended

The best way to use Clash with Claude Code — **automatic conflict detection before every file write, zero ongoing effort.**

```bash
claude plugin marketplace add clash-sh/clash
claude plugin install clash@clash-sh
```

Or manually add the hook to your `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "clash check" }]
      }
    ]
  }
}
```

When Claude tries to write or edit a file, Clash automatically:
1. Reads the target **file path** from the hook's stdin
2. Checks it for **conflicts across all worktrees**
3. If conflicts are found, prompts you with an **"ask" decision** — you can approve or deny the edit

![Clash hook fires before Claude Code writes a conflicting file](https://clash.sh/demos/clash-check-hook-demo.gif)

*Clash detects a conflict before Claude writes the file, giving you a chance to intervene*

> **Note:** Claude Code currently doesn't display the `permissionDecisionReason` in the prompt UI ([anthropics/claude-code#24059](https://github.com/anthropics/claude-code/issues/24059)). You'll see the permission prompt but not the conflict details. As a workaround, you can run `clash check <file>` manually to see full details.

### Check Command (Manual)

You can also run `clash check` manually to check a single file for conflicts across all worktrees:

```bash
clash check src/main.rs
```

```json
{
  "file": "src/main.rs",
  "current_worktree": "main",
  "current_branch": "main",
  "conflicts": [
    {
      "worktree": "clash-agent1",
      "branch": "feature/auth",
      "has_merge_conflict": true,
      "has_active_changes": false
    }
  ]
}
```

Exit codes: `0` = *no conflicts*, `2` = *conflicts found*, `1` = *error*.

### Status Command

Shows a beautiful conflict matrix for all worktree pairs:

```
╔════════════ Conflict Matrix ════════════╗
║            │ main  feat/a  feat/b  feat/c║
╟────────────┼─────────────────────────────╢
║main        │  -     OK      OK      OK   ║
║feature/a   │  OK     -      2       1    ║
║feature/b   │  OK     2      -       3    ║
║feature/c   │  OK     1      3       -    ║
╚══════════════════════════════════════════╝
```

Numbers indicate **conflicting files**. **"OK"** means no conflicts.

### Watch Mode
Live **TUI monitoring** with automatic refresh on file changes:

```bash
# Shows worktree status and conflict updates in real-time
clash watch
```

![Watch mode detecting conflicts as files change in real-time](https://clash.sh/demos/clash-watch-realtime-demo.gif)

### JSON Output

**Machine-readable output** for CI/CD and AI agents:

![JSON output for AI agents, scripts, and automation pipelines](https://clash.sh/demos/clash-status-json-demo.gif)

## Example: Multi-Agent Workflow

![Multiple AI agents working in parallel with Clash coordination](https://clash.sh/demos/multi-agent-clash-demo-v1.gif)

*Coordinating multiple AI agents across worktrees - each agent works independently while using Clash for monitoring for conflicts*

## How It Works

Clash uses `git merge-tree` (via the *gix* library) to perform **three-way merges** between worktree pairs **without modifying your repository**. It:

1. **Discovers** all worktrees (main + linked)
2. **Finds the merge base** for each pair
3. **Simulates the merge** to detect conflicts
4. **Reports** conflicting files

This is **100% read-only** — your repository is *never* modified.

## Use Cases

### For AI Agent Orchestrators
Prevent wasted compute when agents' work conflicts:
```bash
# Check before expensive operations
if clash status --json | jq -e '.conflicts | length > 0'; then
  echo "Conflicts detected! Replan agent tasks"
fi
```

### For Human Teams
See what your teammates are changing before you merge:
```bash
# Add to git pre-merge hook
clash status || echo "Warning: Conflicts detected!"
```

### For CI/CD Pipelines
Fail fast when feature branches conflict:
```yaml
- name: Check for conflicts
  run: |
    cargo install clash
    clash status --json > conflicts.json
    jq -e '.conflicts | length == 0' conflicts.json
```

## Architecture

Clash is written in **Rust** for speed and reliability:

| Crate | Purpose |
|-------|---------|
| **gix** | Git operations without shelling out |
| **ratatui** | Terminal UI framework |
| **notify** | File system watching |
| **serde** | JSON serialization |

**Single binary, no runtime dependencies.** Works anywhere git works.

## Contributing

We really appreciate **all contributions** big or small!

- ⭐ Star the repo — helps others discover Clash
- 🗣️ Tell a friend about Clash
- 📝 [**Open an issue**](https://github.com/clash-sh/clash/issues/) — feedback, feature requests, even small friction points or confusing messages, or [AI agent coordination pain not yet solved](https://github.com/clash-sh/clash/issues/new?title=Agent%20coordination%20friction%3A%20&body=%23%23%20The%20friction%0A%0A%3C!--%20What%20agent%20coordination%20task%20is%20still%20painful%3F%20--%3E%0A%0A%23%23%20Current%20workaround%0A%0A%3C!--%20How%20do%20you%20handle%20this%20today%3F%20--%3E%0A%0A%23%23%20Ideal%20solution%0A%0A%3C!--%20What%20would%20make%20this%20easier%3F%20--%3E)
- 📢 **Share**: [X](https://twitter.com/intent/tweet?text=Clash%20%E2%80%94%20Avoid%20merge%20conflicts%20across%20git%20worktrees%20for%20parallel%20AI%20coding%20agents&url=https%3A%2F%2Fgithub.com%2Fclash-sh%2Fclash) · [Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fclash-sh%2Fclash&title=Clash%20%E2%80%94%20Avoid%20merge%20conflicts%20across%20git%20worktrees%20for%20parallel%20AI%20coding%20agents) · [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fclash-sh%2Fclash)

See [CONTRIBUTING.md](CONTRIBUTING.md) for some more details.

## FAQ

**Q: Does Clash modify my repository?**
A: **Never.** Clash is 100% read-only. It simulates merges in memory.

**Q: Can it resolve conflicts?**
A: Not yet — Clash *detects* conflicts. Resolution suggestions may come in a future version. In the meantime, your AI agent can act on the conflict information directly.

## Support

- 🐛 [Report bugs](https://github.com/clash-sh/clash/issues)
- 📧 [Email support](mailto:matk9@clash.sh)

## License

MIT - See [LICENSE](LICENSE) file for details.

## Acknowledgments

Built with Love, Rust & Claude.

Special thanks to the Rust community for incredible libraries that made this possible.

clash

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README