yeachan-heo/oh-my-claudecode/project-session-manager

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

The public session ID (colon form, e.g. omc:pr-123) is the human-facing identifier stored in sessions.json and used with psm attach/psm kill. tmux reserves : and . for its session:window.pane target syntax and silently rewrites them, so the actual tmux session name uses a tmux-safe form where those characters become _ (issue #3528). PSM translates the public ID to the tmux-safe name at every tmux boundary; attach directly with the tmux-safe name.

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:

```bash # Read project aliases cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'

# Parse ref format: alias#num, owner/repo#num, or URL # Extract: project_alias, repo (owner/repo), pr_number, local_path ```

1. Fetch PR info:

``bash gh pr view <pr_number> --repo <repo> --json number,title,author,headRefName,baseRefName,body,files,url ``

1. Ensure local repo exists:

``bash # If local path doesn't exist, clone if [[ ! -d "$local_path" ]]; then git clone "https://github.com/$repo.git" "$local_path" fi ``

1. Create worktree:

```bash worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"

# Fetch PR branch cd "$local_path" git fetch origin "pull/$pr_number/head:pr-$pr_number-review"

# Create worktree git worktree add "$worktree_path" "pr-$pr_number-review" ```

1. Create session metadata:

``bash cat > "$worktree_path/.psm-session.json" << EOF { "id": "$project_alias:pr-$pr_number", "type": "review", "project": "$project_alias", "ref": "pr-$pr_number", "branch": "<head_branch>", "base": "<base_branch>", "created_at": "$(date -Iseconds)", "tmux_session": "psm_${project_alias}_pr-$pr_number", "worktree_path": "$worktree_path", "source_repo": "$local_path", "github": { "pr_number": $pr_number, "pr_title": "<title>", "pr_author": "<author>", "pr_url": "<url>" }, "state": "active" } EOF ``

1. Update sessions registry:

``bash # Add to ~/.psm/sessions.json ``

1. Create tmux session (tmux-safe name; :/. are translated to _):

``bash tmux new-session -d -s "psm_${project_alias}_pr-$pr_number" -c "$worktree_path" ``

1. Launch Claude Code (unless --no-claude):

```bash # --dangerously-skip-permissions prevents the "Do you trust this directory?" prompt # and repeated tool-approval prompts from stalling the session (issue #2508). tmux send-keys -t "psm_${project_alias}_pr-$pr_number" "claude --dangerously-skip-permissions" Enter

# After claude boots (PSM_CLAUDE_STARTUP_DELAY, default 5s), deliver the task. # Use -l (literal) so special characters are not misinterpreted by tmux. sleep "${PSM_CLAUDE_STARTUP_DELAY:-5}" tmux send-keys -t "psm_${project_alias}_pr-$pr_number" -l \ "Review PR #$pr_number: \"$pr_title\" by @$pr_author ($head_branch → $base_branch). URL: $pr_url." Enter ```

1. Output session info:

``` Session ready!

ID: omc:pr-123 Worktree: ~/.psm/worktrees/omc/pr-123 Tmux: psm_omc_pr-123

To attach: tmux attach -t psm_omc_pr-123 (or: psm attach omc:pr-123) ```

Subcommand: fix <ref>

Purpose: Create issue fix session

Steps:

1. Resolve reference (same as review)

1. Fetch issue info:

``bash gh issue view <issue_number> --repo <repo> --json number,title,body,labels,url ``

1. Create feature branch:

``bash cd "$local_path" git fetch origin main branch_name="fix/$issue_number-$(echo "$title" | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | head -c 30)" git checkout -b "$branch_name" origin/main ``

1. Create worktree:

``bash worktree_path="$HOME/.psm/worktrees/$project_alias/issue-$issue_number" git worktree add "$worktree_path" "$branch_name" ``

1. Create session metadata (similar to review, type="fix")

1. Update registry, create tmux, launch claude:

Same as review, but pass issue context as the initial task prompt: ``bash tmux send-keys -t "psm_${project_alias}_issue-$issue_number" "claude --dangerously-skip-permissions" Enter # After claude boots, deliver the task (see PSM_CLAUDE_STARTUP_DELAY): tmux send-keys -t "psm_${project_alias}_issue-$issue_number" -l \ "Fix issue #$issue_number: \"$issue_title\". URL: $issue_url. Branch: $branch_name." Enter ``

Subcommand: feature <project> <name>

Purpose: Start feature development

Steps:

1. Resolve project (from alias or path)

1. Create feature branch:

``bash cd "$local_path" git fetch origin main branch_name="feature/$feature_name" git checkout -b "$branch_name" origin/main ``

1. Create worktree:

``bash worktree_path="$HOME/.psm/worktrees/$project_alias/feat-$feature_name" git worktree add "$worktree_path" "$branch_name" ``

1. Create session, tmux, launch claude with feature context as initial prompt:

``bash tmux send-keys -t "psm_${project_alias}_feat-$feature_name" "claude --dangerously-skip-permissions" Enter tmux send-keys -t "psm_${project_alias}_feat-$feature_name" -l \ "Implement feature \"$feature_name\" for project $project. Branch: $branch_name." Enter ``

Subcommand: list [project]

Purpose: List active sessions

Steps:

1. Read sessions registry:

``bash cat ~/.psm/sessions.json 2>/dev/null || echo '{"sessions":{}}' ``

1. Check tmux sessions:

``bash tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^psm_" ``

1. Check worktrees:

``bash ls -la ~/.psm/worktrees/*/ 2>/dev/null ``

1. Format output:

``` Active PSM Sessions:

ID | Type | Status | Worktree -------------------|---------|----------|--------------------------- omc:pr-123 | review | active | ~/.psm/worktrees/omc/pr-123 omc:issue-42 | fix | detached | ~/.psm/worktrees/omc/issue-42 ```

Subcommand: attach <session>

Purpose: Attach to existing session

Steps:

1. Parse session ID: project:type-number

1. Verify session exists:

``bash tmux has-session -t "psm_${session_id//[.:]/_}" 2>/dev/null # translate public id to tmux-safe name ``

1. Attach:

``bash tmux attach -t "psm_${session_id//[.:]/_}" ``

Subcommand: kill <session>

Purpose: Kill session and cleanup

Steps:

1. Kill tmux session:

``bash tmux kill-session -t "psm_${session_id//[.:]/_}" 2>/dev/null ``

1. Remove worktree:

```bash worktree_path=$(jq -r ".sessions[\"$session_id\"].worktree" ~/.psm/sessions.json) source_repo=$(jq -r ".sessions[\"$session_id\"].source_repo" ~/.psm/sessions.json)

cd "$source_repo" git worktree remove "$worktree_path" --force ```

1. Update registry:

``bash # Remove from sessions.json ``

Subcommand: cleanup

Purpose: Clean up merged PRs and closed issues

Steps: