Gestionnaire de Sessions Projet (PSM)

Compétence Gestionnaire de Sessions Projet (PSM)

psm est l'alias de compatibilité pour ce point d'entrée canonique de la compétence.

Démarrage rapide (worktree-first) : Commencez avec omc teleport lorsque vous voulez un worktree isolé pour une issue/PR/fonctionnalité sans orchestration tmux/session :

omc teleport #123          # Créer un worktree pour une issue/PR
omc teleport ma-fonctionnalité    # Créer un worktree pour une fonctionnalité
omc teleport list          # Lister les worktrees

Voir Commande Teleport ci-dessous pour les détails.

Automatisez les environnements de développement isolés en utilisant les git worktrees et les sessions tmux avec Claude Code. Permet un travail parallèle sur plusieurs tâches, projets et dépôts.

Commande barre oblique canonique : /oh-my-claudecode:project-session-manager (alias : /oh-my-claudecode:psm).

Commandes

Commande	Description	Exemple
review <ref>	Session de revue de PR	/psm review omc#123
fix <ref>	Session de correction d'issue	/psm fix omc#42
feature <proj> <nom>	Développement de fonctionnalité	/psm feature omc ajouter-webhooks
list [projet]	Lister les sessions actives	/psm list
attach <session>	S'attacher à une session	/psm attach omc:pr-123
kill <session>	Tuer une session	/psm kill omc:pr-123
cleanup	Nettoyer les éléments fusionnés/fermés	/psm cleanup
status	Informations sur la session courante	/psm status

Références Projet

Formats supportés :

• Alias : omc#123 (nécessite ~/.psm/projects.json)
• Complet : propriétaire/dépôt#123
• URL : https://github.com/propriétaire/dépôt/pull/123
• Courant : #123 (utilise le dépôt du répertoire courant)

Configuration

Alias Projet (~/.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
  }
}

Fournisseurs

PSM supporte plusieurs fournisseurs de suivi d'issues :

Fournisseur	CLI Requis	Formats de Référence	Commandes
GitHub (défaut)	gh	propriétaire/dépôt#123, alias#123, URLs GitHub	review, fix, feature
Jira	jira	PROJ-123 (si PROJ configuré), alias#123	fix, feature

Configuration Jira

Pour utiliser Jira, ajoutez un alias avec jira_project et provider : "jira" :

{
  "aliases": {
    "montravail": {
      "jira_project": "MYPROJ",
      "repo": "masociete/mon-projet",
      "local": "~/Workspace/mon-projet",
      "default_base": "develop",
      "provider": "jira"
    }
  }
}

Important : Le champ repo est toujours requis pour cloner le dépôt git. Jira suit les issues, mais vous travaillez dans un dépôt git.

Pour les dépôts non GitHub, utilisez clone_url à la place :

{
  "aliases": {
    "prive": {
      "jira_project": "PRIV",
      "clone_url": "[email protected]:equipe/depot.git",
      "local": "~/Workspace/depot",
      "provider": "jira"
    }
  }
}

Détection de Référence Jira

PSM ne reconnaît le format PROJ-123 comme Jira que lorsque PROJ est explicitement configuré comme jira_project dans vos alias. Cela évite les faux positifs provenant de noms de branche comme FIX-123.

Exemples Jira

# Corriger une issue Jira (MYPROJ doit être configuré)
psm fix MYPROJ-123

# Corriger en utilisant un alias (recommandé)
psm fix montravail#123

# Développement de fonctionnalité (fonctionne comme pour GitHub)
psm feature montravail ajouter-webhooks

# Remarque : 'psm review' n'est pas supporté pour Jira (pas de concept de PR)
# Utilisez 'psm fix' pour les issues Jira

Configuration CLI Jira

Installez le CLI Jira :

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

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

# Configurer (interactif)
jira init

Le CLI Jira gère l'authentification séparément de PSM.

Structure des Répertoires

~/.psm/
├── projects.json       # Alias de projet
├── sessions.json       # Registre des sessions actives
└── worktrees/          # Stockage des worktrees
    └── <projet>/
        └── <type>-<id>/

Nommage des Sessions

