Installation

#

parsec is a single Rust binary with no runtime dependencies. Install via cargo, or build from source.

Via cargo (recommended)

The fastest path. Requires Rust and cargo to be installed.

install via cargo

$ cargo install git-parsec Compiling git-parsec v0.2.4 ✓ Installed ~/.cargo/bin/parsec # Verify installation $ parsec --version parsec 0.3.3

Build from source

Clone the repository and build with cargo build --release. The compiled binary is at ./target/release/parsec.

build from source

$ git clone https://github.com/erishforG/git-parsec.git $ cd git-parsec $ cargo build --release ✓ Binary at ./target/release/parsec # Move to a directory on your $PATH $ cp ./target/release/parsec /usr/local/bin/

Shell completions

Generate tab completions for your shell. Completions cover all commands and flags.

shell completions

# zsh — add to fpath $ parsec config completions zsh > ~/.zsh/completions/_parsec # bash $ parsec config completions bash > ~/.local/share/bash-completion/completions/parsec # fish $ parsec config completions fish > ~/.config/fish/completions/parsec.fish

Shell Integration

#

Shell integration is the single most impactful quality-of-life improvement parsec offers. It hooks into your shell to enable seamless directory switching and automatic working-directory recovery.

enable shell integration

# Add to ~/.zshrc (or ~/.bashrc for bash) eval "$(parsec init zsh)" # Reload your shell $ source ~/.zshrc

What shell integration does

1

Auto-cd on switch

When you run parsec switch TICKET, your shell automatically changes directory into the worktree. Without integration, parsec can only print the path — your shell script would need to call cd $(parsec switch TICKET) manually.
2

CWD recovery after merge/clean

When parsec removes a worktree you're currently inside (e.g. after parsec merge), your shell would normally be stranded in a deleted directory. Shell integration detects this and automatically moves you back to the main repository root.

✓

Recommended for all users

Shell integration has no downsides and makes the switch/merge workflow significantly smoother. Add the eval line to your rc file during first-time setup.

Quick Start Workflow

#

The core parsec lifecycle follows a simple loop: start → code → ship → merge → clean. Each step is one command.

start

create workspace

→

code

work & commit

→

ship

push + open PR

→

merge

merge PR

→

clean

remove worktrees

full lifecycle demo

# 1. Create an isolated workspace from a Jira ticket $ parsec start PROJ-123 ✓ Created worktree for PROJ-123 Branch: feature/PROJ-123 Path: ../myrepo.PROJ-123 # 2. Switch into the worktree (auto-cd with shell integration) $ parsec switch PROJ-123 # shell: → cd ../myrepo.PROJ-123 # 3. Do your work, commit as usual $ git add . && git commit -m "feat: auth flow" # 4. Check for conflicts with parallel work $ parsec conflicts ✓ No conflicts across 3 worktrees # 5. Ship: push + open PR + clean worktree $ parsec ship PROJ-123 ✓ Pushed feature/PROJ-123 (3 commits) ✓ PR #42 created: github.com/org/myrepo/pull/42 ✓ Worktree cleaned up # 6. After review — merge and clean up remote branch $ parsec merge PROJ-123 ✓ PR #42 merged into main # 7. Tidy up any remaining worktrees $ parsec clean ✓ Removed 1 merged worktree

ⓘ

First-time setup

Before running parsec start for the first time, run parsec config init to configure your issue tracker and GitHub token. See Tracker Configuration below.

Tracker Configuration

#

parsec integrates with three issue trackers. Run parsec config init for an interactive setup wizard, or edit ~/.config/parsec/config.toml directly.

Jira

Connect to Jira Cloud or Jira Server. parsec fetches ticket titles, statuses, and assignees automatically.

Cloud & Server

GitHub Issues

Works out of the box when your remote is GitHub. Uses the same token as your GitHub API access.

github.com

GitLab

Connects to GitLab.com or self-hosted GitLab instances via personal access token.

Cloud & Self-hosted

Jira setup

parsec config init — Jira

$ parsec config init ? Tracker type: jira ? Jira base URL: https://myorg.atlassian.net ? Jira email: you@company.com ? Jira API token: *** ? GitHub token: ghp_*** ? Default branch: main ✓ Config saved to ~/.config/parsec/config.toml

ⓘ

Jira API token

Generate a Jira API token at id.atlassian.com/manage-profile/security/api-tokens. parsec uses it for read-only ticket lookups; it never writes to Jira.

GitHub Issues setup

When your repo remote is GitHub, parsec automatically uses GitHub Issues as the tracker. Provide a personal access token with repo scope.

parsec config init — GitHub Issues

$ parsec config init ? Tracker type: github ? GitHub token: ghp_*** ? Default branch: main ✓ Config saved # Ticket IDs are GitHub issue numbers $ parsec start 42 ✓ Created worktree for issue #42: Fix pagination bug

Config file reference

The config file lives at ~/.config/parsec/config.toml. You can edit it directly.

Key	Description	Example
`tracker.type`	Issue tracker backend.	`"jira"` / `"github"` / `"gitlab"`
`tracker.base_url`	Base URL for Jira/GitLab self-hosted.	`"https://myorg.atlassian.net"`
`tracker.token`	API token for the tracker.	Jira API token or GitLab PAT
`github.token`	GitHub personal access token (for PR creation).	`"ghp_..."`
`git.default_branch`	Default base branch for new worktrees.	`"main"` / `"develop"`
`git.worktree_prefix`	Directory prefix for new worktrees.	`".."` (sibling dirs)

