Getting Started
++ Everything you need to go from zero to shipping PRs with parsec. Installation, configuration, and key workflows explained. +
+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. +
+ +Build from source
+
+ Clone the repository and build with cargo build --release. The compiled binary is at ./target/release/parsec.
+
Shell completions
++ Generate tab completions for your shell. Completions cover all commands and flags. +
+ +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. +
+ +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 callcd $(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.
+
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. +
+ +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
+ +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.
+
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" / "bitbucket" |
+
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) |
+
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. +
+ +JSON output for automation
+
+ Use --json on any command to get structured output suitable for piping into jq or a coordinator agent.
+
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.
+
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.
+
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.
+
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. +
+ +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.
+
Customize the release workflow in your config file with [release] section: set the target branch, tag prefix, and whether to include a changelog.
Recipes & Examples
+ # ++ End-to-end examples for the workflow patterns parsec is built around — Bitbucket Cloud setup, history compression, stacked PR navigation, PR templates, offline / headless mode, observability via JSONL, editor autocomplete via the JSON Schema, and worktree build cache sharing. Each recipe is self-contained — copy the snippets and adapt to your repo. +
+ +Bitbucket Cloud — full PR lifecycle
+
+ parsec now speaks Bitbucket Cloud's API: parsec ship opens PRs, parsec pr-status reports CI from Bitbucket Pipelines, parsec ci tails build status, and parsec merge merges from the terminal. Tracker integration uses the same tracker.bitbucket config block.
+
Compress branch history with parsec compress
+ + Squash a branch's commits into one tidy commit before shipping. Co-author trailers from squashed commits are preserved automatically. +
+ +Stack navigation comments
++ When you ship a stacked PR, parsec auto-posts "← previous PR" / "next PR →" navigation comments on every PR in the stack. Reviewers can walk the chain without leaving the PR view. +
+ +PR template auto-fill — ship --template
+
+ Use the repository's .github/PULL_REQUEST_TEMPLATE.md (or the first match under .github/PULL_REQUEST_TEMPLATE/) as the PR description automatically. Combine with ship.template in config.toml to make it the default.
+
Offline mode — --offline / [workspace].offline
+
+ Skip all network operations: tracker lookups, PR creation, fetches. Use a global --offline flag, the PARSEC_OFFLINE=1 env var, or set offline = true under [workspace] in config.toml. Per-command escapes (--no-pr, --no-tracker) remain available for finer control.
+
Observability — execution IDs + JSONL export
+
+ Every command run gets a unique execution ID and per-step timing. parsec log --export emits one JSON object per line for tooling and AI agents to consume. Combined with --json on individual commands, parsec is fully introspectable.
+
Config JSON Schema — editor autocomplete
+
+ The schema for config.toml is published to schemastore.org, so VS Code, IntelliJ, Helix, and any editor with schemastore integration auto-complete and validate every key. parsec config schema emits the schema for offline use.
+
Worktree build cache sharing — [worktree].shared_cache
+
+ New worktrees can reuse target/, node_modules/, .venv/, etc. from the main repo via symlink (default) or recursive copy. Eliminates cold-build cost on parsec start for any project with significant dependency caches.
+
Draft-by-default — ship.draft
+
+ Set [ship].draft = true in config.toml to open every PR as a draft, or pass --draft per ship. Useful for iterative WIP review flows where you want CI feedback before requesting human review.
+
+ 
+