git-parsec
From ticket to PR. One command.
Git worktree lifecycle manager — isolated workspaces tied to your tickets, with stacked PRs, multi-forge support, and clean shipping.
$ parsec start PROJ-1234 # creates worktree, fetches Jira title, sets up branch
$ parsec ship PROJ-1234 # pushes, opens PR, cleans worktree
That's the whole loop. Plain git worktree doesn't track state, doesn't talk to your tracker, doesn't open PRs, doesn't clean up. parsec does.
Why use it
- No
index.lock collisions — every workspace has its own .git/index, so multiple developers (or AI agents) can run git add on the same repo at the same time.
- One command per phase —
start (worktree + tracker fetch), ship (push + PR + cleanup), merge (merge + branch cleanup), clean (sweep merged branches). No web UI round-trips.
- Stacked PRs that don't melt your brain —
parsec start FOO --on BAR chains workspaces; parsec stack --submit opens the whole stack in topological order with auto-posted "← prev / next →" navigation comments.
- Cross-worktree conflict detection —
parsec conflicts flags files modified in two workspaces before anyone pushes.
- Multi-forge — GitHub, GitLab, Bitbucket Cloud. Multi-tracker — Jira, GitHub Issues, GitLab Issues, Bitbucket.
- Agent-friendly —
--json on every command, structured error codes, JSONL execution log, headless/offline modes.
Roadmap
Vision: parsec = AI agents + human devs both — worktree-native git CLI.
| Milestone | Status | Theme |
|---|
| v0.4.0 | ✅ Released (2026-05-04) | Multi-forge + multi-tracker foundation (GitHub / GitLab / Bitbucket; Jira / Linear) |
| v0.5.0 — The visualization release | ✅ Released (2026-06-03) | smartlog · TUI dashboard · speculative merge · parsec test · health · reviews · AI PR descriptions |
| v1.0.0 — AI-Native Standard | ✅ Released (2026-09-19) | MCP server — Claude Desktop and Cursor invoke parsec as a first-class tool |
v1.0 is the final planned feature release. See the CHANGELOG
for release notes and the MCP quickstart for setup.
Install
# Pre-built Linux x86_64 binary
curl -LO https://github.com/erishforG/git-parsec/releases/latest/download/parsec-1.0.0-x86_64-unknown-linux-gnu.tar.gz
tar xzf parsec-*.tar.gz && sudo mv parsec /usr/local/bin/
# Cargo (Rust toolchain required)
cargo install git-parsec
Other targets (macOS arm64/x86_64, Windows x86_64) ship on every release — see Releases. After install, run parsec config init for the interactive first-time setup, then parsec doctor to validate.
Shell completion
parsec ships dynamic completion scripts that suggest live worktrees and branches as you type (e.g. parsec switch <Tab> lists your active tickets).
# zsh — copy to a site fpath dir, or add the repo path to fpath:
cp completions/_parsec ~/.zsh/completions/ # then: fpath=(~/.zsh/completions $fpath)
# bash:
source completions/parsec.bash # or symlink into /etc/bash_completion.d/
# fish:
cp completions/parsec.fish ~/.config/fish/completions/
A purely static fallback (no live candidates) is also available via parsec config completions <shell> if you'd rather not source the dynamic scripts.
60-second tour
# Pull a ticket from Jira / GitHub / GitLab / Bitbucket and start work
$ parsec start PROJ-1234
✓ Worktree: ../myapp.PROJ-1234
Title: Add rate limiting (fetched from Jira)
Branch: feature/PROJ-1234
# See everything in flight
$ parsec list
╭───────────┬───────────────────┬────────┬─────────────────────────╮
│ Ticket │ Branch │ Status │ Path │
├───────────┼───────────────────┼────────┼─────────────────────────┤
│ PROJ-1234 │ feature/PROJ-1234 │ active │ ../myapp.PROJ-1234 │
│ PROJ-5678 │ feature/PROJ-5678 │ active │ ../myapp.PROJ-5678 │
╰───────────┴───────────────────┴────────┴─────────────────────────╯
# Hop in (shell integration auto-cd's)
$ parsec switch PROJ-1234
# Make commits the normal way, then ship — push + PR + cleanup in one shot
$ parsec ship PROJ-1234
✓ Pushed feature/PROJ-1234
✓ PR opened: github.com/org/repo/pull/42
✓ Worktree cleaned up
# Watch CI without leaving the terminal
$ parsec ci PROJ-1234 --watch
# Merge from terminal once CI is green
$ parsec merge PROJ-1234
Top features
🌿 Stacked PRs that don't melt your brain
$ parsec start PROJ-2 --on PROJ-1 # new worktree on top of PROJ-1's branch
$ parsec stack --submit # open all PRs in the stack, root first
parsec auto-posts ← previous PR / next PR → navigation comments so reviewers can walk the chain.
🔄 Multi-forge, multi-tracker
- Forges: GitHub · GitLab · Bitbucket Cloud (full PR lifecycle on each)
- Trackers: Jira · GitHub Issues · GitLab Issues · Bitbucket
- CI status: GitHub Actions · GitLab CI · Bitbucket Pipelines
parsec ci and pr-status work the same shape across all of them.
🤖 Agent-friendly by design
Every command has --json. Errors emit structured codes (E001…E013). parsec log --export outputs JSONL with execution IDs and per-step timing for tooling/agents to consume. --offline and [behavior].offline config skip all network ops for air-gapped or CI environments.
🔌 MCP server (new in v1.0)
Expose parsec's worktree lifecycle to Claude Desktop or Cursor over stdio:
parsec mcp install claude-desktop
parsec mcp serve
The server provides worktree, health, smartlog, PR, review, CI, and sync tools.
Mutating calls are previewed and confirmation-gated; delegated tokens are
scope-checked and repository paths are sandboxed. See the
MCP quickstart and security model.
🧹 Lifecycle hygiene
parsec clean sweeps worktrees for already-merged branches. parsec conflicts flags cross-worktree file overlap before you push. parsec undo reverses the last operation (start, ship, clean). parsec doctor validates every part of your setup with actionable fix instructions.
📂 Worktree build cache sharing
[worktree].shared_cache = ["target", "node_modules", ".venv"] lets new worktrees reuse the main repo's caches via symlink (default) or copy. Eliminates cold-build cost on parsec start for any project with significant dependency caches.
📋 Sprint board + issue creation
parsec board turns your active sprint into a Kanban board in the terminal. parsec create and parsec new-issue open issues in your tracker without leaving the shell.
🌌 Visualization & power-user tools (new in v0.5)
parsec smartlog (alias sl) — ASCII commit DAG of every active worktree with PR / CI overlay.parsec dashboard (alias dash) — real-time TUI panel showing worktrees, CI, and PRs in one screen (ratatui + crossterm).parsec health — lock / uncommitted / stale / CI checks across every worktree, with a configurable stale threshold.parsec reviews — open PR reviews you've received vs. requested, unified across worktrees.parsec conflicts --simulate — in-memory three-way merge to surface real line-level conflicts before you push (worktree-vs-base + cross-worktree pairs, read-only).parsec test — run tests in parallel across worktrees with tree-hash result caching (--all --jobs N --cache).parsec sync — fast-forward stale worktrees against origin/<base> (rebase or merge, --all, --dry-run).
33+ commands total — see the full command reference for every flag and example.
Each PR body includes a stack navigation table:
| Ticket | Branch |
|---|
| ⬆ Parent | PROJ-1 | feature/PROJ-1 |
| ➡ Current | PROJ-2 | feature/PROJ-2 |
| ⬇ Child | PROJ-3 | feature/PROJ-3 |
Configuration (minimal example)
# ~/.config/parsec/config.toml
#:schema https://json.schemastore.org/parsec.json
[workspace]
layout = "sibling" # ../repo.ticket/ (alt: "internal")
branch_prefix = "feature/"
offline = false # true = skip all network ops
[tracker]
provider = "jira" # jira | github | gitlab | bitbucket | none
[tracker.jira]
base_url = "https://yourcompany.atlassian.net"
# Auth: PARSEC_JIRA_TOKEN env var
[ship]
auto_pr = true
auto_cleanup = true
draft = false # true = open PRs as drafts
# template = ".github/PULL_REQUEST_TEMPLATE.md"
[worktree]
shared_cache = ["target", "node_modules", ".venv"]
cache_strategy = "symlink" # alt: "copy"
Auth tokens (set via env vars, all optional):
PARSEC_JIRA_TOKEN PARSEC_GITHUB_TOKEN PARSEC_GITLAB_TOKEN
PARSEC_BITBUCKET_TOKEN GITHUB_TOKEN (fallback) GITLAB_TOKEN (fallback)
PARSEC_OFFLINE=1 — force offline mode globally
Full schema and every option: parsec config schema (also published to schemastore.org).
Comparison
| parsec | GitButler | worktrunk | git worktree | git-town |
|---|
| Tracker integration | Jira + GitHub + GitLab + Bitbucket | — | — | — | — |
| Physical worktree isolation | ✅ | ❌ (virtual) | ✅ | ✅ | ❌ |
| Cross-worktree conflict detection | ✅ | n/a | ❌ | ❌ | ❌ |
| One-step ship (push + PR + cleanup) | ✅ | ❌ | ❌ | ❌ | ✅ |
| Forges | GitHub + GitLab + Bitbucket | Both | GitHub | — | GitHub, GitLab, Gitea, Bitbucket |
| CI integrations | Actions + GitLab CI + Bitbucket Pipelines | — | — | — | — |
| Operation log + undo | ✅ | ✅ | ❌ | ❌ | partial |
| JSON output | ✅ | ✅ | ❌ | ❌ | ❌ |
| Stacked PRs | ✅ | ✅ | ❌ | ❌ | ✅ |
| GUI | CLI only | Desktop + TUI | CLI | CLI | CLI |
Documentation
Error codes
Every command exits with a structured code. JSON output (--json) includes the same code:
| | |
|---|
E001 no auth token | E005 workspace not found | E009 policy violation |
E002 CI failing | E006 workspace already exists | E010 PR not found |
E003 merge conflict | E007 no active workspaces | E011 tracker not configured |
E004 PR not mergeable | E008 pre-ship hook failed | E012 ship partial |
| | E013 cannot undo |
$ parsec ship PROJ-1234 --json 2>&1
{"error":{"code":"E001","message":"No GitHub token configured","hint":"Set PARSEC_GITHUB_TOKEN or run gh auth login"}}
$ echo $?
2
License
MIT — see LICENSE.
