Gestor de Sesiones de Proyecto

Habilidad del Gestor de Sesiones de Proyecto (PSM)

psm es el alias de compatibilidad para este punto de entrada canónico de la habilidad.

Inicio rápido (worktree-first): Comienza con omc teleport cuando quieras un worktree aislado para un issue/PR/funcionalidad antes de añadir cualquier orquestación de sesión tmux:

omc teleport #123          # Crear worktree para issue/PR
omc teleport my-feature    # Crear worktree para funcionalidad
omc teleport list          # Listar worktrees

Consulta Comando Teleport a continuación para más detalles.

Automatiza entornos de desarrollo aislados usando worktrees de git y sesiones tmux con Claude Code. Permite trabajar en paralelo en múltiples tareas, proyectos y repositorios.

Comando canónico: /oh-my-claudecode:project-session-manager (alias: /oh-my-claudecode:psm).

Comandos

Comando	Descripción	Ejemplo
review <ref>	Sesión de revisión de PR	/psm review omc#123
fix <ref>	Sesión de corrección de issue	/psm fix omc#42
feature <proj> <name>	Desarrollo de funcionalidad	/psm feature omc add-webhooks
list [project]	Listar sesiones activas	/psm list
attach <session>	Adjuntar a sesión	/psm attach omc:pr-123
kill <session>	Eliminar sesión	/psm kill omc:pr-123
cleanup	Limpiar fusionados/cerrados	/psm cleanup
status	Información de sesión actual	/psm status

Referencias de Proyecto

Formatos soportados:

• Alias: omc#123 (requiere ~/.psm/projects.json)
• Completo: owner/repo#123
• URL: https://github.com/owner/repo/pull/123
• Actual: #123 (usa el repositorio del directorio actual)

Configuración

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

Proveedores

PSM soporta múltiples proveedores de seguimiento de issues:

Proveedor	CLI Requerido	Formatos de Referencia	Comandos
GitHub (predeterminado)	gh	owner/repo#123, alias#123, URLs de GitHub	review, fix, feature
Jira	jira	PROJ-123 (si PROJ está configurado), alias#123	fix, feature

Configuración de Jira

Para usar Jira, agrega un alias con jira_project y provider: "jira":

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

Importante: El campo repo sigue siendo necesario para clonar el repositorio git. Jira rastrea issues, pero trabajas en un repositorio git.

Para repositorios que no son de GitHub, usa clone_url en su lugar:

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

Detección de Referencias de Jira

PSM solo reconoce el formato PROJ-123 como Jira cuando PROJ está explícitamente configurado como jira_project en tus alias. Esto evita falsos positivos de nombres de rama como FIX-123.

Ejemplos de Jira

# Corregir un issue de Jira (MYPROJ debe estar configurado)
psm fix MYPROJ-123

# Corregir usando alias (recomendado)
psm fix mywork#123

# Desarrollo de funcionalidad (funciona igual que GitHub)
psm feature mywork add-webhooks

# Nota: 'psm review' no es compatible con Jira (no hay concepto de PR)
# Usa 'psm fix' para issues de Jira

Configuración de CLI de Jira

Instala la CLI de Jira:

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

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

# Configurar (interactivo)
jira init

La CLI de Jira maneja la autenticación por separado de PSM.

Estructura de Directorios

~/.psm/
├── projects.json       # Alias de proyecto
├── sessions.json       # Registro de sesiones activas
└── worktrees/          # Almacenamiento de worktrees
    └── <project>/
        └── <type>-<id>/

Nomenclatura de Sesiones

