name: project-session-manager

description: Worktree-first dev environment manager for issues, PRs, and features with optional tmux sessions

aliases: [psm]

level: 2

Project Session Manager (PSM) Skill

psm is the compatibility alias for this canonical skill entrypoint.

Quick Start (worktree-first): Start with omc teleport when you want an isolated issue/PR/feature worktree before adding any tmux/session orchestration:

```bash

omc teleport #123 # Create worktree for issue/PR

omc teleport my-feature # Create worktree for feature

omc teleport list # List worktrees

```

See Teleport Command below for details.

Automate isolated development environments using git worktrees and tmux sessions with Claude Code. Enables parallel work across multiple tasks, projects, and repositories.

Canonical slash command: /oh-my-claudecode:project-session-manager (alias: /oh-my-claudecode:psm).

Commands

Project References

Supported formats:

• Alias: omc#123 (requires ~/.psm/projects.json)
• Full: owner/repo#123
• URL: https://github.com/owner/repo/pull/123
• Current: #123 (uses current directory's repo)

Configuration

Project Aliases (~/.psm/projects.json)

{
  "aliases": {
    "omc": {
      "repo": "Yeachan-Heo/oh-my-claudecode",
      "local": "~/Workspace/oh-my-claudecode",
      "default_base": "main"
    }
  },
  "defaults": {
    "worktree_root": "~/.psm/worktrees",
    "cleanup_after_days": 14
  }
}

Providers

PSM supports multiple issue tracking providers:

Jira Configuration

To use Jira, add an alias with jira_project and provider: "jira":

{
  "aliases": {
    "mywork": {
      "jira_project": "MYPROJ",
      "repo": "mycompany/my-project",
      "local": "~/Workspace/my-project",
      "default_base": "develop",
      "provider": "jira"
    }
  }
}

Important: The repo field is still required for cloning the git repository. Jira tracks issues, but you work in a git repo.

For non-GitHub repos, use clone_url instead:

{
  "aliases": {
    "private": {
      "jira_project": "PRIV",
      "clone_url": "git@gitlab.internal:team/repo.git",
      "local": "~/Workspace/repo",
      "provider": "jira"
    }
  }
}

Jira Reference Detection

PSM only recognizes PROJ-123 format as Jira when PROJ is explicitly configured as a jira_project in your aliases. This prevents false positives from branch names like FIX-123.

Jira Examples

# Fix a Jira issue (MYPROJ must be configured)
psm fix MYPROJ-123

# Fix using alias (recommended)
psm fix mywork#123

# Feature development (works same as GitHub)
psm feature mywork add-webhooks

# Note: 'psm review' is not supported for Jira (no PR concept)
# Use 'psm fix' for Jira issues

Jira CLI Setup

Install the Jira CLI:

# macOS
brew install ankitpokhrel/jira-cli/jira-cli

# Linux
# See: https://github.com/ankitpokhrel/jira-cli#installation

# Configure (interactive)
jira init

The Jira CLI handles authentication separately from PSM.

Directory Structure

~/.psm/
├── projects.json       # Project aliases
├── sessions.json       # Active session registry
└── worktrees/          # Worktree storage
    └── <project>/
        └── <type>-<id>/

Session Naming

Implementation Protocol

When the user invokes a PSM command, follow this protocol:

Parse Arguments

Parse {{ARGUMENTS}} to determine:

1. Subcommand: review, fix, feature, list, attach, kill, cleanup, status
2. Reference: project#number, URL, or session ID
3. Options: --branch, --base, --no-claude, --no-tmux, etc.

Subcommand: review <ref>

Purpose: Create PR review session

Steps:

1. Resolve reference:

   # Read project aliases