pm

Terminal-based project manager built around tmux and git worktrees.

Requirements

• tmux
• git
• gh (for pm feat pr)

Install

cargo install --path .

Installs the pm binary to ~/.cargo/bin/. Ensure this is in your PATH.

Quick start

Option A: New project from scratch

pm init ~/projects/myapp
cd ~/projects/myapp/main

Creates a project root with a git repo in main/ and a .pm/ state directory.

Option B: Register an existing repo (symlink)

pm register ~/code/myapp --name myapp
cd ~/code/myapp-pm/main

Creates a wrapper directory (myapp-pm/) with a symlink to the original repo as main/. The original repo is untouched.

Option C: Register an existing repo (move)

pm register ~/code/myapp --name myapp --move
cd ~/code/myapp/main

Restructures the repo in-place: moves it into main/ within a new wrapper at the same path. No -pm suffix needed since the original directory becomes the wrapper.

Create a feature

pm feat new login
pm feat new login --context "Implement login page per issue #42"
pm feat new login --context path/to/brief.md

Creates a git branch, worktree, and tmux session (myapp/login). With --context, seeds a TASK.md in the worktree.

List features

pm feat list

Switch to a feature

pm feat switch login             # direct switch
pm feat switch                   # interactive picker (tmux display-menu)

Merge a feature

pm feat merge login             # merge into main
pm feat merge --delete          # merge current feature and clean up

Blocks if either the feature or main worktree has uncommitted changes. Always creates a merge commit (--no-ff). Feature name is detected from CWD if omitted.

Lifecycle hooks

Every project is bootstrapped with two hook scripts:

• .pm/hooks/post-create.sh — runs in the feature's tmux session after pm feat new
• .pm/hooks/post-merge.sh — runs in the main tmux session after pm feat merge

Hooks run asynchronously in a dedicated hook window via tmux send-keys — pm does not block on their completion. The hook window is reused across invocations.

Edit the scripts to add your own logic (install deps, run migrations, deploy, etc.). Removing a hook script disables it.

Create a PR

pm feat pr login                # create a draft PR for the feature
pm feat pr --ready              # create a non-draft PR (feature detected from CWD)

Pushes the branch to origin, then creates a GitHub PR via gh. Draft by default; use --ready for a non-draft PR. If a PR already exists for the branch, links it instead of creating a new one. Respects .github/pull_request_template.md if present. Stores the PR number in feature state. Draft PRs keep wip status; --ready sets status to review. Feature name is detected from CWD if omitted.

Mark a PR as ready for review

pm feat ready                   # mark current feature's PR as ready
pm feat ready login             # mark a specific feature's PR as ready

Pushes latest commits, then calls gh pr ready to remove draft status. Sets feature status to review. Fails if the feature has no linked PR — run pm feat pr first.

Delete a feature

pm feat delete login             # with safety checks
pm feat delete --force           # delete current feature, skip safety checks

Safety checks block deletion if the feature has uncommitted changes or commits not merged into main. Untracked files trigger a warning but don't block. Feature name is detected from CWD if omitted.

Open a project

pm open                          # open/reconstruct sessions for current project

Creates tmux sessions for the main worktree and any active features that are missing sessions. Useful after a reboot or tmux server restart.

Permissions management

Manage Claude Code settings (settings.json, settings.local.json) across worktrees. The main worktree's .claude/ directory is the source of truth — new features are seeded from it automatically.

pm perm list              # show current feature's .claude/ settings
pm perm push              # push current feature's .claude/ settings to main
pm perm pull              # pull main's .claude/ settings into current feature
pm perm diff              # show differences between main and feature
pm perm merge             # union merge feature settings into main (main wins on conflicts)
pm perm merge --ours      # union merge, feature wins on conflicts

Feature name is detected from CWD if omitted.

Claude Code session migration

When registering or adopting repos, Claude Code sessions are automatically migrated from the old path to the new worktree path. Sessions are copied (not moved) so originals remain accessible.

pm claude migrate --from /old/path   # migrate sessions from old path to CWD
pm feat adopt login --from /old/path # adopt branch and migrate sessions

pm register (both symlink and move modes) migrates sessions automatically — no extra flags needed.

Other commands

pm list                          # list all registered projects
pm open                          # open/reconstruct tmux sessions
pm --help                        # full help
pm feat --help                   # feature subcommand help

Development

cargo build
cargo test
cargo clippy
cargo fmt

See design.md for the full spec and CLAUDE.md for development guidelines.