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:
omc teleport
omc teleport my-feature
omc teleport list
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
| Command |
Description |
Example |
review <ref> |
PR review session |
/psm review omc#123 |
fix <ref> |
Issue fix session |
/psm fix omc#42 |
feature <proj> <name> |
Feature development |
/psm feature omc add-webhooks |
list [project] |
List active sessions |
/psm list |
attach <session> |
Attach to session |
/psm attach omc:pr-123 |
kill <session> |
Kill session |
/psm kill omc:pr-123 |
cleanup |
Clean merged/closed |
/psm cleanup |
status |
Current session info |
/psm status |
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:
| Provider |
CLI Required |
Reference Formats |
Commands |
| GitHub (default) |
gh |
owner/repo#123, alias#123, GitHub URLs |
review, fix, feature |
| Jira |
jira |
PROJ-123 (if PROJ configured), alias#123 |
fix, feature |
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": "[email protected]: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
psm fix MYPROJ-123
psm fix mywork
psm feature mywork add-webhooks
Jira CLI Setup
Install the Jira CLI:
brew install ankitpokhrel/jira-cli/jira-cli
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
| Type |
Tmux Session |
Worktree Dir |
| PR Review |
psm:omc:pr-123 |
~/.psm/worktrees/omc/pr-123 |
| Issue Fix |
psm:omc:issue-42 |
~/.psm/worktrees/omc/issue-42 |
| Feature |
psm:omc:feat-auth |
~/.psm/worktrees/omc/feat-auth |
Implementation Protocol
When the user invokes a PSM command, follow this protocol:
Parse Arguments
Parse {{ARGUMENTS}} to determine:
- Subcommand: review, fix, feature, list, attach, kill, cleanup, status
- Reference: project#number, URL, or session ID
- Options: --branch, --base, --no-claude, --no-tmux, etc.
Subcommand: review <ref>
Purpose: Create PR review session
Steps:
-
Resolve reference:
cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
-
Fetch PR info:
gh pr view <pr_number> --repo <repo> --json number,title,author,headRefName,baseRefName,body,files,url
-
Ensure local repo exists:
if [[ ! -d "$local_path" ]]; then
git clone "https://github.com/$repo.git" "$local_path"
fi
-
Create worktree:
worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
cd "$local_path"
git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
git worktree add "$worktree_path" "pr-$pr_number-review"
-
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
-
Update sessions registry:
-
Create tmux session:
tmux new-session -d -s "psm:$project_alias:pr-$pr_number" -c "$worktree_path"
-
Launch Claude Code (unless --no-claude):
tmux send-keys -t "psm:$project_alias:pr-$pr_number" "claude" Enter
-
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:
-
Resolve reference (same as review)
-
Fetch issue info:
gh issue view <issue_number> --repo <repo> --json number,title,body,labels,url
-
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
-
Create worktree:
worktree_path="$HOME/.psm/worktrees/$project_alias/issue-$issue_number"
git worktree add "$worktree_path" "$branch_name"
-
Create session metadata (similar to review, type="fix")
-
Update registry, create tmux, launch claud
