project-session-manager_skill

Overview

This skill manages isolated development environments using git worktrees and tmux sessions to enable parallel, team-friendly work. It automates creating review, fix, and feature sessions, tracks active worktrees, and can launch Claude Code inside tmux for agent-assisted coding. Use it to keep context-separated branches and sessions without polluting your main repo.

How this skill works

The skill parses subcommands (review, fix, feature, list, attach, kill, cleanup, status) and resolves references via project aliases, full repo refs, or URLs. It creates git worktrees under a configurable root, registers session metadata in a sessions registry, manages tmux sessions named psm:<project>:<id>, and optionally launches Claude Code inside tmux panes. Cleanup and status checks use provider CLIs (gh or jira) to detect merged/closed work.

When to use it

• Start a PR review session and inspect changed files without switching branches locally.
• Create an isolated branch and worktree for fixing a specific issue while keeping other work untouched.
• Spin up feature worktrees for long-running work and switch between tasks quickly.
• Run cleanup to remove worktrees and tmux sessions for merged PRs or closed issues.
• Quickly create a worktree without tmux using the teleport command for fast experiments.

Best practices

• Configure ~/.psm/projects.json with aliases for repositories and default bases to avoid repetitive flags.
• Use feature or fix sessions per task to keep commits and branches scoped and review-friendly.
• Run psm cleanup regularly or enable auto_cleanup_merged to reclaim disk and session state.
• Prefer attach over recreate when a worktree already exists to avoid accidental branch duplication.
• Ensure gh or jira CLI is installed and authenticated for provider-backed operations.

Example use cases

• psm review omc#123 — create a worktree for PR #123, open a tmux session, and launch Claude Code for review assistance.
• psm fix myproj#42 — spawn a fix/issue branch, worktree, and tmux session tied to issue 42 for focused fixes.
• psm feature omc add-webhooks — start a feature/ branch and isolated worktree for building webhooks.
• psm list — list active PSM tmux sessions and worktrees with their status and paths.
• omc teleport #123 — lightweight worktree creation without tmux for quick edits or local testing.