L'ID de session publique (forme avec deux-points, ex. omc:pr-123) est l'identifiant visible par l'humain stocké dans sessions.json et utilisé avec psm attach/psm kill. tmux réserve : et . pour sa syntaxe cible session:fenêtre.panneau et les réécrit silencieusement, donc le nom de session tmux réel utilise une forme compatible tmux où ces caractères deviennent _ (issue #3528). PSM translate l'ID public vers le nom compatible tmux à chaque frontière tmux ; attachez directement avec le nom compatible tmux.

Type	ID Public (psm attach/kill)	Session Tmux (tmux attach -t)	Répertoire Worktree
Revue PR	omc:pr-123	psm_omc_pr-123	~/.psm/worktrees/omc/pr-123
Correction Issue	omc:issue-42	psm_omc_issue-42	~/.psm/worktrees/omc/issue-42
Fonctionnalité	omc:feat-auth	psm_omc_feat-auth	~/.psm/worktrees/omc/feat-auth

---

Protocole d'Implémentation

Lorsque l'utilisateur invoque une commande PSM, suivez ce protocole :

Analyser les Arguments

Analysez {{ARGUMENTS}} pour déterminer :

1. Sous-commande : review, fix, feature, list, attach, kill, cleanup, status
2. Référence : projet#nombre, URL, ou ID de session
3. Options : --branch, --base, --no-claude, --no-tmux, etc.

Sous-commande : review <ref>

Objectif : Créer une session de revue de PR

Étapes :

1. Résoudre la référence :

   # Lire les alias de projet
   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
   
   # Analyser le format de réf : alias#num, propriétaire/dépôt#num, ou URL
   # Extraire : alias_projet, dépôt (propriétaire/dépôt), num_pr, chemin_local
   

2. Récupérer les infos de la PR :

   gh pr view <numéro_pr> --repo <dépôt> --json number,title,author,headRefName,baseRefName,body,files,url
   

3. S'assurer que le dépôt local existe :

   # Si le chemin local n'existe pas, cloner
   if [[ ! -d "$chemin_local" ]]; then
     git clone "https://github.com/$dépôt.git" "$chemin_local"
   fi
   

4. Créer un worktree :

   chemin_worktree="$HOME/.psm/worktrees/$alias_projet/pr-$num_pr"
   
   # Récupérer la branche PR
   cd "$chemin_local"
   git fetch origin "pull/$num_pr/head:pr-$num_pr-review"
   
   # Créer un worktree
   git worktree add "$chemin_worktree" "pr-$num_pr-review"
   

5. Créer les métadonnées de session :

   cat > "$chemin_worktree/.psm-session.json" << EOF
   {
     "id": "$alias_projet:pr-$num_pr",
     "type": "review",
     "project": "$alias_projet",
     "ref": "pr-$num_pr",
     "branch": "<branche_entete>",
     "base": "<branche_base>",
     "created_at": "$(date -Iseconds)",
     "tmux_session": "psm_${alias_projet}_pr-$num_pr",
     "worktree_path": "$chemin_worktree",
     "source_repo": "$chemin_local",
     "github": {
       "pr_number": $num_pr,
       "pr_title": "<titre>",
       "pr_author": "<auteur>",
       "pr_url": "<url>"
     },
     "state": "active"
   }
   EOF
   

6. Mettre à jour le registre des sessions :

   # Ajouter à ~/.psm/sessions.json
   

7. Créer une session tmux (nom compatible tmux ; :/. sont traduits en _) :

   tmux new-session -d -s "psm_${alias_projet}_pr-$num_pr" -c "$chemin_worktree"
   

8. Lancer Claude Code (sauf si --no-claude) :

   # --dangerously-skip-permissions empêche l'invite "Faites-vous confiance à ce répertoire ?"
   # et les invites répétées d'approbation d'outils qui bloquent la session (issue #2508).
   tmux send-keys -t "psm_${alias_projet}_pr-$num_pr" "claude --dangerously-skip-permissions" Entrée
   
   # Après le démarrage de claude (PSM_CLAUDE_STARTUP_DELAY, défaut 5s), délivrer la tâche.
   # Utilisez -l (littéral) pour que les caractères spéciaux ne soient pas mal interprétés par tmux.
   sleep "${PSM_CLAUDE_STARTUP_DELAY:-5}"
   tmux send-keys -t "psm_${alias_projet}_pr-$num_pr" -l \
     "Revue de la PR #$num_pr : \"$titre_pr\" par @$auteur_pr ($branche_entête → $branche_base). URL : $url_pr." Entrée
   

