Getting Started¶

Prerequisites¶

Go 1.22+ -- required for installation and building
Git -- required for project tracking and worktrees
gh CLI (optional) -- for GitHub release information in pm project show
wt CLI (optional) -- for advanced worktree management via pm worktree

Installation¶

Via `go install`¶

go install github.com/joescharf/pm@latest

Build from source¶

git clone https://github.com/joescharf/pm.git
cd pm
make build
# Binary is at ./bin/pm

To install to your $GOPATH/bin:

make install

Initial Setup¶

Create a configuration file¶

pm config init

This creates ~/.config/pm/config.yaml with commented defaults. Review and edit it:

pm config edit

Verify your configuration¶

pm config show

This displays all effective values and where each comes from (default, file, or environment variable):

Config file: /home/user/.config/pm/config.yaml

  state_dir              /home/user/.config/pm  (default)
  db_path                /home/user/.config/pm/pm.db  (default)
  github.default_org                            (default)
  agent.model            opus                   (default)
  agent.auto_launch      false                  (default)

Add Your First Project¶

Add the current directory as a tracked project:

cd ~/code/my-project
pm project add .

Or add a specific path with a group:

pm project add ~/code/my-api --group backend

Auto-discover projects¶

Scan a parent directory to find and add all git repos at once:

pm project scan ~/code

This finds every top-level git repository under ~/code and adds it to tracking.

List tracked projects¶

pm project list

Create an Issue¶

pm issue add my-project --title "Add user authentication" --priority high --type feature

If you're inside a tracked project directory, you can omit the project name:

cd ~/code/my-project
pm issue add --title "Fix login bug" --type bug

Check Status¶

View a dashboard across all projects:

pm status

This shows each project's current branch, dirty/clean status, open issue counts, health score, and last activity time.

Filter to stale projects (no activity in 7+ days):

pm status --stale

Launch the Web Dashboard¶

pm serve

This starts the embedded web UI at http://localhost:8080 and the REST API at http://localhost:8080/api/v1/.

PM Web Dashboard

Use --port to change the port:

pm serve --port 3000

Next Steps¶

Configuration -- Customize settings, environment variables, and database location
Command Reference -- Full details on every command and flag
Workflows -- End-to-end usage patterns for common tasks
REST API -- Programmatic access via HTTP endpoints