DEV Community

Cover image for git-parsec: The Git Worktree Manager Your Team Needs
Housk Shin
Housk Shin

Posted on

git-parsec: The Git Worktree Manager Your Team Needs

#rust #git #productivity #cli

git-parsec: The Git Worktree Manager Your Team Needs

The Real Problem With git worktree

You're running multiple AI coding agents on your repository. Or maybe your team wants to work on several features in parallel.

Git worktrees solve the isolation problem — each worktree has its own working directory and index, so multiple agents can commit simultaneously without index.lock conflicts.

But creating worktrees is just the beginning. The lifecycle management is where things fall apart:

# Create worktrees manually
git worktree add ../repo.PROJ-1234 -b feature/PROJ-1234
git worktree add ../repo.PROJ-5678 -b feature/PROJ-5678

# Now what?
# - Which branch corresponds to which ticket?
# - How do you ship (push + PR + cleanup) without five manual steps?
# - Are two worktrees editing the same files?
# - What's the CI status for each PR?
# - How do you undo a mistake?
Enter fullscreen mode Exit fullscreen mode

You end up with a mess of worktrees, branches, and manual bookkeeping. Every time you ship a feature, it's: git push, open browser, create PR, come back, git worktree remove, git branch -D... for each ticket.

There had to be a better way. Enter git-parsec.

What is git-parsec?

git-parsec is a CLI tool written in Rust that automates the complete lifecycle of git worktrees. It's built for parallel workflows—whether you're coordinating multiple AI agents or your team is shipping features independently.

Think of parsec as your git worktree manager. It handles:

  • Ticket-driven workspaces — Create worktrees tied to Jira, GitHub Issues, or GitLab Issues
  • Zero-conflict parallelism — Each worktree gets its own index; no lock contention
  • Conflict detection — Warns you when multiple worktrees modify the same files
  • One-step shipping — Push, create a PR/MR, and clean up with a single command
  • CI monitoring — Watch your builds directly from the terminal
  • Operation history — parsec log and parsec undo let you track and revert actions
  • Machine-readable output — --json on every command for AI agent consumption

Installation 

cargo install git-parsec
Enter fullscreen mode Exit fullscreen mode

Or build from source:

git clone https://github.com/erishforG/git-parsec.git
cd git-parsec
cargo build --release
Enter fullscreen mode Exit fullscreen mode

Quick Start: 5 Commands

Let's walk through a real workflow.

1. Start a worktree for a ticket 

$ parsec start PROJ-1234 --title "Add user authentication"
Created workspace for PROJ-1234 at /home/user/myapp.PROJ-1234
  Add user authentication

  Tip: cd $(parsec switch PROJ-1234)
Enter fullscreen mode Exit fullscreen mode

Parsec creates a new worktree in a sibling directory (e.g., myapp.PROJ-1234) and checks out a new branch named feature/PROJ-1234. The --title can come from your Jira integration too—just run parsec start PROJ-1234 and it'll fetch the title automatically.

2. Switch into the workspace and start working 

$ cd $(parsec switch PROJ-1234)
$ git add src/auth.rs && git commit -m "Implement OAuth2 flow"
Enter fullscreen mode Exit fullscreen mode

You're now in an isolated worktree. No index.lock conflicts with other agents or developers.

3. Start another ticket in parallel 

$ parsec start PROJ-5678 --title "Fix payment timeout"
Created workspace for PROJ-5678 at /home/user/myapp.PROJ-5678
Enter fullscreen mode Exit fullscreen mode

Both worktrees exist simultaneously. Both can commit independently. No conflicts.

4. Check for file conflicts across worktrees 

$ parsec conflicts
No conflicts detected.
Enter fullscreen mode Exit fullscreen mode

Before you ship, make sure no two worktrees are modifying the same files. If they are, parsec warns you:

$ parsec conflicts
╭──────────────────┬──────────────────────╮
│ File             │ Worktrees            │
├──────────────────┼──────────────────────┤
│ src/api/router.rs│ PROJ-1234, PROJ-5678 │
╰──────────────────┴──────────────────────╯
Enter fullscreen mode Exit fullscreen mode

5. Ship it 

$ parsec ship PROJ-1234
Shipped PROJ-1234!
  PR: https://github.com/org/repo/pull/42
  Workspace cleaned up.
Enter fullscreen mode Exit fullscreen mode

That single command:

  • Pushes your branch to the remote
  • Creates a PR (GitHub) or MR (GitLab)
  • Removes the worktree and cleans up
  • All in one step

Core Features Deep Dive

Ticket Tracker Integration

Connect parsec to your issue tracker and it auto-fetches ticket titles:

# Setup once
$ parsec config init
? Which tracker? (jira/github/gitlab/none) › jira
? Jira base URL? › https://yourcompany.atlassian.net

