プロジェクトセッションマネージャー (PSM)

Project Session Manager (PSM) スキル

psm は、この正規スキルのエントリポイントに対する互換性エイリアスです。

クイックスタート (worktree 優先): tmux/セッションのオーケストレーションを追加する前に、まずは omc teleport を使用して隔離された Issue/PR/機能の worktree を作成します。

omc teleport #123          # Issue/PR 用に worktree を作成
omc teleport my-feature    # 機能開発用に worktree を作成
omc teleport list          # worktree 一覧を表示

詳細は Teleport コマンド を参照してください。

Claude Code と連携して、git worktree と tmux セッションを使用した隔離された開発環境を自動化します。複数のタスク、プロジェクト、リポジトリにわたる並行作業を可能にします。

正規スラッシュコマンド: /oh-my-claudecode:project-session-manager (エイリアス: /oh-my-claudecode: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]	アクティブなセッション一覧	/psm list
attach <session>	セッションにアタッチ	/psm attach omc:pr-123
kill <session>	セッションを強制終了	/psm kill omc:pr-123
cleanup	マージ済み/クローズ済みをクリーンアップ	/psm cleanup
status	現在のセッション情報	/psm status

プロジェクト参照

サポートされている形式:

• エイリアス: omc#123 (~/.psm/projects.json が必要)
• 完全形式: owner/repo#123
• URL: https://github.com/owner/repo/pull/123
• 現在のプロジェクト: #123 (現在のディレクトリのリポジトリを使用)

設定

プロジェクトエイリアス (~/.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
  }
}

プロバイダー

PSM は複数の課題追跡プロバイダーをサポートしています:

プロバイダー	必要な CLI	参照形式	コマンド
GitHub (デフォルト)	gh	owner/repo#123, alias#123, GitHub URL	review, fix, feature
Jira	jira	PROJ-123 (PROJ が設定されている場合), alias#123	fix, feature

Jira 設定

Jira を使用するには、jira_project と provider: "jira" を含むエイリアスを追加します:

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

重要: git リポジトリをクローンするために repo フィールドは依然として必要です。Jira は課題を追跡しますが、作業は git リポジトリ内で行います。

GitHub 以外のリポジトリの場合は、代わりに clone_url を使用します:

{
  "aliases": {
    "private": {
      "jira_project": "PRIV",
      "clone_url": "[email protected]:team/repo.git",
      "local": "~/Workspace/repo",
      "provider": "jira"
    }
  }
}

Jira 参照の検出

PSM は PROJ-123 形式を、PROJ がエイリアスで jira_project として明示的に設定されている場合にのみ Jira として認識します。これにより、FIX-123 のようなブランチ名による誤検出を防ぎます。

Jira の例

# Jira Issue を修正 (MYPROJ が設定されている必要があります)
psm fix MYPROJ-123

# エイリアスを使用して修正 (推奨)
psm fix mywork#123

# 機能開発 (GitHub と同じように動作)
psm feature mywork add-webhooks

# 注意: 'psm review' は Jira ではサポートされていません (PR の概念がないため)
# Jira Issue には 'psm fix' を使用してください

Jira CLI のセットアップ

Jira CLI をインストールします:

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

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

# 設定 (対話式)
jira init

Jira CLI は認証を PSM とは別に処理します。

ディレクトリ構造

~/.psm/
├── projects.json       # プロジェクトエイリアス
├── sessions.json       # アクティブセッションレジストリ
└── worktrees/          # Worktree ストレージ
    └── <project>/
        └── <type>-<id>/

セッションの命名規則

