Project Session Manager (PSM)

Project Session Manager (PSM) Skill

psm ist der Kompatibilitäts-Alias für diesen kanonischen Skill-Einstiegspunkt.

Schnellstart (Worktree-first): Beginnen Sie mit omc teleport, wenn Sie ein isoliertes Issue/PR/Feature-Worktree erstellen möchten, bevor Sie eine tmux/Sitzungs-Orchestrierung hinzufügen:

omc teleport #123          # Worktree für Issue/PR erstellen
omc teleport my-feature    # Worktree für Feature erstellen
omc teleport list          # Worktrees auflisten

Siehe Teleport-Befehl unten für Details.

Automatisieren Sie isolierte Entwicklungsumgebungen mit Git-Worktrees und tmux-Sitzungen mit Claude Code. Ermöglicht paralleles Arbeiten an mehreren Aufgaben, Projekten und Repositories.

Kanonischer Slash-Befehl: /oh-my-claudecode:project-session-manager (Alias: /oh-my-claudecode:psm).

Befehle

Befehl	Beschreibung	Beispiel
review <ref>	PR-Review-Sitzung	/psm review omc#123
fix <ref>	Issue-Fix-Sitzung	/psm fix omc#42
feature <proj> <name>	Feature-Entwicklung	/psm feature omc add-webhooks
list [project]	Aktive Sitzungen auflisten	/psm list
attach <session>	An Sitzung anhängen	/psm attach omc:pr-123
kill <session>	Sitzung beenden	/psm kill omc:pr-123
cleanup	Zusammengeführte/geschlossene bereinigen	/psm cleanup
status	Aktuelle Sitzungsinfo anzeigen	/psm status

Projektverweise

Unterstützte Formate:

• Alias: omc#123 (erfordert ~/.psm/projects.json)
• Vollständig: owner/repo#123
• URL: https://github.com/owner/repo/pull/123
• Aktuell: #123 (verwendet das Repository des aktuellen Verzeichnisses)

Konfiguration

Projekt-Aliase (~/.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
  }
}

Provider

PSM unterstützt mehrere Issue-Tracking-Provider:

Provider	Erforderliche CLI	Referenzformate	Befehle
GitHub (Standard)	gh	owner/repo#123, alias#123, GitHub-URLs	review, fix, feature
Jira	jira	PROJ-123 (wenn PROJ konfiguriert), alias#123	fix, feature

Jira-Konfiguration

Um Jira zu verwenden, fügen Sie einen Alias mit jira_project und provider: "jira" hinzu:

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

Wichtig: Das Feld repo ist weiterhin erforderlich, um das Git-Repository zu klonen. Jira verfolgt Issues, aber Sie arbeiten in einem Git-Repo.

Verwenden Sie für Nicht-GitHub-Repos clone_url stattdessen:

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

Jira-Referenzerkennung

PSM erkennt das Format PROJ-123 nur dann als Jira, wenn PROJ explizit als jira_project in Ihren Aliasen konfiguriert ist. Dies verhindert Fehlalarme durch Branchnamen wie FIX-123.

Jira-Beispiele

# Ein Jira-Issue beheben (MYPROJ muss konfiguriert sein)
psm fix MYPROJ-123

# Mit Alias beheben (empfohlen)
psm fix mywork#123

# Feature-Entwicklung (funktioniert wie bei GitHub)
psm feature mywork add-webhooks

# Hinweis: 'psm review' wird für Jira nicht unterstützt (kein PR-Konzept)
# Verwenden Sie 'psm fix' für Jira-Issues

Jira-CLI-Setup

Installieren Sie die Jira-CLI:

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

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

# Konfigurieren (interaktiv)
jira init

Die Jira-CLI behandelt die Authentifizierung getrennt von PSM.

Verzeichnisstruktur

~/.psm/
├── projects.json       # Projekt-Aliase
├── sessions.json       # Aktive Sitzungsregistrierung
└── worktrees/          # Worktree-Speicher
    └── <project>/
        └── <type>-<id>/

Sitzungsbenennung

