Plural

Do more, faster. Parallel Claude Code sessions.

Run multiple Claude sessions on the same codebase—each in its own git branch. When Claude offers different approaches, fork the session and try them all in parallel. Switch freely. Merge the winner.

Requirements

• Claude Code CLI installed and authenticated
• Git
• GitHub CLI (gh) for PR creation (optional)

Run plural --check-prereqs to verify all required tools are installed and configured correctly.

Installation

Homebrew (Recommended)

brew tap zhubert/tap
brew install plural

Nix / Devbox

# Run directly without installing
nix run github:zhubert/plural

# Install to your profile
nix profile install github:zhubert/plural

# Or add to devbox
devbox add github:zhubert/plural
devbox global add github:zhubert/plural

From Source

See CONTRIBUTING.md for build instructions.

Quick Start

plural

1. Press a to add a git repository
2. Press n to create a new session
3. Press Tab or Enter to focus the chat
4. Type your message and press Enter
5. When Claude requests permission: y (allow), n (deny), or a (always allow)

Press ? at any time to see all available keyboard shortcuts for your current context.

---

Core Concepts

How Sessions Work

When you create a session, Plural:

1. Creates a new git branch (plural-<uuid> or your custom name)
2. Sets up a worktree in .plural-worktrees/<uuid> (sibling to your repo)
3. Starts a persistent Claude Code process in that worktree

This isolation means:

• Claude can edit files freely without affecting your main branch
• Multiple sessions can work on the same repo simultaneously
• You control when changes get merged

Applying Changes

When you're ready to use your session's changes:

1. Select the session
2. Press m to open the merge modal
3. Choose:
   • Merge to main: Directly merges into your default branch
   • Create PR: Pushes and creates a GitHub PR (requires gh)

Uncommitted changes are auto-committed before merge/PR. If there are merge conflicts, Claude can help resolve them.

Branching Options

When Claude presents multiple approaches (e.g., "Option 1: Use Redis" vs "Option 2: Use PostgreSQL"), you can explore them all in parallel:

1. Select a session where Claude has offered options
2. Press Ctrl+P to open the options explorer
3. Select which options to explore (use Space to toggle, a to select all)
4. Press Enter to fork the session

Plural creates child sessions for each selected option, automatically continuing the conversation with that choice. Child sessions appear indented under their parent in the sidebar.

Options are detected from:

• Markdown headings like ## Option 1: or ## Option A:
• Numbered lists with option patterns

---

GitHub Integration

Issue Import

Import issues directly from your GitHub repository and let Claude work on them automatically:

1. Press i from the sidebar
2. If no session is selected, choose a repository from the picker
3. Browse open issues with ↑/↓ and toggle selection with Space
4. Press Enter to create sessions for selected issues

Each issue becomes a new session with:

• Branch named issue-{number} (e.g., issue-42)
• Full issue context (title, body, labels) sent to Claude
• Claude automatically begins working on the fix

When you create a PR from an issue session, "Fixes #{number}" is automatically added to the PR description, which closes the issue when merged.

---

Session Management

Search

With many sessions, use / to search:

1. Press / in the sidebar
2. Type to filter by branch name, session name, or repo
3. Use ↑/↓ to navigate results
4. Press Enter to select, Esc to cancel

Rename

Give sessions meaningful names:

1. Select a session in the sidebar
2. Press r to open the rename modal
3. Enter the new name and press Enter

The git branch is also renamed to match (with the configured branch prefix applied).

View Changes

Review uncommitted changes before merging:

1. Select a session in the sidebar
2. Press v to view changes
3. Navigate between files with ←/→ or h/l
4. Scroll the diff with ↑/↓, j/k, or PgUp/PgDn
5. Press Esc or q to close

The navigation bar shows the current file's status (M=modified, A=added, D=deleted), filename, and position in the file list.

Open Terminal

Work directly in a session's worktree:

1. Select a session in the sidebar
2. Press Ctrl+E to open a new terminal window
3. The terminal opens at the session's worktree directory

Useful for running tests, checking git status, or manual edits alongside Claude's work.

Image Pasting

Share screenshots and diagrams with Claude:

1. Copy an image to your clipboard (e.g., Cmd+Shift+4 on macOS)
2. Focus the chat input
3. Press Ctrl+V to attach
4. You'll see [Image attached: XXkb]
5. Add a message and press Enter

Supports PNG, JPEG, GIF, and WebP (max 3.75MB).

Message Search

Search within conversation history:

1. Press Ctrl+/ when the chat panel is focused
2. Type to search messages
3. Use ↑/↓ to navigate matches
4. Press Enter to close

---

Customization

Themes

Press t to choose from:

• Dark Purple (default)
• Nord
• Dracula
• Gruvbox Dark
• Tokyo Night
• Catppuccin Mocha
• Science Fiction
• Light

Settings

Press , to open the Settings modal:

• Branch prefix: Set a default prefix for auto-generated branch names (e.g., yourname/ creates branches like yourname/plural-abc123)
• Desktop notifications: Toggle notifications when Claude finishes while Plural is in the background

Notification platform notes:

• macOS: Works out of the box. For better notifications, install terminal-notifier (brew install terminal-notifier)
• Linux: Requires a notification daemon (most desktop environments have one) or notify-send
• Windows 10+: Works out of the box

MCP Servers

Extend Claude's capabilities with MCP servers:

1. Press s from the sidebar
2. Add servers globally or per-repository
3. Configure name, command, and arguments

Example: Add a GitHub MCP server globally, or a database server for a specific project.

Slash Commands

Plural provides its own slash commands (Claude CLI's built-in commands don't work in stream-json mode):

• /cost - Show token usage and estimated cost for the current session
• /help - Show available Plural slash commands
• /mcp - Open MCP servers configuration modal
• /plugins - Open plugin directories configuration modal

Other slash commands are passed through to Claude CLI.

---

Reference

Configuration

Data stored in ~/.plural/:

• config.json - Repos, sessions, tools, MCP servers, theme
• sessions/<id>.json - Conversation history

Commands

plural                  # Start the application
plural --check-prereqs  # Verify required tools
plural --clear          # Remove all sessions
plural --prune          # Clean up orphaned worktrees
plural --debug          # Enable debug logging

Troubleshooting

Devbox/Nix upgrade fails

# Workaround for nix profile upgrade limitation
devbox global rm github:zhubert/plural
devbox global add github:zhubert/plural

Or use Homebrew which handles upgrades correctly.

---

Changelog

See the GitHub Releases page for version history and release notes.

License

MIT License - see LICENSE for details.