9. Afficher les informations de session :

   Session prête !
   
     ID : omc:pr-123
     Worktree : ~/.psm/worktrees/omc/pr-123
     Tmux : psm_omc_pr-123
   
   Pour s'attacher : tmux attach -t psm_omc_pr-123   (ou : psm attach omc:pr-123)
   

Sous-commande : fix <ref>

Objectif : Créer une session de correction d'issue

Étapes :

1. Résoudre la référence (comme pour review)

2. Récupérer les informations de l'issue :

   gh issue view <numéro_issue> --repo <dépôt> --json number,title,body,labels,url
   

3. Créer une branche de fonctionnalité :

   cd "$chemin_local"
   git fetch origin main
   nom_branche="fix/$num_issue-$(echo "$titre" | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | head -c 30)"
   git checkout -b "$nom_branche" origin/main
   

4. Créer un worktree :

   chemin_worktree="$HOME/.psm/worktrees/$alias_projet/issue-$num_issue"
   git worktree add "$chemin_worktree" "$nom_branche"
   

5. Créer les métadonnées de session (similaire à review, type="fix")

6. Mettre à jour le registre, créer tmux, lancer claude : Identique à review, mais passer le contexte de l'issue comme invite de tâche initiale :

   tmux send-keys -t "psm_${alias_projet}_issue-$num_issue" "claude --dangerously-skip-permissions" Entrée
   # Après le démarrage de claude, délivrer la tâche (voir PSM_CLAUDE_STARTUP_DELAY) :
   tmux send-keys -t "psm_${alias_projet}_issue-$num_issue" -l \
     "Corriger l'issue #$num_issue : \"$titre_issue\". URL : $url_issue. Branche : $nom_branche." Entrée
   

Sous-commande : feature <projet> <nom>

Objectif : Démarrer le développement d'une fonctionnalité

Étapes :

1. Résoudre le projet (à partir d'un alias ou d'un chemin)

2. Créer une branche de fonctionnalité :

   cd "$chemin_local"
   git fetch origin main
   nom_branche="feature/$nom_fonctionnalité"
   git checkout -b "$nom_branche" origin/main
   

3. Créer un worktree :

   chemin_worktree="$HOME/.psm/worktrees/$alias_projet/feat-$nom_fonctionnalité"
   git worktree add "$chemin_worktree" "$nom_branche"
   

4. Créer la session, tmux, lancer claude avec le contexte de la fonctionnalité comme invite initiale :

   tmux send-keys -t "psm_${alias_projet}_feat-$nom_fonctionnalité" "claude --dangerously-skip-permissions" Entrée
   tmux send-keys -t "psm_${alias_projet}_feat-$nom_fonctionnalité" -l \
     "Implémenter la fonctionnalité \"$nom_fonctionnalité\" pour le projet $projet. Branche : $nom_branche." Entrée
   

Sous-commande : list [projet]

Objectif : Lister les sessions actives

Étapes :

1. Lire le registre des sessions :

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

2. Vérifier les sessions tmux :

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

3. Vérifier les worktrees :

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

4. Formater la sortie :

   Sessions PSM Actives :
   
   ID                 | Type    | Statut   | Worktree
   -------------------|---------|----------|---------------------------
   omc:pr-123        | review  | actif   | ~/.psm/worktrees/omc/pr-123
   omc:issue-42      | fix     | détaché | ~/.psm/worktrees/omc/issue-42
   

Sous-commande : attach <session>

Objectif : S'attacher à une session existante

Étapes :

1. Analyser l'ID de session : projet:type-numéro

2. Vérifier que la session existe :

   tmux has-session -t "psm_${session_id//[.:]/_}" 2>/dev/null   # traduire l'id public en nom compatible tmux
   

3. S'attacher :

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

Sous-commande : kill <session>

Objectif : Tuer une session et nettoyer

Étapes :

1. Tuer la session tmux :

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

2. Supprimer le worktree :

   chemin_worktree=$(jq -r ".sessions[\"$session_id\"].worktree" ~/.psm/sessions.json)
   dépôt_source=$(jq -r ".sessions[\"$session_id\"].source_repo" ~/.psm/sessions.json)
   
   cd "$dépôt_source"
   git worktree remove "$chemin_worktree" --force
   

3. Mettre à jour le registre :

   # Supprimer de sessions.json
   

