| Name | par-cli JSON |
| Version |
0.1.2
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-13 05:14:43 |
| 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 command-line tool designed to simplify parallel development within a single Git repository. 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
- **🏷️ Simple Labels**: Easy-to-remember names for each session
- **📡 Remote Control**: Send commands to any or all sessions
- **👁️ 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
par start feature-auth # Creates worktree, branch, and tmux session
par start bugfix-login # Another isolated session
par start experiment-ai # Yet another session
```
### 📋 **Unified Development Context Management**
```bash
par ls # List all sessions AND workspaces in one view
par open feature-auth # Switch to any session or workspace
par rm bugfix-login # Clean up completed work
```
### 📡 **Remote Execution**
```bash
par send feature-auth "pnpm test" # Run tests in one session
par send all "git status" # Check status across all sessions
```
### 🎛️ **Control Center**
```bash
par control-center # View all sessions AND workspaces in a tiled layout
```
### 🏢 **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 a tiled tmux layout
- 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 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
cd /path/to/your/git/repo
par start my-feature
```
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`
### 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
```
**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
### Managing Development Contexts
**List all sessions and workspaces:**
```bash
par ls
```
Shows both single-repo sessions and multi-repo workspaces in a unified table:
```
Par Development Contexts for coplane:
┌────────────────┬───────────┬──────────────────┬──────────────┬─────────────────┬────────────┐
│ Label │ Type │ Tmux Session │ Branch │ Other Repos │ Created │
├────────────────┼───────────┼──────────────────┼──────────────┼─────────────────┼────────────┤
│ feature-auth │ Session │ par-coplane-... │ feature-auth │ - │ 2025-06-07 │
│ fullstack-auth │ Workspace │ par-ws-coplane.. │ fullstack-auth│ planar │ 2025-06-05 │
└────────────────┴───────────┴──────────────────┴──────────────┴─────────────────┴────────────┘
```
**Open any development context:**
```bash
par open my-feature # Opens single-repo session
par open fullstack-auth # Opens multi-repo workspace
```
**Remove completed work:**
```bash
par rm my-feature # Remove specific session/workspace
par rm all # Remove all sessions (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`.
### 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 docs-update "mkdocs serve"
```
**Broadcast to all sessions:**
```bash
par send all "git status"
par send all "npm test"
```
### Control Center
View all development contexts simultaneously in a tiled tmux layout:
```bash
par control-center
```
Shows both single-repo sessions and multi-repo workspaces in separate panes, giving you a unified overview of all your active development work.
> **Note**: Must be run from outside tmux. Creates a new session and attaches to each context in its own pane.
### 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 manages 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 tmux session with dedicated panes for each repository, all sharing the same branch name.
### Quick Start
```bash
# Navigate to directory containing multiple repos
cd /path/to/my-project # contains frontend/, backend/, docs/
# Start workspace with auto-detection
par workspace start feature-auth
# Or specify repositories explicitly
par workspace start feature-auth --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> [--repos repo1,repo2] [--open]
```
**List workspaces:**
```bash
par workspace ls
```
**Open workspace:**
```bash
par workspace open <label> # Attach to tmux session
par workspace code <label> # Open in VSCode
par workspace cursor <label> # Open in Cursor
```
**Remove workspace:**
```bash
par workspace rm <label> # Remove specific workspace
par workspace rm all # Remove all workspaces
```
### How Workspaces Work
When you create a workspace, `par` automatically:
1. **Detects repositories** in the current directory (or uses `--repos`)
2. **Creates worktrees** for each repository with the same branch name
3. **Creates tmux session** in the workspace root directory with access to all repositories
4. **Generates IDE workspace files** for seamless editor integration
**Example directory structure:**
```
my-fullstack-app/
├── frontend/ # React app
├── backend/ # Python API
└── docs/ # Documentation
# After: par workspace start user-auth
# Creates branches: user-auth in all three repos
# Creates single tmux session in workspace root
# Can access all repositories with: cd frontend/, cd backend/, cd docs/
```
### 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
cd my-app/
par workspace start user-profiles --repos frontend,backend
# 2. Open in IDE with proper multi-repo support
par workspace code user-profiles
# 3. Open tmux session in workspace root
par workspace 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. Clean up when feature is complete
par workspace rm user-profiles
```
**Microservices development:**
```bash
# Work on API changes affecting multiple services
par workspace start api-v2 --repos auth-service,user-service,gateway
# All services get api-v2 branch
# Single tmux session in workspace root
# IDE workspace shows all services together
# Navigate between services: cd auth-service/, cd user-service/, etc.
```
### 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
### Repository-Scoped Sessions
`par` automatically scopes sessions to the current Git repository. You can use the same labels across different projects without conflicts:
```bash
cd ~/project-a
par start feature-auth # Creates project-a/feature-auth
cd ~/project-b
par start feature-auth # Creates separate project-b/feature-auth
```
## Configuration
### Data Directory
Par stores its data in `~/.local/share/par/` (or `$XDG_DATA_HOME/par/`):
```
~/.local/share/par/
├── state.json # Session metadata
└── worktrees/ # Git worktrees organized by repo
└── <repo-hash>/
├── feature-1/ # Individual workspaces
├── feature-2/
└── experiment-1/
```
### 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 for the current repository:
```bash
par rm all
```
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/1c/8b/0b3e25001b0db4a1eb55e134f5d710a952bddb7cf0a0d47e5026cb7acbd9/par_cli-0.1.2.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 command-line tool designed to simplify parallel development within a single Git repository. 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 Simple Labels**: Easy-to-remember names for each session\n- **\ud83d\udce1 Remote Control**: Send commands to any or all sessions\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\n\n## Key Features\n\n### \ud83d\ude80 **Quick Start**\n```bash\npar start feature-auth # Creates worktree, branch, and tmux session\npar start bugfix-login # Another isolated session\npar start experiment-ai # Yet another session\n```\n\n### \ud83d\udccb **Unified Development Context Management**\n```bash\npar ls # List all sessions AND workspaces in one view\npar open feature-auth # Switch to any session or workspace\npar rm bugfix-login # Clean up completed work\n```\n\n### \ud83d\udce1 **Remote Execution** \n```bash\npar send feature-auth \"pnpm test\" # Run tests in one session\npar send all \"git status\" # Check status across all sessions\n```\n\n### \ud83c\udf9b\ufe0f **Control Center**\n```bash\npar control-center # View all sessions AND workspaces in a tiled layout\n```\n\n### \ud83c\udfe2 **Multi-Repository Workspaces**\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- **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- `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 a tiled tmux layout\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- **Git** - Version control system\n- **tmux** - Terminal multiplexer \n- **Python 3.12+** - Runtime environment\n- **uv** - Package manager (recommended)\n\n### Install from Source\n```bash\ngit clone https://github.com/coplane/par.git\ncd par\nuv tool install .\n```\n\n### Verify Installation\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\ncd /path/to/your/git/repo\npar start my-feature\n```\n\nThis creates:\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\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\n**Supported formats:**\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### Managing Development Contexts\n\n**List all sessions and workspaces:**\n```bash\npar ls\n```\n\nShows both single-repo sessions and multi-repo workspaces in a unified table:\n\n```\nPar Development Contexts for coplane:\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 Tmux Session \u2502 Branch \u2502 Other Repos \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 par-coplane-... \u2502 feature-auth \u2502 - \u2502 2025-06-07 \u2502\n\u2502 fullstack-auth \u2502 Workspace \u2502 par-ws-coplane.. \u2502 fullstack-auth\u2502 planar \u2502 2025-06-05 \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:**\n```bash\npar open my-feature # Opens single-repo session\npar open fullstack-auth # Opens multi-repo workspace\n```\n\n**Remove completed work:**\n```bash\npar rm my-feature # Remove specific session/workspace\npar rm all # Remove all sessions (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### Remote Command Execution\n\n**Send commands to specific sessions:**\n```bash\npar send my-feature \"npm install\"\npar send backend-work \"python manage.py migrate\"\npar send docs-update \"mkdocs serve\"\n```\n\n**Broadcast to all sessions:**\n```bash\npar send all \"git status\"\npar send all \"npm test\"\n```\n\n### Control Center\n\nView all development contexts simultaneously in a tiled tmux layout:\n\n```bash\npar control-center\n```\n\nShows both single-repo sessions and multi-repo workspaces in separate panes, giving you a unified overview of all your active development work.\n\n> **Note**: Must be run from outside tmux. Creates a new session and attaches to each context in its own pane.\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 manages 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- 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 tmux session with dedicated panes for each repository, all sharing the same branch name.\n\n### Quick Start\n\n```bash\n# Navigate to directory containing multiple repos\ncd /path/to/my-project # contains frontend/, backend/, docs/\n\n# Start workspace with auto-detection\npar workspace start feature-auth\n\n# Or specify repositories explicitly\npar workspace start feature-auth --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```bash\npar workspace start <label> [--repos repo1,repo2] [--open]\n```\n\n**List workspaces:**\n```bash\npar workspace ls\n```\n\n**Open workspace:**\n```bash\npar workspace open <label> # Attach to tmux session\npar workspace code <label> # Open in VSCode \npar workspace cursor <label> # Open in Cursor\n```\n\n**Remove workspace:**\n```bash\npar workspace rm <label> # Remove specific workspace\npar workspace rm all # Remove all workspaces\n```\n\n### How Workspaces Work\n\nWhen you create a workspace, `par` automatically:\n\n1. **Detects repositories** in the current directory (or uses `--repos`)\n2. **Creates worktrees** for each repository with the same branch name\n3. **Creates tmux session** in the workspace root directory with access to all repositories\n4. **Generates IDE workspace files** for seamless editor integration\n\n**Example directory structure:**\n```\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\n# Creates branches: user-auth in all three repos\n# Creates single tmux session in workspace root\n# Can access all repositories with: cd frontend/, cd backend/, cd docs/\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```bash\npar workspace code user-auth\n```\n\nThis generates and opens a `.code-workspace` file containing:\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- 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```bash\npar workspace start feature-name\n# Automatically finds all git repositories in current directory\n```\n\n**Explicit specification:**\n```bash\npar workspace start feature-name --repos frontend,backend,shared\n# Only includes specified repositories\n```\n\n**Comma-separated syntax:**\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```bash\n# 1. Start workspace for new feature\ncd my-app/\npar workspace start user-profiles --repos frontend,backend\n\n# 2. Open in IDE with proper multi-repo support\npar workspace code user-profiles\n\n# 3. Open tmux session in workspace root\npar workspace 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. Clean up when feature is complete\npar workspace rm user-profiles\n```\n\n**Microservices development:**\n```bash\n# Work on API changes affecting multiple services\npar workspace start api-v2 --repos auth-service,user-service,gateway\n\n# All services get api-v2 branch\n# Single tmux session in workspace root\n# IDE workspace shows all services together\n# Navigate between services: cd auth-service/, cd user-service/, etc.\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### Repository-Scoped Sessions\n\n`par` automatically scopes sessions to the current Git repository. You can use the same labels across different projects without conflicts:\n\n```bash\ncd ~/project-a\npar start feature-auth # Creates project-a/feature-auth\n\ncd ~/project-b \npar start feature-auth # Creates separate project-b/feature-auth\n```\n\n## Configuration\n\n### Data Directory\nPar stores its data in `~/.local/share/par/` (or `$XDG_DATA_HOME/par/`):\n\n```\n~/.local/share/par/\n\u251c\u2500\u2500 state.json # Session metadata\n\u2514\u2500\u2500 worktrees/ # Git worktrees organized by repo\n \u2514\u2500\u2500 <repo-hash>/\n \u251c\u2500\u2500 feature-1/ # Individual workspaces\n \u251c\u2500\u2500 feature-2/\n \u2514\u2500\u2500 experiment-1/\n```\n\n### Session Naming Convention\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 for the current repository:\n```bash\npar rm all\n```\n\nRemove specific stale sessions:\n```bash\npar rm old-feature-name\n```\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.1.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "01e60bfe7ab8cdaee1d6b09e64c941ea950c83b0e33fa011abbc9f3475e69251",
"md5": "36831fc41fe3fa682f165a625cd45367",
"sha256": "8f38fc878a0e0551c7c7bbf934c236b679cd4453ef54a1ea5895bf452c0c8ead"
},
"downloads": -1,
"filename": "par_cli-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36831fc41fe3fa682f165a625cd45367",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 25304,
"upload_time": "2025-07-13T05:14:42",
"upload_time_iso_8601": "2025-07-13T05:14:42.646371Z",
"url": "https://files.pythonhosted.org/packages/01/e6/0bfe7ab8cdaee1d6b09e64c941ea950c83b0e33fa011abbc9f3475e69251/par_cli-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1c8b0b3e25001b0db4a1eb55e134f5d710a952bddb7cf0a0d47e5026cb7acbd9",
"md5": "83db097f0e77b726a1cfc1c4100ccf5d",
"sha256": "80b95118199514f480a62cbc53080ae8825c2e8e9ca5f4edef61558d4efcc704"
},
"downloads": -1,
"filename": "par_cli-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "83db097f0e77b726a1cfc1c4100ccf5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 20660,
"upload_time": "2025-07-13T05:14:43",
"upload_time_iso_8601": "2025-07-13T05:14:43.811005Z",
"url": "https://files.pythonhosted.org/packages/1c/8b/0b3e25001b0db4a1eb55e134f5d710a952bddb7cf0a0d47e5026cb7acbd9/par_cli-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 05:14:43",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "par-cli"
}
