| Name | par-cli JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | CLI for parallel development workflows with isolated Git worktrees and tmux sessions, tailored for agentic coding. |
| upload_time | 2025-07-21 05:03:58 |
| maintainer | None |
| docs_url | None |
| author | Victor |
| requires_python | >=3.12 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Par: Parallel Worktree & Session Manager
> **Easily manage parallel development workflows with isolated Git worktrees and tmux sessions**
`par` is a **global** command-line tool designed to simplify parallel development across any Git repositories on your system. It's specifically designed for working with AI coding assistants, background agents, or multiple development contexts simultaneously, `par` creates isolated workspaces that don't interfere with each other.
## Why Par?
Tools like OpenAI Codex, Claude Code, and other coding agents have made it easier to parallelize the work on multiple features, experiments, or problems simultaneously. However, traditional Git branch switching is not ideal for handling multiple concurrent workstreams on the same repository.
`par` solves this by creating **isolated development environments** for each task:
- **🔀 Git Worktrees**: Each session gets its own directory and branch
- **🖥️ Tmux Sessions**: Persistent terminal sessions where agents can run in the background
- **🏷️ Globally Unique Labels**: Easy-to-remember names that work across all repositories
- **🌍 Global Management**: Create, list, and manage sessions from anywhere on your system
- **📡 Remote Control**: Send commands to any or all sessions globally
- **👁️ Overview Mode**: Monitor all sessions simultaneously
- **🏢 Multi-Repo Workspaces**: Unified development across multiple repositories
- **🎨 IDE Integration**: Native VSCode/Cursor workspace support with auto-generated configs
https://github.com/user-attachments/assets/88eb4aed-c00d-4238-b1a9-bcaa34c975c3
## Key Features
### 🚀 **Quick Start**
```bash
# From within a git repository
par start feature-auth # Creates worktree, branch, and tmux session
# From anywhere on your system
par start bugfix-login --path /path/to/repo
par start experiment-ai --path ~/projects/my-app
```
### 📋 **Global Development Context Management**
```bash
par ls # List ALL sessions and workspaces globally
par open feature-auth # Switch to any session or workspace from anywhere
par rm bugfix-login # Clean up completed work globally
```
### 📡 **Global Remote Execution**
```bash
par send feature-auth "pnpm test" # Run tests in one session
par send all "git status" # Check status across ALL sessions globally
```
### 🎛️ **Global Control Center**
```bash
par control-center # View ALL sessions and workspaces globally with separate windows
```
### 🏢 **Multi-Repository Workspaces**
```bash
par workspace start feature-auth --repos frontend,backend
par workspace code feature-auth # Open in VSCode with multi-repo support
par workspace open feature-auth # Attach to unified tmux session
```
## Unified Development Context System
`par` provides a **unified interface** for managing both single-repository sessions and multi-repository workspaces. Whether you're working on a single feature branch or coordinating changes across multiple repositories, all your development contexts appear in one place.
### Two Development Modes:
- **Sessions**: Single-repo development with isolated branches (`par start`, `par checkout`)
- **Workspaces**: Multi-repo development with synchronized branches (`par workspace start`)
### Unified Commands:
- `par ls` - See all your development contexts (sessions + workspaces) in one table
- `par open <label>` - Switch to any session or workspace
- `par control-center` - View all contexts in separate tmux windows
- Tab completion works across both sessions and workspaces
This eliminates the need to remember which type of development context you're working with - just use the label and `par` handles the rest!
## Installation
### Prerequisites
- **Git** - Version control system
- **tmux** - Terminal multiplexer
- **Python 3.12+** - Runtime environment
- **uv** - Package manager (recommended)
### Install with uv
```bash
uv tool install par-cli
```
### Install with pip
```bash
pip install par-cli
```
### Install from Source
```bash
git clone https://github.com/coplane/par.git
cd par
uv tool install .
```
### Verify Installation
```bash
par --version
par --help
```
## Usage
### Starting a New Session
Create a new isolated development environment:
```bash
# From within a git repository
par start my-feature
# From anywhere, specifying the repository path
par start my-feature --path /path/to/your/git/repo
par start my-feature -p ~/projects/my-app
```
This creates:
- Git worktree at `~/.local/share/par/worktrees/<repo-hash>/my-feature/`
- Git branch named `my-feature`
- tmux session named `par-<repo>-<hash>-my-feature`
- **Globally unique session** accessible from anywhere
### Checking Out Existing Branches and PRs
Work with existing branches or review PRs without creating new branches:
```bash
# Checkout existing branch
par checkout existing-branch
# Checkout PR by number
par checkout pr/123
# Checkout PR by URL
par checkout https://github.com/owner/repo/pull/456
# Checkout remote branch from fork
par checkout alice:feature-branch
# Checkout with custom session label
par checkout develop --label dev-work
# Checkout from anywhere specifying repository path
par checkout feature-branch --path /path/to/repo
par checkout pr/123 --path ~/projects/my-app --label pr-review
```
**Supported formats:**
- `branch-name` - Local or origin branch
- `pr/123` - GitHub PR by number
- `https://github.com/owner/repo/pull/123` - GitHub PR by URL
- `username:branch` - Remote branch from fork
- `remote/branch` - Branch from specific remote
### Global Development Context Management
**List all sessions and workspaces globally:**
```bash
par ls # Shows ALL sessions and workspaces from anywhere
```
Shows all development contexts across all repositories in a unified table:
```
Par Development Contexts (Global)
┌────────────────┬───────────┬──────────────────┬──────────────┬─────────────────┬────────────┐
│ Label │ Type │ Repository/Work… │ Tmux Session │ Branch │ Created │
├────────────────┼───────────┼──────────────────┼──────────────┼─────────────────┼────────────┤
│ feature-auth │ Session │ my-app (proj…) │ par-myapp-… │ feature-auth │ 2025-07-19 │
│ fullstack │ Workspace │ workspace (2 re… │ par-ws-full… │ fullstack │ 2025-07-19 │
│ bugfix-123 │ Checkout │ other-repo (c…) │ par-other-… │ hotfix/bug-123 │ 2025-07-19 │
└────────────────┴───────────┴──────────────────┴──────────────┴─────────────────┴────────────┘
```
**Open any development context from anywhere:**
```bash
par open my-feature # Opens session
par open fullstack-auth # Opens workspace
```
**Remove completed work from anywhere:**
```bash
par rm my-feature # Remove specific session/workspace globally
par rm all # Remove ALL sessions and workspaces (with confirmation)
```
> **Note**: When removing checkout sessions, `par` only removes the worktree and tmux session. It does not delete the original branch since it wasn't created by `par`.
### Global Remote Command Execution
**Send commands to specific sessions :**
```bash
par send my-feature "npm install"
par send backend-work "python manage.py migrate"
par send workspace-name "git status" # Works for workspaces too
```
**Broadcast to ALL sessions and workspaces globally:**
```bash
par send all "git status" # Sends to every session everywhere
par send all "npm test" # Runs tests across all contexts
```
### Global Control Center
View ALL development contexts simultaneously with dedicated tmux windows:
```bash
par control-center # Works from anywhere, shows everything
```
Creates a unified `control-center` tmux session with separate windows for each development context (sessions and workspace repositories), giving you easy navigation across your entire development workflow.
> **Note**: Must be run from outside tmux. Creates a global control center session with dedicated windows for each context.
**Benefits of the windowed approach:**
- **Easy Navigation**: Use tmux window switching (`Ctrl-b + number` or `Ctrl-b + n/p`) to jump between contexts
- **Clean Organization**: Each development context gets its own dedicated window with a descriptive name
- **Scalable**: Works well with many sessions/workspaces (unlike tiled panes that become cramped)
- **Workspace Support**: For multi-repo workspaces, each repository gets its own window
### Automatic Initialization with .par.yaml
`par` can automatically run initialization commands when creating new worktrees. Simply add a `.par.yaml` file to your repository root:
```yaml
# .par.yaml
initialization:
include:
- .env
- config/*.json
commands:
- name: "Install frontend dependencies"
command: "cd frontend && pnpm install"
- name: "Setup environment file"
command: "cd frontend && cp .env.example .env"
- name: "Install backend dependencies"
command: "cd backend && uv sync"
# Simple string commands are also supported
- "echo 'Workspace initialized!'"
```
Files listed under `include` are copied from the repository root into each new worktree before any commands run. This lets you keep gitignored files like `.env` in the new environment.
All commands start from the worktree root directory. Use `cd <directory> &&` to run commands in subdirectories.
When you run `par start my-feature`, these commands will automatically execute in the new session's tmux environment.
## Multi-Repository Workspaces
For projects spanning multiple repositories (like frontend/backend splits or microservices), `par` provides **workspace** functionality that creates a single session managing multiple repositories together in a unified development environment.
### Why Workspaces?
When working on features that span multiple repositories, you typically need to:
- Create branches with the same name across repos
- Keep terminal sessions open for each repo
- Switch between repositories frequently
- Manage development servers for multiple services
Workspaces solve this by creating a **single global session** that starts from a unified workspace directory with access to all repositories, all sharing the same branch name.
### Quick Start
```bash
# From a directory containing multiple repos (auto-detection)
cd /path/to/my-project # contains frontend/, backend/, docs/
par workspace start feature-auth
# From anywhere, specifying repositories by absolute path
par workspace start feature-auth --repos /path/to/frontend,/path/to/backend
par workspace start feature-auth --path /workspace/root --repos frontend,backend
# Open in your preferred IDE with proper multi-repo support
par workspace code feature-auth # VSCode
par workspace cursor feature-auth # Cursor
```
### Workspace Commands
**Create a workspace:**
```bash
par workspace start <label> [--path /workspace/root] [--repos repo1,repo2] [--open]
```
**List workspaces (now unified with sessions):**
```bash
par ls # Shows workspaces alongside sessions
par workspace ls # Shows only workspaces (deprecated)
```
**Open workspace (now unified):**
```bash
par open <label> # Opens workspace session
par workspace code <label> # Open in VSCode
par workspace cursor <label> # Open in Cursor
```
**Remove workspace (now unified):**
```bash
par rm <label> # Remove workspace
par workspace rm <label> # Also works (delegates to global rm)
```
### How Workspaces Work
When you create a workspace, `par` automatically:
1. **Detects repositories** in the workspace directory (or uses `--repos` with absolute paths)
2. **Creates worktrees** for each repository with the same branch name
3. **Creates single global session** starting from unified workspace root with access to all repositories
4. **Generates IDE workspace files** for seamless editor integration
5. **Integrates with global par commands** - use `par ls`, `par open`, `par rm` etc.
**Example directory structure:**
```
# Original repositories anywhere on system:
my-fullstack-app/
├── frontend/ # React app
├── backend/ # Python API
└── docs/ # Documentation
# After: par workspace start user-auth --repos /home/user/projects/frontend,/home/user/projects/backend,/opt/company/docs
# Creates unified workspace at: ~/.local/share/par/workspaces/.../user-auth/
├── frontend/
├── backend/
├── docs/
└── user-auth.code-workspace
# Single tmux session starts from workspace root
# Navigate with: cd frontend/, cd backend/, cd docs/
# Global session accessible via: par open user-auth
```
### IDE Integration
Workspaces include first-class IDE support that solves the common problem of multi-repo development in editors.
**VSCode Integration:**
```bash
par workspace code user-auth
```
This generates and opens a `.code-workspace` file containing:
```json
{
"folders": [
{
"name": "frontend (user-auth)",
"path": "/path/to/worktrees/frontend/user-auth"
},
{
"name": "backend (user-auth)",
"path": "/path/to/worktrees/backend/user-auth"
}
],
"settings": {
"git.detectSubmodules": false,
"git.repositoryScanMaxDepth": 1
}
}
```
**Benefits:**
- Each repository appears as a separate folder in the explorer
- Git operations work correctly for each repository
- All repositories are on the correct feature branch
- No worktree plugin configuration needed
### Repository Specification
**Auto-detection (recommended):**
```bash
par workspace start feature-name
# Automatically finds all git repositories in current directory
```
**Explicit specification:**
```bash
par workspace start feature-name --repos frontend,backend,shared
# Only includes specified repositories
```
**Comma-separated syntax:**
```bash
--repos repo1,repo2,repo3
--repos "frontend, backend, docs" # Spaces are trimmed
```
### Workspace Organization
Workspaces are organized separately from single-repo sessions:
```
~/.local/share/par/
├── worktrees/ # Single-repo sessions
│ └── <repo-hash>/
└── workspaces/ # Multi-repo workspaces
└── <workspace-hash>/
└── <workspace-label>/
├── frontend/
│ └── feature-auth/ # Worktree
├── backend/
│ └── feature-auth/ # Worktree
└── feature-auth.code-workspace
```
### Workspace Initialization
Workspaces support the same `.par.yaml` initialization as single repositories. When you create a workspace, `par` runs the initialization commands from each repository's `.par.yaml` file in their respective worktrees.
For example, if both `frontend` and `backend` repositories have their own `.par.yaml` files:
```yaml
# frontend/.par.yaml
initialization:
commands:
- name: "Install dependencies"
command: "pnpm install"
- name: "Setup environment"
command: "cp .env.example .env"
# backend/.par.yaml
initialization:
commands:
- name: "Install dependencies"
command: "uv sync"
- name: "Run migrations"
command: "python manage.py migrate"
```
Each repository's initialization runs in its own worktree, ensuring proper isolation and consistent behavior.
### Example Workflows
**Full-stack feature development:**
```bash
# 1. Start workspace for new feature
par workspace start user-profiles --repos /path/to/frontend,/path/to/backend
# 2. Open in IDE with proper multi-repo support
par workspace code user-profiles
# 3. Open unified session
par open user-profiles
# 4. Work across repositories from single terminal
cd frontend/ # Switch to frontend worktree
cd ../backend/ # Switch to backend worktree
claude # Run Claude from workspace root to see all repos
# 5. Global management
par ls # See all sessions including workspaces
par send user-profiles "git status" # Send commands globally
# 6. Clean up when feature is complete
par rm user-profiles
```
**Microservices development:**
```bash
# Work on API changes affecting multiple services
par workspace start api-v2 --repos /srv/auth-service,/srv/user-service,/srv/gateway
# All services get api-v2 branch
# Single global session accessible from anywhere
# IDE workspace shows all services together
# Navigate: cd auth-service/, cd user-service/, etc.
# Global commands: par send api-v2 "docker-compose up"
```
### Branch Creation
Workspaces create branches from the **currently checked out branch** in each repository, not necessarily from `main`. This allows for:
- **Feature branches from develop**: If repos are on `develop`, workspace branches from `develop`
- **Different base branches**: Each repo can be on different branches before workspace creation
- **Flexible workflows**: Supports GitFlow, GitHub Flow, or custom branching strategies
## Advanced Usage
### Globally Unique Sessions
`par` enforces globally unique session labels across all repositories. This ensures you can manage sessions from anywhere without conflicts:
```bash
# All sessions must have unique labels globally
par start feature-auth --path ~/project-a # Creates feature-auth session
par start feature-auth --path ~/project-b # ❌ Error: label already exists
par start feature-auth-v2 --path ~/project-b # ✅ Works with unique label
# Access any session from anywhere
par open feature-auth # Works from any directory
par ls # Shows all sessions globally
```
## Configuration
### Data Directory
Par stores its data in `~/.local/share/par/` (or `$XDG_DATA_HOME/par/`):
```
~/.local/share/par/
├── global_state.json # Global session and workspace metadata
├── worktrees/ # Single-repo sessions organized by repo hash
│ └── <repo-hash>/
│ ├── feature-1/ # Individual worktrees
│ ├── feature-2/
│ └── experiment-1/
└── workspaces/ # Multi-repo workspaces
└── <workspace-hash>/
└── <workspace-label>/
├── frontend/
│ └── feature-auth/ # Worktree
├── backend/
│ └── feature-auth/ # Worktree
└── feature-auth.code-workspace
```
### Session Naming Convention
tmux sessions follow the pattern: `par-<repo-name>-<repo-hash>-<label>`
Example: `par-myproject-a1b2c3d4-feature-auth`
### Cleaning Up
Remove all par-managed resources globally:
```bash
par rm all # Removes ALL sessions and workspaces everywhere
```
Remove specific stale sessions:
```bash
par rm old-feature-name
```
Raw data
{
"_id": null,
"home_page": null,
"name": "par-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Victor",
"author_email": "Victor <vimota@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/08/07/2ba47c1bdeacbb1dbefab930631f8873fc6ff0c1d222cc3e2c339700fd39/par_cli-0.2.0.tar.gz",
"platform": null,
"description": "# Par: Parallel Worktree & Session Manager\n\n> **Easily manage parallel development workflows with isolated Git worktrees and tmux sessions**\n\n`par` is a **global** command-line tool designed to simplify parallel development across any Git repositories on your system. It's specifically designed for working with AI coding assistants, background agents, or multiple development contexts simultaneously, `par` creates isolated workspaces that don't interfere with each other.\n\n## Why Par?\n\nTools like OpenAI Codex, Claude Code, and other coding agents have made it easier to parallelize the work on multiple features, experiments, or problems simultaneously. However, traditional Git branch switching is not ideal for handling multiple concurrent workstreams on the same repository.\n\n`par` solves this by creating **isolated development environments** for each task:\n\n- **\ud83d\udd00 Git Worktrees**: Each session gets its own directory and branch\n- **\ud83d\udda5\ufe0f Tmux Sessions**: Persistent terminal sessions where agents can run in the background\n- **\ud83c\udff7\ufe0f Globally Unique Labels**: Easy-to-remember names that work across all repositories\n- **\ud83c\udf0d Global Management**: Create, list, and manage sessions from anywhere on your system\n- **\ud83d\udce1 Remote Control**: Send commands to any or all sessions globally\n- **\ud83d\udc41\ufe0f Overview Mode**: Monitor all sessions simultaneously\n- **\ud83c\udfe2 Multi-Repo Workspaces**: Unified development across multiple repositories\n- **\ud83c\udfa8 IDE Integration**: Native VSCode/Cursor workspace support with auto-generated configs\n\nhttps://github.com/user-attachments/assets/88eb4aed-c00d-4238-b1a9-bcaa34c975c3\n\n## Key Features\n\n### \ud83d\ude80 **Quick Start**\n\n```bash\n# From within a git repository\npar start feature-auth # Creates worktree, branch, and tmux session\n\n# From anywhere on your system\npar start bugfix-login --path /path/to/repo\npar start experiment-ai --path ~/projects/my-app\n```\n\n### \ud83d\udccb **Global Development Context Management**\n\n```bash\npar ls # List ALL sessions and workspaces globally\npar open feature-auth # Switch to any session or workspace from anywhere\npar rm bugfix-login # Clean up completed work globally\n```\n\n### \ud83d\udce1 **Global Remote Execution**\n\n```bash\npar send feature-auth \"pnpm test\" # Run tests in one session\npar send all \"git status\" # Check status across ALL sessions globally\n```\n\n### \ud83c\udf9b\ufe0f **Global Control Center**\n\n```bash\npar control-center # View ALL sessions and workspaces globally with separate windows\n```\n\n### \ud83c\udfe2 **Multi-Repository Workspaces**\n\n```bash\npar workspace start feature-auth --repos frontend,backend\npar workspace code feature-auth # Open in VSCode with multi-repo support\npar workspace open feature-auth # Attach to unified tmux session\n```\n\n## Unified Development Context System\n\n`par` provides a **unified interface** for managing both single-repository sessions and multi-repository workspaces. Whether you're working on a single feature branch or coordinating changes across multiple repositories, all your development contexts appear in one place.\n\n### Two Development Modes:\n\n- **Sessions**: Single-repo development with isolated branches (`par start`, `par checkout`)\n- **Workspaces**: Multi-repo development with synchronized branches (`par workspace start`)\n\n### Unified Commands:\n\n- `par ls` - See all your development contexts (sessions + workspaces) in one table\n- `par open <label>` - Switch to any session or workspace\n- `par control-center` - View all contexts in separate tmux windows\n- Tab completion works across both sessions and workspaces\n\nThis eliminates the need to remember which type of development context you're working with - just use the label and `par` handles the rest!\n\n## Installation\n\n### Prerequisites\n\n- **Git** - Version control system\n- **tmux** - Terminal multiplexer\n- **Python 3.12+** - Runtime environment\n- **uv** - Package manager (recommended)\n\n### Install with uv\n\n```bash\nuv tool install par-cli\n```\n\n### Install with pip\n\n```bash\npip install par-cli\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/coplane/par.git\ncd par\nuv tool install .\n```\n\n### Verify Installation\n\n```bash\npar --version\npar --help\n```\n\n## Usage\n\n### Starting a New Session\n\nCreate a new isolated development environment:\n\n```bash\n# From within a git repository\npar start my-feature\n\n# From anywhere, specifying the repository path\npar start my-feature --path /path/to/your/git/repo\npar start my-feature -p ~/projects/my-app\n```\n\nThis creates:\n\n- Git worktree at `~/.local/share/par/worktrees/<repo-hash>/my-feature/`\n- Git branch named `my-feature`\n- tmux session named `par-<repo>-<hash>-my-feature`\n- **Globally unique session** accessible from anywhere\n\n### Checking Out Existing Branches and PRs\n\nWork with existing branches or review PRs without creating new branches:\n\n```bash\n# Checkout existing branch\npar checkout existing-branch\n\n# Checkout PR by number\npar checkout pr/123\n\n# Checkout PR by URL\npar checkout https://github.com/owner/repo/pull/456\n\n# Checkout remote branch from fork\npar checkout alice:feature-branch\n\n# Checkout with custom session label\npar checkout develop --label dev-work\n\n# Checkout from anywhere specifying repository path\npar checkout feature-branch --path /path/to/repo\npar checkout pr/123 --path ~/projects/my-app --label pr-review\n```\n\n**Supported formats:**\n\n- `branch-name` - Local or origin branch\n- `pr/123` - GitHub PR by number\n- `https://github.com/owner/repo/pull/123` - GitHub PR by URL\n- `username:branch` - Remote branch from fork\n- `remote/branch` - Branch from specific remote\n\n### Global Development Context Management\n\n**List all sessions and workspaces globally:**\n\n```bash\npar ls # Shows ALL sessions and workspaces from anywhere\n```\n\nShows all development contexts across all repositories in a unified table:\n\n```\nPar Development Contexts (Global)\n\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Label \u2502 Type \u2502 Repository/Work\u2026 \u2502 Tmux Session \u2502 Branch \u2502 Created \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 feature-auth \u2502 Session \u2502 my-app (proj\u2026) \u2502 par-myapp-\u2026 \u2502 feature-auth \u2502 2025-07-19 \u2502\n\u2502 fullstack \u2502 Workspace \u2502 workspace (2 re\u2026 \u2502 par-ws-full\u2026 \u2502 fullstack \u2502 2025-07-19 \u2502\n\u2502 bugfix-123 \u2502 Checkout \u2502 other-repo (c\u2026) \u2502 par-other-\u2026 \u2502 hotfix/bug-123 \u2502 2025-07-19 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Open any development context from anywhere:**\n\n```bash\npar open my-feature # Opens session\npar open fullstack-auth # Opens workspace\n```\n\n**Remove completed work from anywhere:**\n\n```bash\npar rm my-feature # Remove specific session/workspace globally\npar rm all # Remove ALL sessions and workspaces (with confirmation)\n```\n\n> **Note**: When removing checkout sessions, `par` only removes the worktree and tmux session. It does not delete the original branch since it wasn't created by `par`.\n\n### Global Remote Command Execution\n\n**Send commands to specific sessions :**\n\n```bash\npar send my-feature \"npm install\"\npar send backend-work \"python manage.py migrate\"\npar send workspace-name \"git status\" # Works for workspaces too\n```\n\n**Broadcast to ALL sessions and workspaces globally:**\n\n```bash\npar send all \"git status\" # Sends to every session everywhere\npar send all \"npm test\" # Runs tests across all contexts\n```\n\n### Global Control Center\n\nView ALL development contexts simultaneously with dedicated tmux windows:\n\n```bash\npar control-center # Works from anywhere, shows everything\n```\n\nCreates a unified `control-center` tmux session with separate windows for each development context (sessions and workspace repositories), giving you easy navigation across your entire development workflow.\n\n> **Note**: Must be run from outside tmux. Creates a global control center session with dedicated windows for each context.\n\n**Benefits of the windowed approach:**\n- **Easy Navigation**: Use tmux window switching (`Ctrl-b + number` or `Ctrl-b + n/p`) to jump between contexts\n- **Clean Organization**: Each development context gets its own dedicated window with a descriptive name\n- **Scalable**: Works well with many sessions/workspaces (unlike tiled panes that become cramped)\n- **Workspace Support**: For multi-repo workspaces, each repository gets its own window\n\n### Automatic Initialization with .par.yaml\n\n`par` can automatically run initialization commands when creating new worktrees. Simply add a `.par.yaml` file to your repository root:\n\n```yaml\n# .par.yaml\ninitialization:\n include:\n - .env\n - config/*.json\n commands:\n - name: \"Install frontend dependencies\"\n command: \"cd frontend && pnpm install\"\n\n - name: \"Setup environment file\"\n command: \"cd frontend && cp .env.example .env\"\n\n - name: \"Install backend dependencies\"\n command: \"cd backend && uv sync\"\n\n # Simple string commands are also supported\n - \"echo 'Workspace initialized!'\"\n```\n\nFiles listed under `include` are copied from the repository root into each new worktree before any commands run. This lets you keep gitignored files like `.env` in the new environment.\n\nAll commands start from the worktree root directory. Use `cd <directory> &&` to run commands in subdirectories.\n\nWhen you run `par start my-feature`, these commands will automatically execute in the new session's tmux environment.\n\n## Multi-Repository Workspaces\n\nFor projects spanning multiple repositories (like frontend/backend splits or microservices), `par` provides **workspace** functionality that creates a single session managing multiple repositories together in a unified development environment.\n\n### Why Workspaces?\n\nWhen working on features that span multiple repositories, you typically need to:\n\n- Create branches with the same name across repos\n- Keep terminal sessions open for each repo\n- Switch between repositories frequently\n- Manage development servers for multiple services\n\nWorkspaces solve this by creating a **single global session** that starts from a unified workspace directory with access to all repositories, all sharing the same branch name.\n\n### Quick Start\n\n```bash\n# From a directory containing multiple repos (auto-detection)\ncd /path/to/my-project # contains frontend/, backend/, docs/\npar workspace start feature-auth\n\n# From anywhere, specifying repositories by absolute path\npar workspace start feature-auth --repos /path/to/frontend,/path/to/backend\npar workspace start feature-auth --path /workspace/root --repos frontend,backend\n\n# Open in your preferred IDE with proper multi-repo support\npar workspace code feature-auth # VSCode\npar workspace cursor feature-auth # Cursor\n```\n\n### Workspace Commands\n\n**Create a workspace:**\n\n```bash\npar workspace start <label> [--path /workspace/root] [--repos repo1,repo2] [--open]\n```\n\n**List workspaces (now unified with sessions):**\n\n```bash\npar ls # Shows workspaces alongside sessions\npar workspace ls # Shows only workspaces (deprecated)\n```\n\n**Open workspace (now unified):**\n\n```bash\npar open <label> # Opens workspace session\npar workspace code <label> # Open in VSCode\npar workspace cursor <label> # Open in Cursor\n```\n\n**Remove workspace (now unified):**\n\n```bash\npar rm <label> # Remove workspace\npar workspace rm <label> # Also works (delegates to global rm)\n```\n\n### How Workspaces Work\n\nWhen you create a workspace, `par` automatically:\n\n1. **Detects repositories** in the workspace directory (or uses `--repos` with absolute paths)\n2. **Creates worktrees** for each repository with the same branch name\n3. **Creates single global session** starting from unified workspace root with access to all repositories\n4. **Generates IDE workspace files** for seamless editor integration\n5. **Integrates with global par commands** - use `par ls`, `par open`, `par rm` etc.\n\n**Example directory structure:**\n\n```\n# Original repositories anywhere on system:\nmy-fullstack-app/\n\u251c\u2500\u2500 frontend/ # React app\n\u251c\u2500\u2500 backend/ # Python API\n\u2514\u2500\u2500 docs/ # Documentation\n\n# After: par workspace start user-auth --repos /home/user/projects/frontend,/home/user/projects/backend,/opt/company/docs\n# Creates unified workspace at: ~/.local/share/par/workspaces/.../user-auth/\n\u251c\u2500\u2500 frontend/\n\u251c\u2500\u2500 backend/\n\u251c\u2500\u2500 docs/\n\u2514\u2500\u2500 user-auth.code-workspace\n\n# Single tmux session starts from workspace root\n# Navigate with: cd frontend/, cd backend/, cd docs/\n# Global session accessible via: par open user-auth\n```\n\n### IDE Integration\n\nWorkspaces include first-class IDE support that solves the common problem of multi-repo development in editors.\n\n**VSCode Integration:**\n\n```bash\npar workspace code user-auth\n```\n\nThis generates and opens a `.code-workspace` file containing:\n\n```json\n{\n \"folders\": [\n {\n \"name\": \"frontend (user-auth)\",\n \"path\": \"/path/to/worktrees/frontend/user-auth\"\n },\n {\n \"name\": \"backend (user-auth)\",\n \"path\": \"/path/to/worktrees/backend/user-auth\"\n }\n ],\n \"settings\": {\n \"git.detectSubmodules\": false,\n \"git.repositoryScanMaxDepth\": 1\n }\n}\n```\n\n**Benefits:**\n\n- Each repository appears as a separate folder in the explorer\n- Git operations work correctly for each repository\n- All repositories are on the correct feature branch\n- No worktree plugin configuration needed\n\n### Repository Specification\n\n**Auto-detection (recommended):**\n\n```bash\npar workspace start feature-name\n# Automatically finds all git repositories in current directory\n```\n\n**Explicit specification:**\n\n```bash\npar workspace start feature-name --repos frontend,backend,shared\n# Only includes specified repositories\n```\n\n**Comma-separated syntax:**\n\n```bash\n--repos repo1,repo2,repo3\n--repos \"frontend, backend, docs\" # Spaces are trimmed\n```\n\n### Workspace Organization\n\nWorkspaces are organized separately from single-repo sessions:\n\n```\n~/.local/share/par/\n\u251c\u2500\u2500 worktrees/ # Single-repo sessions\n\u2502 \u2514\u2500\u2500 <repo-hash>/\n\u2514\u2500\u2500 workspaces/ # Multi-repo workspaces\n \u2514\u2500\u2500 <workspace-hash>/\n \u2514\u2500\u2500 <workspace-label>/\n \u251c\u2500\u2500 frontend/\n \u2502 \u2514\u2500\u2500 feature-auth/ # Worktree\n \u251c\u2500\u2500 backend/\n \u2502 \u2514\u2500\u2500 feature-auth/ # Worktree\n \u2514\u2500\u2500 feature-auth.code-workspace\n```\n\n### Workspace Initialization\n\nWorkspaces support the same `.par.yaml` initialization as single repositories. When you create a workspace, `par` runs the initialization commands from each repository's `.par.yaml` file in their respective worktrees.\n\nFor example, if both `frontend` and `backend` repositories have their own `.par.yaml` files:\n\n```yaml\n# frontend/.par.yaml\ninitialization:\n commands:\n - name: \"Install dependencies\"\n command: \"pnpm install\"\n - name: \"Setup environment\"\n command: \"cp .env.example .env\"\n\n# backend/.par.yaml\ninitialization:\n commands:\n - name: \"Install dependencies\"\n command: \"uv sync\"\n - name: \"Run migrations\"\n command: \"python manage.py migrate\"\n```\n\nEach repository's initialization runs in its own worktree, ensuring proper isolation and consistent behavior.\n\n### Example Workflows\n\n**Full-stack feature development:**\n\n```bash\n# 1. Start workspace for new feature\npar workspace start user-profiles --repos /path/to/frontend,/path/to/backend\n\n# 2. Open in IDE with proper multi-repo support\npar workspace code user-profiles\n\n# 3. Open unified session\npar open user-profiles\n\n# 4. Work across repositories from single terminal\ncd frontend/ # Switch to frontend worktree\ncd ../backend/ # Switch to backend worktree\nclaude # Run Claude from workspace root to see all repos\n\n# 5. Global management\npar ls # See all sessions including workspaces\npar send user-profiles \"git status\" # Send commands globally\n\n# 6. Clean up when feature is complete\npar rm user-profiles\n```\n\n**Microservices development:**\n\n```bash\n# Work on API changes affecting multiple services\npar workspace start api-v2 --repos /srv/auth-service,/srv/user-service,/srv/gateway\n\n# All services get api-v2 branch\n# Single global session accessible from anywhere\n# IDE workspace shows all services together\n# Navigate: cd auth-service/, cd user-service/, etc.\n# Global commands: par send api-v2 \"docker-compose up\"\n```\n\n### Branch Creation\n\nWorkspaces create branches from the **currently checked out branch** in each repository, not necessarily from `main`. This allows for:\n\n- **Feature branches from develop**: If repos are on `develop`, workspace branches from `develop`\n- **Different base branches**: Each repo can be on different branches before workspace creation\n- **Flexible workflows**: Supports GitFlow, GitHub Flow, or custom branching strategies\n\n## Advanced Usage\n\n### Globally Unique Sessions\n\n`par` enforces globally unique session labels across all repositories. This ensures you can manage sessions from anywhere without conflicts:\n\n```bash\n# All sessions must have unique labels globally\npar start feature-auth --path ~/project-a # Creates feature-auth session\npar start feature-auth --path ~/project-b # \u274c Error: label already exists\npar start feature-auth-v2 --path ~/project-b # \u2705 Works with unique label\n\n# Access any session from anywhere\npar open feature-auth # Works from any directory\npar ls # Shows all sessions globally\n```\n\n## Configuration\n\n### Data Directory\n\nPar stores its data in `~/.local/share/par/` (or `$XDG_DATA_HOME/par/`):\n\n```\n~/.local/share/par/\n\u251c\u2500\u2500 global_state.json # Global session and workspace metadata\n\u251c\u2500\u2500 worktrees/ # Single-repo sessions organized by repo hash\n\u2502 \u2514\u2500\u2500 <repo-hash>/\n\u2502 \u251c\u2500\u2500 feature-1/ # Individual worktrees\n\u2502 \u251c\u2500\u2500 feature-2/\n\u2502 \u2514\u2500\u2500 experiment-1/\n\u2514\u2500\u2500 workspaces/ # Multi-repo workspaces\n \u2514\u2500\u2500 <workspace-hash>/\n \u2514\u2500\u2500 <workspace-label>/\n \u251c\u2500\u2500 frontend/\n \u2502 \u2514\u2500\u2500 feature-auth/ # Worktree\n \u251c\u2500\u2500 backend/\n \u2502 \u2514\u2500\u2500 feature-auth/ # Worktree\n \u2514\u2500\u2500 feature-auth.code-workspace\n```\n\n### Session Naming Convention\n\ntmux sessions follow the pattern: `par-<repo-name>-<repo-hash>-<label>`\n\nExample: `par-myproject-a1b2c3d4-feature-auth`\n\n### Cleaning Up\n\nRemove all par-managed resources globally:\n\n```bash\npar rm all # Removes ALL sessions and workspaces everywhere\n```\n\nRemove specific stale sessions:\n\n```bash\npar rm old-feature-name\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI for parallel development workflows with isolated Git worktrees and tmux sessions, tailored for agentic coding.",
"version": "0.2.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "772ffda18d1ce4d3e734f44380be13baa18537b4d2f96a799198ad0c6ddf04dc",
"md5": "f2365afc024e59ff664cccde7f3d38ac",
"sha256": "722f78fdf7d84840dcea06b5402a4c1ae2e8989fe035be33a66e8dfe6369bac3"
},
"downloads": -1,
"filename": "par_cli-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2365afc024e59ff664cccde7f3d38ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 28146,
"upload_time": "2025-07-21T05:03:57",
"upload_time_iso_8601": "2025-07-21T05:03:57.486249Z",
"url": "https://files.pythonhosted.org/packages/77/2f/fda18d1ce4d3e734f44380be13baa18537b4d2f96a799198ad0c6ddf04dc/par_cli-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "08072ba47c1bdeacbb1dbefab930631f8873fc6ff0c1d222cc3e2c339700fd39",
"md5": "8f1ce0fdff109ed76c03b7ff54d80eec",
"sha256": "2f510c27860b5d5f551291dae319ce596f3411ef5b3e6dd050f36f4b74bb117c"
},
"downloads": -1,
"filename": "par_cli-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8f1ce0fdff109ed76c03b7ff54d80eec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 23483,
"upload_time": "2025-07-21T05:03:58",
"upload_time_iso_8601": "2025-07-21T05:03:58.649489Z",
"url": "https://files.pythonhosted.org/packages/08/07/2ba47c1bdeacbb1dbefab930631f8873fc6ff0c1d222cc3e2c339700fd39/par_cli-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 05:03:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "par-cli"
}
