project-session-manager

用途

Project Session Manager（PSM）是一个 worktree 优先的开发环境管理器，用于在 Claude Code 中为 issue、PR 和功能开发自动创建隔离的开发环境。它结合 git worktree 与 tmux 会话，支持在多个任务、项目和仓库之间并行工作。

psm 是此规范技能入口点的兼容别名。规范斜杠命令为 /oh-my-claudecode:project-session-manager（别名：/oh-my-claudecode:psm）。

主要能力

PSM 提供以下命令：

review <ref>：创建 PR 审查会话，例如 /psm review omc#123
fix <ref>：创建 issue 修复会话，例如 /psm fix omc#42
feature <proj> <name>：功能开发，例如 /psm feature omc add-webhooks
list [project]：列出活动会话
attach <session>：附加到会话，例如 /psm attach omc:pr-123
kill <session>：终止会话
cleanup：清理已合并/已关闭的会话
status：显示当前会话信息

项目引用支持多种格式：别名（omc#123，需 ~/.psm/projects.json）、完整格式（owner/repo#123）、URL（https://github.com/owner/repo/pull/123）、当前目录（#123）。

PSM 支持多个 issue 追踪提供方：GitHub（默认，需 gh CLI）和 Jira（需 jira CLI）。Jira 仅识别显式配置为 jira_project 的 PROJ-123 格式，以避免误判。注意 Jira 不支持 review 命令（无 PR 概念），应使用 fix。

使用方式

快速开始（worktree 优先）：使用 omc teleport 在添加 tmux/会话编排之前创建隔离的 issue/PR/功能 worktree：

omc teleport #123          # 为 issue/PR 创建 worktree
omc teleport my-feature    # 为功能创建 worktree
omc teleport list          # 列出 worktrees

配置项目别名（~/.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
  }
}

Jira 配置需添加 jira_project 和 provider: "jira"，repo 字段仍为克隆 git 仓库所必需。非 GitHub 仓库可使用 clone_url。

Jira CLI 安装：

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

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

# 配置（交互式）
jira init

目录结构：

~/.psm/
├── projects.json       # 项目别名
├── sessions.json       # 活动会话注册表
└── worktrees/          # worktree 存储
    └── <project>/
        └── <type>-<id>/

会话命名：公开会话 ID 使用冒号形式（如 omc:pr-123），用于 psm attach/kill。由于 tmux 保留 : 和 . 用于其 session:window.pane 目标语法并会静默重写，实际 tmux 会话名使用安全形式，将这些字符替换为 _（issue #3528）。PSM 在每个 tmux 边界将公开 ID 转换为 tmux 安全名。

适用场景

需要为 PR 审查、issue 修复或功能开发创建隔离环境
需要跨多个任务、项目、仓库并行工作
希望自动启动 Claude Code 并传入任务上下文
需要自动清理已合并 PR 和已关闭 issue 的会话

限制

依赖 git（需 worktree 支持 v2.5+）和 jq
tmux 为可选但推荐；无 tmux 时会警告并跳过会话创建
GitHub 工作流需 gh CLI；Jira 工作流需 jira CLI
Jira 不支持 review 命令
启动 Claude Code 时使用 --dangerously-skip-permissions 以避免信任目录提示和工具审批提示阻塞会话（issue #2508）
启动后等待 PSM_CLAUDE_STARTUP_DELAY（默认 5 秒）再投递任务

Teleport 命令

omc teleport 提供轻量替代方案，仅创建 git worktree 而不管理 tmux 会话。选项包括 --worktree（默认 true）、--path <path>（默认 ~/Workspace/omc-worktrees/）、--base <branch>（默认 main）、--json。

PSM 与 Teleport 对比：PSM 支持 git worktree、tmux 会话、Claude Code 启动、会话注册表、自动清理、项目别名；Teleport 仅支持 git worktree（使用当前仓库）。完整管理会话用 PSM，快速创建 worktree 用 teleport。

初始化

首次运行时创建默认配置：

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

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

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

技能介绍

用途

主要能力

使用方式

适用场景

限制

Teleport 命令

初始化