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

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 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
2. Fetch PR info: gh pr view <pr_number> --repo <repo> --json number,title,author,headRefName,baseRefName,body,files,url
3. Ensure local repo exists: # If local path doesn't exist, clone if [[! -d "$local_path"]]; then git clone "https://github.com/$repo.git" "$local_path" fi
4. Create worktree: 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"
5. Create session metadata: 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
6. Update sessions registry: # Add to ~/.psm/sessions.json
7. Create tmux session: tmux new-session -d -s "psm:$project_alias:pr-$pr_number" -c "$worktree_path"
8. Launch Claude Code (unless --no-claude): # --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
9. 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

Subcommand: fix <ref>

Purpose: Create issue fix session

Steps:

1. Resolve reference (same as review)
2. Fetch issue info: gh issue view <issue_number> --repo <repo> --json number,title,body,labels,url
3. Create feature branch: 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
4. Create worktree: worktree_path="$HOME/.psm/worktrees/$project_alias/issue-$issue_number" git worktree add "$worktree_path" "$branch_name"
5. Create session metadata (similar to review, type="fix")
6. Update registry, create tmux, launch claude: Same as review, but pass issue context as the initial task prompt: 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)
2. Create feature branch: cd "$local_path" git fetch origin main branch_name="feature/$feature_name" git checkout -b "$branch_name" origin/main
3. Create worktree: worktree_path="$HOME/.psm/worktrees/$project_alias/feat-$feature_name" git worktree add "$worktree_path" "$branch_name"
4. Create session, tmux, launch claude with feature context as initial prompt: 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: cat ~/.psm/sessions.json 2>/dev/null || echo '{"sessions":{}}'
2. Check tmux sessions: tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^psm:"
3. Check worktrees: ls -la ~/.psm/worktrees/*/ 2>/dev/null
4. 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
2. Verify session exists: tmux has-session -t "psm:$session_id" 2>/dev/null
3. Attach: tmux attach -t "psm:$session_id"

Subcommand: kill <session>

Purpose: Kill session and cleanup

Steps:

1. Kill tmux session: tmux kill-session -t "psm:$session_id" 2>/dev/null
2. Remove worktree: 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
3. Update registry: # Remove from sessions.json

Subcommand: cleanup

Purpose: Clean up merged PRs and closed issues

Steps:

1. Read all sessions
2. For each PR session, check if merged: gh pr view <pr_number> --repo <repo> --json merged,state
3. For each issue session, check if closed: gh issue view <issue_number> --repo <repo> --json closed,state
4. Clean up merged/closed sessions:

- Kill tmux session - Remove worktree - Update registry

1. Report: Cleanup complete: Removed: omc:pr-123 (merged) Removed: omc:issue-42 (closed) Kept: omc:feat-auth (active)

Subcommand: status

Purpose: Show current session info

Steps:

1. Detect current session from tmux or cwd: tmux display-message -p "#{session_name}" 2>/dev/null # or check if cwd is inside a worktree
2. Read session metadata: cat.psm-session.json 2>/dev/null
3. Show status: Current Session: omc:pr-123 Type: review PR: #123 - Add webhook support Branch: feature/webhooks Created: 2 hours ago

Error Handling

Teleport Command

The omc teleport command provides a lightweight alternative to full PSM sessions. It creates git worktrees without tmux session management — ideal for quick, isolated development.

Usage

# Create worktree for an issue or PR
omc teleport #123
omc teleport owner/repo#123
omc teleport https://github.com/owner/repo/issues/42

# Create worktree for a feature
omc teleport my-feature

# List existing worktrees
omc teleport list

# Remove a worktree
omc teleport remove issue/my-repo-123
omc teleport remove --force feat/my-repo-my-feature

Options

Worktree Layout

~/Workspace/omc-worktrees/
├── issue/
│   └── my-repo-123/        # Issue worktrees
├── pr/
│   └── my-repo-456/        # PR review worktrees
└── feat/
    └── my-repo-my-feature/ # Feature worktrees

PSM vs Teleport

Use PSM for full managed sessions. Use teleport for quick worktree creation.

Requirements

Required:

• git - Version control (with worktree support v2.5+)
• jq - JSON parsing
• tmux - Session management (optional, but recommended)

Optional (per provider):

• gh - GitHub CLI (for GitHub workflows)
• jira - Jira CLI (for Jira workflows)

Initialization

On first run, create default config:

mkdir -p ~/.psm/worktrees ~/.psm/logs

# Create default projects.json if not exists
if [[ ! -f ~/.psm/projects.json ]]; then
  cat > ~/.psm/projects.json << 'EOF'
{
  "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,
    "auto_cleanup_merged": true
  }
}
EOF
fi

# Create sessions.json if not exists
if [[ ! -f ~/.psm/sessions.json ]]; then
  echo '{"version":1,"sessions":{},"stats":{"total_created":0,"total_cleaned":0}}' > ~/.psm/sessions.json
fi