!

No tracker configured

parsec still works without a tracker configured. Use --title "My description" with parsec start to provide a description manually. Ticket IDs become local labels only.

AI Agent Workflows

#

parsec was built from day one for parallel AI agent execution. Each worktree is an isolated git environment — agents can run git add, git commit, and git push simultaneously without index.lock collisions.

🔒

Zero index.lock conflicts

Each worktree has its own .git/index. Parallel agents never contend on the same file. No retries, no wasted tokens.

📈

JSON output for scripting

Every command supports --json for machine-readable output. Poll pr-status, check ci, trigger merge — all scriptable.

🔍

Conflict detection

parsec conflicts surfaces which files are modified by multiple agents before any PR is opened — catch issues early.

📄

Operation history & undo

parsec log shows every action. parsec undo rolls back the last step — useful when an agent ships prematurely.

Running multiple agents in parallel

Each agent gets its own worktree. Launch them concurrently from a coordinator script — parsec handles isolation so agents never need to coordinate on git state.

parallel agent launch script

#!/bin/bash # Each ticket becomes an isolated, independent workspace parsec start PROJ-120 --quiet & parsec start PROJ-121 --quiet & parsec start PROJ-122 --quiet & wait # Agent 1 works in ./myrepo.PROJ-120 # Agent 2 works in ./myrepo.PROJ-121 ← no conflicts # Agent 3 works in ./myrepo.PROJ-122

JSON output for automation

Use --json on any command to get structured output suitable for piping into jq or a coordinator agent.

JSON output examples

# Check if PR is mergeable $ parsec pr-status PROJ-120 --json | jq '.mergeable' true # Wait for CI then merge $ parsec ci PROJ-120 --watch --json # polls until complete, exits 0 on success $ parsec merge PROJ-120 # List all worktrees as JSON $ parsec list --json | jq '.[].ticket' "PROJ-120" "PROJ-121" "PROJ-122"

✓

Agent best practices

Run parsec conflicts before any agent calls parsec ship. This surfaces file-level overlaps between parallel workstreams before they become merge conflicts.

Stacked PRs

#

Stacked PRs let you build a chain of dependent changes — each PR targets the previous ticket's branch rather than main. This is useful when a feature spans multiple tickets, or when you want incremental review of a large change.

Creating a stack with `--on`

Pass --on <TICKET> to parsec start to create a worktree whose base is another ticket's branch.

stacked PR workflow

# Base ticket — targets main $ parsec start PROJ-100 ✓ Created worktree, base: main # Second ticket — stacks on PROJ-100 $ parsec start PROJ-101 --on PROJ-100 ✓ Created worktree, base: feature/PROJ-100 # Third in the chain $ parsec start PROJ-102 --on PROJ-101 ✓ Created worktree, base: feature/PROJ-101 # Visualize the stack $ parsec stack main └── feature/PROJ-100 PR #10 open └── feature/PROJ-101 PR #11 open └── feature/PROJ-102 PR #12 open

After merging a stacked PR

When the base PR in a stack is merged, the child PR's target becomes stale — it still points to the merged branch. Use parsec stack --sync to automatically re-target all stacked PRs to their correct new bases.

parsec stack --sync

# PROJ-100 was merged to main # Now re-target PROJ-101 to main $ parsec stack --sync ✓ PR #11 retargeted: feature/PROJ-100 → main ✓ Stack synchronized

ⓘ

Merge order matters

Always merge stacked PRs from the bottom of the stack upward — merge the base first, then parsec stack --sync, then merge the next PR. Skipping --sync results in child PRs targeting already-merged branches.

New Features

#

Recent additions to parsec that extend the workflow beyond worktree management into issue creation, release automation, and customizable hooks.

Issue creation with `parsec create`

Create issues directly from the terminal without leaving your workflow. Works with GitHub Issues and Jira. Use --start to immediately begin work on the new issue.

parsec create

# Create a GitHub issue $ parsec create --title "Fix login redirect" --label "bug" ✓ Created #145: Fix login redirect # Create and start working immediately $ parsec create --title "Add caching layer" --start ✓ Created #146: Add caching layer ✓ Created workspace at ~/myrepo.146 # For Jira with issue type $ parsec new-issue --title "API caching" --issue-type Story --project CL ✓ Created CL-42: API caching

Release workflow with `parsec release`

Automate the entire release process: merge develop to main, create a version tag, and publish a GitHub Release with auto-generated changelog — all in one command.

parsec release

$ parsec release 0.3.3 ✓ Merged develop → main ✓ Tagged v0.3.3 ✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.3 # Always preview first with --dry-run $ parsec release 0.4.0 --dry-run Would merge develop → main Would tag v0.4.0

Pre-ship hooks

Define commands that run automatically before parsec ship pushes your branch. Great for ensuring tests pass and linting is clean before creating a PR.

config.toml

# ~/.config/parsec/config.toml [hooks] post_create = ["npm install"] pre_ship = ["cargo test", "cargo clippy"] # Skip hooks when needed $ parsec ship PROJ-123 --skip-hooks

ⓘ

Release configuration

Customize the release workflow in your config file with [release] section: set the target branch, tag prefix, and whether to include a changelog.

Getting Started