パブリックセッション ID (コロン形式、例: omc:pr-123) は人間が読みやすい識別子で、sessions.json に保存され、psm attach / psm kill で使用されます。tmux は : と . を session:window.pane ターゲット構文のために予約しており、これらを自動的に書き換えるため、実際の tmux セッション名 はこれらの文字を _ に変換した tmux セーフな形式を使用します (issue #3528)。PSM はすべての tmux 境界でパブリック ID を tmux セーフな名前に変換します。tmux セーフな名前で直接アタッチすることもできます。

タイプ	パブリック ID (psm attach/kill)	Tmux セッション (tmux attach -t)	Worktree ディレクトリ
PR レビュー	omc:pr-123	psm_omc_pr-123	~/.psm/worktrees/omc/pr-123
Issue 修正	omc:issue-42	psm_omc_issue-42	~/.psm/worktrees/omc/issue-42
機能開発	omc:feat-auth	psm_omc_feat-auth	~/.psm/worktrees/omc/feat-auth

---

実装プロトコル

ユーザーが PSM コマンドを呼び出した場合、以下のプロトコルに従ってください:

引数の解析

{{ARGUMENTS}} を解析して以下を特定します:

1. サブコマンド: review, fix, feature, list, attach, kill, cleanup, status
2. 参照: project#number, URL, またはセッション ID
3. オプション: --branch, --base, --no-claude, --no-tmux など

サブコマンド: review <ref>

目的: PR レビューセッションを作成

手順:

1. 参照を解決:

   # プロジェクトエイリアスを読み込む
   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
   
   # ref 形式を解析: alias#num, owner/repo#num, または URL
   # 抽出: project_alias, repo (owner/repo), pr_number, local_path
   

2. PR 情報を取得:

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

3. ローカルリポジトリの存在を確認:

   # ローカルパスが存在しない場合はクローン
   if [[ ! -d "$local_path" ]]; then
     git clone "https://github.com/$repo.git" "$local_path"
   fi
   

4. Worktree を作成:

   worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
   
   # PR ブランチをフェッチ
   cd "$local_path"
   git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
   
   # Worktree を作成
   git worktree add "$worktree_path" "pr-$pr_number-review"
   

5. セッションメタデータを作成:

   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. セッションレジストリを更新:

   # ~/.psm/sessions.json に追加
   

7. tmux セッションを作成 (tmux セーフな名前; :/. は _ に変換):

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

8. Claude Code を起動 (--no-claude が指定されていない場合):

   # --dangerously-skip-permissions は「このディレクトリを信頼しますか？」というプロンプトと
   # 繰り返しのツール承認プロンプトを回避し、セッションの停止を防ぎます (issue #2508)。
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" "claude --dangerously-skip-permissions" Enter
   
   # claude が起動した後 (PSM_CLAUDE_STARTUP_DELAY、デフォルト 5 秒)、タスクを配信します。
   # -l (リテラル) を使用して、特殊文字が tmux によって誤って解釈されないようにします。
   sleep "${PSM_CLAUDE_STARTUP_DELAY:-5}"
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" -l \
     "PR #$pr_number をレビュー: \"$pr_title\" by @$pr_author ($head_branch → $base_branch). URL: $pr_url." Enter
   

9. セッション情報を出力:

   セッション準備完了!
   
     ID: omc:pr-123
     Worktree: ~/.psm/worktrees/omc/pr-123
     Tmux: psm_omc_pr-123
   
   アタッチ方法: tmux attach -t psm_omc_pr-123   (または: psm attach omc:pr-123)
   

サブコマンド: fix <ref>

目的: Issue 修正セッションを作成

手順:

1. 参照を解決 (review と同じ)

2. Issue 情報を取得:

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

3. 機能ブランチを作成:

   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. Worktree を作成:

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

5. セッションメタデータを作成 (review と同様、type="fix")

6. レジストリを更新、tmux を作成、claude を起動: review と同様ですが、初期タスクプロンプトとして Issue のコンテキストを渡します:

   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" "claude --dangerously-skip-permissions" Enter
   # claude が起動した後、タスクを配信 (PSM_CLAUDE_STARTUP_DELAY を参照):
   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" -l \
     "Issue #$issue_number を修正: \"$issue_title\". URL: $issue_url. ブランチ: $branch_name." Enter
   

サブコマンド: feature <project> <name>

目的: 機能開発を開始

手順:

1. プロジェクトを解決 (エイリアスまたはパスから)

2. 機能ブランチを作成:

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

3. Worktree を作成:

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

4. セッション、tmux、claude を作成 し、初期プロンプトとして機能コンテキストを渡します:

   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 \
     "プロジェクト $project 向けに機能 \"$feature_name\" を実装。ブランチ: $branch_name。" Enter
   

サブコマンド: list [project]

目的: アクティブなセッション一覧を表示

手順:

1. セッションレジストリを読み込む:

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

2. tmux セッションを確認:

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

3. worktree を確認:

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

4. 出力を整形:

   アクティブな PSM セッション:
   
   ID                 | タイプ  | ステータス | Worktree
   -------------------|---------|----------|---------------------------
   omc:pr-123        | review  | active   | ~/.psm/worktrees/omc/pr-123
   omc:issue-42      | fix     | detached | ~/.psm/worktrees/omc/issue-42
   

サブコマンド: attach <session>

目的: 既存のセッションにアタッチ

手順:

1. セッション ID を解析: project:type-number

2. セッションの存在を確認:

   tmux has-session -t "psm_${session_id//[.:]/_}" 2>/dev/null   # パブリック ID を tmux セーフな名前に変換
   

3. アタッチ:

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

サブコマンド: kill <session>

目的: セッションを強制終了してクリーンアップ

手順:

1. tmux セッションを強制終了:

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

2. 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. レジストリを更新:

   # sessions.json から削除
   

サブコマンド: cleanup

目的: マージ済み PR とクローズ済み Issue をクリーンアップ

手順:

1. すべてのセッションを読み込む

2. 各 PR セッションについて、マージ済みか確認:

   gh pr view <pr_number> --repo <repo> --json merged,state
   

3. 各 Issue セッションについて、クローズ済みか確認:

   gh issue view <issue_number> --repo <repo> --json closed,state
   

4. マージ/クローズ済みセッションをクリーンアップ:

   • tmux セッションを強制終了
   • Worktree を削除
   • レジストリを更新

5. レポート:

   クリーンアップ完了:
     削除: omc:pr-123 (マージ済み)
     削除: omc:issue-42 (クローズ済み)
     保持: omc:feat-auth (アクティブ)
   

サブコマンド: status

目的: 現在のセッション情報を表示

手順:

1. 現在のセッションを検出 (tmux またはカレントワーキングディレクトリから):

   tmux display-message -p "#{session_name}" 2>/dev/null
   # または cwd が worktree 内にあるか確認
   

2. セッションメタデータを読み込む:

   cat .psm-session.json 2>/dev/null
   

3. ステータスを表示:

   現在のセッション: omc:pr-123
   タイプ: review
   PR: #123 - ウェブフックサポートの追加
   ブランチ: feature/webhooks
   作成: 2 時間前
   

---

エラーハンドリング

エラー	解決策
Worktree が既に存在	アタッチ、再作成、または中止を提案
PR が見つからない	URL/番号を確認、権限を確認
tmux がない	警告し、セッション作成をスキップ
gh CLI がない	インストール手順とともにエラー表示

Teleport コマンド

omc teleport コマンドは、完全な PSM セッションに代わる軽量な代替手段を提供します。tmux セッション管理なしで git worktree を作成します。迅速な隔離開発に最適です。

使用法

# Issue または PR 用に worktree を作成
omc teleport #123
omc teleport owner/repo#123
omc teleport https://github.com/owner/repo/issues/42

# 機能開発用に worktree を作成
omc teleport my-feature

# 既存の worktree 一覧
omc teleport list

# Worktree を削除
omc teleport remove issue/my-repo-123
omc teleport remove --force feat/my-repo-my-feature

オプション

フラグ	説明	デフォルト値
--worktree-dir	Worktree のベースディレクトリ	~/.psm/worktrees (または PSM_WORKTREE_DIR)
--main-branch	デフォルトのベースブランチ	プロジェクト設定による
--force	ダーティな worktree を強制的に削除	false

Teleport の設定

デフォルト値は ~/.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
  }
}

Teleport クリーンアップ

マージ済みの Teleport worktree をクリーンアップします:

# マージ済みの Teleport worktree を一覧表示
omc teleport cleanup --dry-run

# マージ済みの worktree を削除
omc teleport cleanup