El ID de sesión público (forma de dos puntos, ej. omc:pr-123) es el identificador visible para el usuario almacenado en sessions.json y usado con psm attach/psm kill. tmux reserva : y . para su sintaxis de destino session:window.pane y los reescribe silenciosamente, por lo que el nombre real de la sesión de tmux usa una forma segura para tmux donde esos caracteres se convierten en _ (issue #3528). PSM traduce el ID público al nombre seguro para tmux en cada límite de tmux; adjunta directamente con el nombre seguro para tmux.

Tipo	ID Público (psm attach/kill)	Sesión Tmux (tmux attach -t)	Directorio Worktree
Revisión de PR	omc:pr-123	psm_omc_pr-123	~/.psm/worktrees/omc/pr-123
Corrección de Issue	omc:issue-42	psm_omc_issue-42	~/.psm/worktrees/omc/issue-42
Funcionalidad	omc:feat-auth	psm_omc_feat-auth	~/.psm/worktrees/omc/feat-auth

---

Protocolo de Implementación

Cuando el usuario invoca un comando de PSM, sigue este protocolo:

Analizar Argumentos

Analiza {{ARGUMENTS}} para determinar:

1. Subcomando: review, fix, feature, list, attach, kill, cleanup, status
2. Referencia: project#number, URL o ID de sesión
3. Opciones: --branch, --base, --no-claude, --no-tmux, etc.

Subcomando: review <ref>

Propósito: Crear sesión de revisión de PR

Pasos:

1. Resolver referencia:

   # Leer alias de proyecto
   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
   
   # Analizar formato de ref: alias#num, owner/repo#num o URL
   # Extraer: project_alias, repo (owner/repo), pr_number, local_path
   

2. Obtener información del PR:

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

3. Asegurar que el repositorio local existe:

   # Si la ruta local no existe, clonar
   if [[ ! -d "$local_path" ]]; then
     git clone "https://github.com/$repo.git" "$local_path"
   fi
   

4. Crear worktree:

   worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
   
   # Obtener rama del PR
   cd "$local_path"
   git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
   
   # Crear worktree
   git worktree add "$worktree_path" "pr-$pr_number-review"
   

5. Crear metadatos de sesión:

   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. Actualizar registro de sesiones:

   # Añadir a ~/.psm/sessions.json
   

7. Crear sesión tmux (nombre seguro para tmux; :/. se traducen a _):

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

8. Iniciar Claude Code (a menos que se use --no-claude):

   # --dangerously-skip-permissions evita la solicitud "¿Confías en este directorio?"
   # y las solicitudes repetidas de aprobación de herramientas que detendrían la sesión (issue #2508).
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" "claude --dangerously-skip-permissions" Enter
   
   # Después de que claude arranque (PSM_CLAUDE_STARTUP_DELAY, predeterminado 5s), entrega la tarea.
   # Usa -l (literal) para que los caracteres especiales no sean malinterpretados por tmux.
   sleep "${PSM_CLAUDE_STARTUP_DELAY:-5}"
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" -l \
     "Revisa el PR #$pr_number: \"$pr_title\" por @$pr_author ($head_branch → $base_branch). URL: $pr_url." Enter
   

9. Mostrar información de la sesión:

   ¡Sesión lista!
   
     ID: omc:pr-123
     Worktree: ~/.psm/worktrees/omc/pr-123
     Tmux: psm_omc_pr-123
   
   Para adjuntar: tmux attach -t psm_omc_pr-123   (o: psm attach omc:pr-123)
   

Subcomando: fix <ref>

Propósito: Crear sesión de corrección de issue

Pasos:

1. Resolver referencia (igual que review)

2. Obtener información del issue:

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

3. Crear rama de funcionalidad:

   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. Crear worktree:

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

5. Crear metadatos de sesión (similar a review, type="fix")

6. Actualizar registro, crear tmux, iniciar claude: Igual que review, pero pasar contexto del issue como instrucción inicial de la tarea:

   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" "claude --dangerously-skip-permissions" Enter
   # Después de que claude arranque, entregar la tarea (ver PSM_CLAUDE_STARTUP_DELAY):
   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" -l \
     "Corrige el issue #$issue_number: \"$issue_title\". URL: $issue_url. Rama: $branch_name." Enter
   

Subcomando: feature <project> <name>

Propósito: Iniciar desarrollo de funcionalidad

Pasos:

1. Resolver proyecto (desde alias o ruta)

2. Crear rama de funcionalidad:

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

3. Crear worktree:

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

4. Crear sesión, tmux, iniciar claude con contexto de funcionalidad como instrucción inicial:

   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 \
     "Implementa la funcionalidad \"$feature_name\" para el proyecto $project. Rama: $branch_name." Enter
   

Subcomando: list [project]

Propósito: Listar sesiones activas

Pasos:

1. Leer registro de sesiones:

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

2. Verificar sesiones tmux:

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

3. Verificar worktrees:

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

4. Formatear salida:

   Sesiones PSM Activas:
   
   ID                 | Tipo    | Estado    | Worktree
   -------------------|---------|-----------|---------------------------
   omc:pr-123        | review  | activo    | ~/.psm/worktrees/omc/pr-123
   omc:issue-42      | fix     | separado  | ~/.psm/worktrees/omc/issue-42
   

Subcomando: attach <session>

Propósito: Adjuntar a sesión existente

Pasos:

1. Analizar ID de sesión: project:type-number

2. Verificar que la sesión existe:

   tmux has-session -t "psm_${session_id//[.:]/_}" 2>/dev/null   # traducir id público a nombre seguro para tmux
   

3. Adjuntar:

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

Subcomando: kill <session>

Propósito: Eliminar sesión y limpiar

Pasos:

1. Matar sesión tmux:

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

2. Eliminar 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. Actualizar registro:

   # Eliminar de sessions.json
   

Subcomando: cleanup

Propósito: Limpiar PRs fusionados e issues cerrados

Pasos:

1. Leer todas las sesiones

2. Para cada sesión de PR, verificar si está fusionada:

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

3. Para cada sesión de issue, verificar si está cerrada:

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

4. Limpiar sesiones fusionadas/cerradas:

   • Matar sesión tmux
   • Eliminar worktree
   • Actualizar registro

5. Informar:

   Limpieza completada:
     Eliminado: omc:pr-123 (fusionado)
     Eliminado: omc:issue-42 (cerrado)
     Conservado: omc:feat-auth (activo)
   

Subcomando: status

Propósito: Mostrar información de la sesión actual

Pasos:

1. Detectar sesión actual desde tmux o cwd:

   tmux display-message -p "#{session_name}" 2>/dev/null
   # o verificar si cwd está dentro de un worktree
   

2. Leer metadatos de sesión:

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

3. Mostrar estado:

   Sesión Actual: omc:pr-123
   Tipo: review
   PR: #123 - Añadir soporte para webhooks
   Rama: feature/webhooks
   Creado: hace 2 horas
   

---

Manejo de Errores

Error	Resolución
Worktree existe	Ofrecer: adjuntar, recrear o abortar
PR no encontrado	Verificar URL/número, comprobar permisos
Sin tmux	Advertir y omitir creación de sesión
Sin CLI gh	Error con instrucciones de instalación

Comando Teleport

El comando omc teleport proporciona una alternativa ligera a las sesiones completas de PSM. Crea worktrees de git sin gestión de sesiones tmux, ideal para desarrollo rápido y aislado.

Uso

# Crear worktree para un issue o PR
omc teleport #123
omc teleport owner/repo#123
omc teleport https://github.com/owner/repo/issues/42

# Crear worktree para una funcionalidad
omc teleport my-feature

# Listar worktrees existentes
omc teleport list

# Eliminar un worktree
omc teleport remove issue/my-repo-123
omc teleport remove --force feat/my-repo-my-feature

Opciones

Flag	Descripción	Predeterminado
--worktr [truncado]