Sous-commande : cleanup

Objectif : Nettoyer les PR fusionnées et les issues fermées

Étapes :

1. Lire toutes les sessions

2. Pour chaque session PR, vérifier si elle est fusionnée :

   gh pr view <numéro_pr> --repo <dépôt> --json merged,state
   

3. Pour chaque session issue, vérifier si elle est fermée :

   gh issue view <numéro_issue> --repo <dépôt> --json closed,state
   

4. Nettoyer les sessions fusionnées/fermées :

   • Tuer la session tmux
   • Supprimer le worktree
   • Mettre à jour le registre

5. Rapport :

   Nettoyage terminé :
     Supprimé : omc:pr-123 (fusionné)
     Supprimé : omc:issue-42 (fermé)
     Conservé : omc:feat-auth (actif)
   

Sous-commande : status

Objectif : Afficher les informations de la session courante

Étapes :

1. Détecter la session courante à partir de tmux ou du répertoire de travail courant :

   tmux display-message -p "#{session_name}" 2>/dev/null
   # ou vérifier si le répertoire de travail courant est dans un worktree
   

2. Lire les métadonnées de session :

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

3. Afficher le statut :

   Session Courante : omc:pr-123
   Type : review
   PR : #123 - Ajouter le support des webhooks
   Branche : feature/webhooks
   Créée : il y a 2 heures
   

---

Gestion des Erreurs

Erreur	Résolution
Le worktree existe	Proposer : attacher, recréer ou abandonner
PR non trouvée	Vérifier l'URL/le numéro, vérifier les permissions
Pas de tmux	Avertir et ignorer la création de session
Pas de CLI gh	Erreur avec instructions d'installation

Commande Teleport

La commande omc teleport offre une alternative légère aux sessions PSM complètes. Elle crée des git worktrees sans gestion de session tmux — idéal pour un développement rapide et isolé.

Utilisation

# Créer un worktree pour une issue ou une PR
omc teleport #123
omc teleport propriétaire/dépôt#123
omc teleport https://github.com/propriétaire/dépôt/issues/42

# Créer un worktree pour une fonctionnalité
omc teleport ma-fonctionnalité

# Lister les worktrees existants
omc teleport list

# Supprimer un worktree
omc teleport remove issue/mon-depot-123
omc teleport remove --force feat/mon-depot-ma-fonctionnalité

Options

Option	Description	Défaut
--worktree-dir <chemin>	Répertoire de destination pour le worktree	~/.psm/worktrees
--base <branche>	Branche de base pour le worktree	main (ou develop pour Jira)
--force	Forcer la suppression d'un worktree non nettoyé	false

Exemples

# Worktree avec une branche de base personnalisée
omc teleport --base develop #123

# Supprimer un worktree
omc teleport remove feat/mon-depot-ma-fonctionnalité

---

Intégration Continue

PSM peut être intégré dans des pipelines CI/CD :

# Exemple GitHub Actions
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configurer PSM
        run: |
          mkdir -p ~/.psm
          echo '{"aliases":{"monprojet":{"repo":"${{ github.repository }}","local":"${{ github.workspace }}"}}}' > ~/.psm/projects.json
      - name: Créer session PSM
        run: |
          # Utiliser psm pour créer un environnement de travail
          psm review ${{ github.repository }}/${{ github.event.pull_request.number }}

Dépannage

La session tmux ne démarre pas

Vérifiez les points suivants :

1. tmux est-il installé ? tmux --version
2. Le répertoire du worktree existe-t-il ? ls -la ~/.psm/worktrees/
3. Les permissions sont-elles correctes ? chmod -R 755 ~/.psm/

Claude Code ne répond pas

1. Vérifiez que --dangerously-skip-permissions est utilisé
2. Augmentez PSM_CLAUDE_STARTUP_DELAY si Claude met du temps à démarrer
3. Vérifiez les logs avec tmux capture-pane -t psm_* -p

Problèmes de worktree git

# Nettoyer manuellement les worktrees
cd ~/.psm/worktrees/monprojet
rm -rf pr-123
git worktree prune

Références

• Documentation git worktree : https://git-scm.com/docs/git-worktree
• Documentation tmux : https://github.com/tmux/tmux/wiki
• Documentation Jira CLI : https://github.com/ankitpokhrel/jira-cli