Die öffentliche Sitzungs-ID (Doppelpunktform, z. B. omc:pr-123) ist die menschenlesbare Kennung, die in sessions.json gespeichert und mit psm attach/psm kill verwendet wird. tmux reserviert : und . für seine session:window.pane-Zielsyntax und schreibt sie stillschweigend um. Daher verwendet der tatsächliche tmux-Sitzungsname eine tmux-sichere Form, in der diese Zeichen zu _ werden (Issue #3528). PSM übersetzt die öffentliche ID an jeder tmux-Grenze in den tmux-sicheren Namen; hängen Sie direkt mit dem tmux-sicheren Namen an.

Typ	Öffentliche ID (psm attach/kill)	Tmux-Sitzung (tmux attach -t)	Worktree-Verzeichnis
PR-Review	omc:pr-123	psm_omc_pr-123	~/.psm/worktrees/omc/pr-123
Issue-Fix	omc:issue-42	psm_omc_issue-42	~/.psm/worktrees/omc/issue-42
Feature	omc:feat-auth	psm_omc_feat-auth	~/.psm/worktrees/omc/feat-auth

---

Implementierungsprotokoll

Wenn der Benutzer einen PSM-Befehl aufruft, befolgen Sie dieses Protokoll:

Argumente parsen

Parsen Sie {{ARGUMENTS}}, um Folgendes zu bestimmen:

1. Unterbefehl: review, fix, feature, list, attach, kill, cleanup, status
2. Referenz: project#number, URL oder Sitzungs-ID
3. Optionen: --branch, --base, --no-claude, --no-tmux, usw.

Unterbefehl: review <ref>

Zweck: PR-Review-Sitzung erstellen

Schritte:

1. Referenz auflösen:

   # Projekt-Aliase lesen
   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
   
   # Referenzformat parsen: alias#num, owner/repo#num oder URL
   # Extrahieren: project_alias, repo (owner/repo), pr_number, local_path
   

2. PR-Info abrufen:

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

3. Sicherstellen, dass lokales Repo existiert:

   # Wenn lokaler Pfad nicht existiert, klonen
   if [[ ! -d "$local_path" ]]; then
     git clone "https://github.com/$repo.git" "$local_path"
   fi
   

4. Worktree erstellen:

   worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
   
   # PR-Branch abrufen
   cd "$local_path"
   git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
   
   # Worktree erstellen
   git worktree add "$worktree_path" "pr-$pr_number-review"
   

5. Sitzungsmetadaten erstellen:

   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. Sitzungsregistrierung aktualisieren:

   # Zu ~/.psm/sessions.json hinzufügen
   

7. tmux-Sitzung erstellen (tmux-sicherer Name; :/. werden in _ übersetzt):

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

8. Claude Code starten (außer mit --no-claude):

   # --dangerously-skip-permissions verhindert die „Vertrauen Sie diesem Verzeichnis?“-Aufforderung
   # und wiederholte Tool-Genehmigungsaufforderungen, die die Sitzung blockieren (Issue #2508).
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" "claude --dangerously-skip-permissions" Enter
   
   # Nachdem Claude gestartet ist (PSM_CLAUDE_STARTUP_DELAY, Standard 5s), die Aufgabe übergeben.
   # Verwenden Sie -l (literal), damit Sonderzeichen nicht von tmux fehlinterpretiert werden.
   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. Sitzungsinfo ausgeben:

   Sitzung bereit!
   
     ID: omc:pr-123
     Worktree: ~/.psm/worktrees/omc/pr-123
     Tmux: psm_omc_pr-123
   
   Zum Anhängen: tmux attach -t psm_omc_pr-123   (oder: psm attach omc:pr-123)
   

Unterbefehl: fix <ref>

Zweck: Issue-Fix-Sitzung erstellen

Schritte:

1. Referenz auflösen (wie bei review)

2. Issue-Info abrufen:

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

3. Feature-Branch erstellen:

   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 erstellen:

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

5. Sitzungsmetadaten erstellen (ähnlich wie review, type="fix")

6. Registrierung aktualisieren, tmux erstellen, claude starten: Wie bei review, aber Issue-Kontext als anfängliche Aufgabenaufforderung übergeben:

   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" "claude --dangerously-skip-permissions" Enter
   # Nachdem Claude gestartet ist, die Aufgabe übergeben (siehe 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
   

Unterbefehl: feature <project> <name>

Zweck: Feature-Entwicklung starten

Schritte:

1. Projekt auflösen (aus Alias oder Pfad)

2. Feature-Branch erstellen:

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

3. Worktree erstellen:

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

4. Sitzung, tmux, claude mit Feature-Kontext als anfängliche Aufforderung erstellen:

   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
   

Unterbefehl: list [project]

Zweck: Aktive Sitzungen auflisten

Schritte:

1. Sitzungsregistrierung lesen:

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

2. tmux-Sitzungen prüfen:

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

3. Worktrees prüfen:

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

4. Ausgabe formatieren:

   Aktive PSM-Sitzungen:
   
   ID                 | Typ    | Status   | Worktree
   -------------------|---------|----------|---------------------------
   omc:pr-123        | review  | active   | ~/.psm/worktrees/omc/pr-123
   omc:issue-42      | fix     | detached | ~/.psm/worktrees/omc/issue-42
   

Unterbefehl: attach <session>

Zweck: An bestehende Sitzung anhängen

Schritte:

1. Sitzungs-ID parsen: project:type-number

2. Vorhandensein der Sitzung überprüfen:

   tmux has-session -t "psm_${session_id//[.:]/_}" 2>/dev/null   # öffentliche ID in tmux-sicheren Namen übersetzen
   

3. Anhängen:

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

Unterbefehl: kill <session>

Zweck: Sitzung beenden und bereinigen

Schritte:

1. tmux-Sitzung beenden:

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

2. Worktree entfernen:

   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. Registrierung aktualisieren:

   # Aus sessions.json entfernen
   

Unterbefehl: cleanup

Zweck: Zusammengeführte PRs und geschlossene Issues bereinigen

Schritte:

1. Alle Sitzungen lesen

2. Für jede PR-Sitzung prüfen, ob zusammengeführt:

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

3. Für jede Issue-Sitzung prüfen, ob geschlossen:

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

4. Zusammengeführte/geschlossene Sitzungen bereinigen:

   • tmux-Sitzung beenden
   • Worktree entfernen
   • Registrierung aktualisieren

5. Bericht:

   Bereinigung abgeschlossen:
     Entfernt: omc:pr-123 (merged)
     Entfernt: omc:issue-42 (closed)
     Behalten: omc:feat-auth (active)
   

Unterbefehl: status

Zweck: Aktuelle Sitzungsinfo anzeigen

Schritte:

1. Aktuelle Sitzung erkennen über tmux oder cwd:

   tmux display-message -p "#{session_name}" 2>/dev/null
   # oder prüfen, ob cwd innerhalb eines Worktrees liegt
   

2. Sitzungsmetadaten lesen:

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

3. Status anzeigen:

   Aktuelle Sitzung: omc:pr-123
   Typ: review
   PR: #123 - Add webhook support
   Branch: feature/webhooks
   Erstellt: vor 2 Stunden
   

---

Fehlerbehandlung

Fehler	Lösung
Worktree existiert	Angebot: anhängen, neu erstellen oder abbrechen
PR nicht gefunden	URL/Nummer überprüfen, Berechtigungen prüfen
Kein tmux	Warnen und Sitzungserstellung überspringen
Keine gh-CLI	Fehler mit Installationsanleitung

Teleport-Befehl

Der Befehl omc teleport bietet eine leichtgewichtige Alternative zu vollständigen PSM-Sitzungen. Er erstellt Git-Worktrees ohne tmux-Sitzungsverwaltung – ideal für schnelle, isolierte Entwicklung.

Verwendung

# Worktree für ein Issue oder PR erstellen
omc teleport #123
omc teleport owner/repo#123
omc teleport https://github.com/owner/repo/issues/42

# Worktree für ein Feature erstellen
omc teleport my-feature

# Vorhandene Worktrees auflisten
omc teleport list

# Worktree entfernen
omc teleport remove issue/my-repo-123
omc teleport remove --force feat/my-repo-my-feature

Optionen

Flag	Beschreibung	Standard
--worktr
…

[abgeschnitten für Übersetzung]

}