# Now titles are automatic
$ parsec start PROJ-1234
Created workspace for PROJ-1234 at /home/user/myapp.PROJ-1234
  Implement rate limiting for API endpoints
Enter fullscreen mode Exit fullscreen mode

Supported trackers: Jira, GitHub Issues, GitLab Issues, or none (manual titles).

One-Step Shipping

parsec ship is the killer feature. One command does what normally takes five:

$ parsec ship PROJ-1234 [--draft] [--no-pr]
Enter fullscreen mode Exit fullscreen mode
  • ✓ Pushes your branch
  • ✓ Creates a PR/MR (platform auto-detected)
  • ✓ Cleans up the worktree
  • ✓ Removes the branch (if cleanup enabled)

Use --draft to create a draft PR, or --no-pr to push without creating a PR.

CI Monitoring with Watch Mode

Monitor your CI directly from the terminal. No browser tab switching:

$ parsec ci PROJ-1234 --watch
CI for PROJ-1234 (PR #42, a1b2c3d)
┌────────────┬───────────┬──────────┐
│ Check      │ Status    │ Duration │
├────────────┼───────────┼──────────┤
│ Tests      │ ✓ passed  │ 2m 15s   │
│ Build      │ ✓ passed  │ 1m 42s   │
│ Lint       │ ● running │ running… │
└────────────┴───────────┴──────────┘
✓ CI: 2/3 — 2 passed, 1 running

# --watch mode refreshes every 5s until all checks complete
Enter fullscreen mode Exit fullscreen mode

Merge PRs Without Leaving Terminal 

$ parsec merge PROJ-1234 [--rebase] [--no-wait]
Waiting for CI to pass... ✓
Merged PR #42 for PROJ-1234!
  Method: squash
  SHA:    a1b2c3d
Enter fullscreen mode Exit fullscreen mode

By default, parsec waits for CI to pass before merging. Use --no-wait to skip that check. Use --rebase for rebase merge instead of squash.

Conflict Detection

When multiple worktrees modify the same files, you need to know before you ship:

$ parsec conflicts
╭──────────────────┬──────────────────────╮
│ File             │ Worktrees            │
├──────────────────┼──────────────────────┤
│ src/config.ts    │ PROJ-1234, PROJ-5678 │
│ src/utils.ts     │ PROJ-1234, PROJ-9000 │
╰──────────────────┴──────────────────────╯
Enter fullscreen mode Exit fullscreen mode

Perfect for coordinating AI agents or team members. Spot conflicts before they become merge conflicts.

Stacked PRs

Create dependent PR chains where PR B builds on top of PR A:

$ parsec start PROJ-1 --title "Add models"
$ parsec start PROJ-2 --on PROJ-1 --title "Add API endpoints"
$ parsec start PROJ-3 --on PROJ-2 --title "Add frontend"

$ parsec stack
Stack dependency graph:
└── PROJ-1 Add models
    └── PROJ-2 Add API endpoints
        └── PROJ-3 Add frontend
Enter fullscreen mode Exit fullscreen mode

When you ship, each PR gets the correct base branch:

$ parsec ship PROJ-1   # PR to main
$ parsec ship PROJ-2   # PR to feature/PROJ-1
$ parsec ship PROJ-3   # PR to feature/PROJ-2
Enter fullscreen mode Exit fullscreen mode

Operation History & Undo

Track what happened and revert if needed:

$ parsec log
╭───┬───────┬───────────┬───────────────────────────────┬──────────────────╮
│ # │ Op    │ Ticket    │ Detail                        │ Time             │
├───┼───────┼───────────┼───────────────────────────────┼──────────────────┤
│ 4 │ clean │ PROJ-5678 │ Cleaned workspace             │ 2026-04-15 14:30 │
│ 3 │ ship  │ PROJ-1234 │ Shipped branch 'feature/1234' │ 2026-04-15 14:02 │
│ 2 │ start │ PROJ-5678 │ Created workspace             │ 2026-04-15 13:55 │
│ 1 │ start │ PROJ-1234 │ Created workspace             │ 2026-04-15 09:14 │
╰───┴───────┴───────────┴───────────────────────────────┴──────────────────╯

$ parsec undo
Undid start for PROJ-5678
  Worktree removed.
Enter fullscreen mode Exit fullscreen mode

JSON Output for AI Agents

Every command supports --json for machine consumption:

$ parsec list --json
[
  {
    "ticket": "TEST-1",
    "path": "/home/user/myapp.TEST-1",
    "branch": "feature/TEST-1",
    "base_branch": "main",
    "created_at": "2026-04-15T09:00:00Z",
    "ticket_title": "Add auth",
    "status": "active"
  }
]
Enter fullscreen mode Exit fullscreen mode

Perfect for orchestration scripts or AI agents that need structured output.

parsec vs. The Alternatives

Feature parsec Worktrunk wtp git worktree git-town
Ticket tracker integration ✓ (Jira, GitHub, GitLab) ✗ ✗ ✗ ✗
Physical isolation (worktrees) ✓ ✓ ✓ ✓ ✗
Cross-worktree conflict detection ✓ ✗ ✗ ✗ ✗
One-step ship (push+PR+cleanup) ✓ ✗ ✗ ✗ ✓
GitHub + GitLab support Both GitHub ✗ ✗ GitHub, GitLab, Gitea, Bitbucket
Operation history & undo ✓ ✗ ✗ ✗ ✓ (undo)
JSON output ✓ ✗ ✗ ✗ ✗
CI monitoring ✓ (with --watch) ✗ ✗ ✗ ✗
Stacked PRs ✓ ✗ ✗ ✗ ✓
Post-create hooks ✓ ✓ ✓ ✗ ✗
Zero-config start ✓ ✓ ✓ ✗ ✗

TL;DR: parsec combines worktree isolation with ticket tracker integration, CI monitoring, and cross-worktree conflict detection — a combination no other tool currently offers.

All Commands at a Glance 

# Workspace management
parsec start PROJ-1234              # Create worktree for a ticket
parsec adopt PROJ-1234 --branch fix/bug  # Import existing branch
parsec switch PROJ-1234             # Get path to worktree
parsec list                         # See all active workspaces
parsec status [ticket]              # Detailed workspace status
parsec clean [--all]                # Remove worktrees

# Shipping & PRs
parsec ship PROJ-1234 [--draft]     # Push + PR + cleanup
parsec merge PROJ-1234 [--no-wait]  # Merge PR from terminal
parsec pr-status [ticket]           # Check PR review status
parsec ci [ticket] [--watch]        # Monitor CI status

# Changes & syncing
parsec diff [ticket]                # View changes vs base
parsec sync [--all]                 # Rebase all worktrees
parsec conflicts                    # Detect cross-worktree conflicts

# History & stacks
parsec log [ticket]                 # Operation history
parsec undo                         # Revert last operation
parsec stack [--sync]               # Stacked PR dependency graph
parsec open [ticket]                # Open PR or ticket page

# Configuration
parsec config init                  # Setup wizard
parsec config show                  # Show configuration
parsec config completions zsh       # Generate shell completions
parsec config man                   # Install man page
Enter fullscreen mode Exit fullscreen mode

Getting Started

1. Install 

cargo install git-parsec
Enter fullscreen mode Exit fullscreen mode

2. Setup (optional but recommended) 

parsec config init
Enter fullscreen mode Exit fullscreen mode

Answer a few questions about your tracker (Jira, GitHub, GitLab) and you're done.

3. Start your first worktree 

cd your-repo
parsec start PROJ-1234
cd $(parsec switch PROJ-1234)
Enter fullscreen mode Exit fullscreen mode

4. Explore 

# List all worktrees
parsec list

# Check for conflicts
parsec conflicts

# See your work in progress
parsec diff

# Ship when ready
parsec ship PROJ-1234
Enter fullscreen mode Exit fullscreen mode

Perfect For

  • AI Agent Orchestration — Run multiple Claude Code agents on the same repo without lock conflicts
  • Large Teams — Developers work on independent features without branching complexity
  • High-Velocity Teams — Ship features fast with one-command shipping
  • Monorepos — Isolate changes by feature or domain
  • Stacked Workflows — Build dependent features with automatic rebasing

One More Thing

parsec is free, open-source, and MIT-licensed. Star the repo on GitHub:

erishforG/git-parsec

Documentation: erishforg.github.io/git-parsec

Have feedback? Found a bug? Open an issue or PR. We're actively developing parsec and love community input.

FAQ

Q: Will parsec work with my Git hosting platform?

A: parsec auto-detects GitHub, GitHub Enterprise, GitLab, and GitLab self-hosted from your remote URL. If it doesn't recognize yours, let us know.

Q: Can I use parsec without a ticket tracker?

A: Absolutely. Run parsec start <anything> and provide a manual title with --title "Your title here". No tracker integration required.

Q: What if I already have worktrees created with plain git worktree?

A: Use parsec adopt to import them into parsec management.

Q: How does parsec handle merge conflicts?

A: parsec detects when two worktrees modify the same files and warns you. When you merge a PR, Git handles conflicts as normal.

Q: Can I use parsec in a CI/CD pipeline?

A: Yes. Every command supports --json for machine consumption, and you can set PARSEC_*_TOKEN environment variables for non-interactive auth.

Start shipping faster. No more context switching. No more index.lock nightmares.

Try parsec today: cargo install git-parsec

Top comments (0)