Gerenciador de Sessão de Projeto

Skill do Gerenciador de Sessão de Projeto (PSM)

psm é o alias de compatibilidade para este ponto de entrada canônico da skill.

Início Rápido (worktree-first): Comece com omc teleport quando quiser um worktree isolado de issue/PR/funcionalidade antes de adicionar qualquer orquestração de tmux/sessão:

omc teleport #123          # Criar worktree para issue/PR
omc teleport minha-feature # Criar worktree para funcionalidade
omc teleport list          # Listar worktrees

Veja o Comando Teleport abaixo para detalhes.

Automatize ambientes de desenvolvimento isolados usando git worktrees e sessões tmux com o Claude Code. Permite trabalho paralelo em múltiplas tarefas, projetos e repositórios.

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

Comandos

Comando	Descrição	Exemplo
review <ref>	Sessão de revisão de PR	/psm review omc#123
fix <ref>	Sessão de correção de issue	/psm fix omc#42
feature <proj> <nome>	Desenvolvimento de funcionalidade	/psm feature omc add-webhooks
list [project]	Listar sessões ativas	/psm list
attach <sessão>	Anexar a sessão	/psm attach omc:pr-123
kill <sessão>	Matar sessão	/psm kill omc:pr-123
cleanup	Limpar mesclados/fechados	/psm cleanup
status	Informações da sessão atual	/psm status

Referências de Projeto

Formatos suportados:

• Alias: omc#123 (requer ~/.psm/projects.json)
• Completo: owner/repo#123
• URL: https://github.com/owner/repo/pull/123
• Atual: #123 (usa o repositório do diretório atual)

Configuração

Apelidos de Projeto (~/.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
  }
}

Provedores

O PSM suporta múltiplos provedores de rastreamento de issues:

Provedor	CLI Necessário	Formatos de Referência	Comandos
GitHub (padrão)	gh	owner/repo#123, alias#123, URLs do GitHub	review, fix, feature
Jira	jira	PROJ-123 (se PROJ configurado), alias#123	fix, feature

Configuração Jira

Para usar Jira, adicione um alias com jira_project e provider: "jira":

{
  "aliases": {
    "meutrabalho": {
      "jira_project": "MEUPROJ",
      "repo": "minhaempresa/meu-projeto",
      "local": "~/Workspace/meu-projeto",
      "default_base": "develop",
      "provider": "jira"
    }
  }
}

Importante: O campo repo ainda é necessário para clonar o repositório git. O Jira rastreia issues, mas você trabalha em um repositório git.

Para repositórios não-GitHub, use clone_url em vez disso:

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

Detecção de Referência Jira

O PSM só reconhece o formato PROJ-123 como Jira quando PROJ está explicitamente configurado como jira_project em seus aliases. Isso evita falsos positivos de nomes de branch como FIX-123.

Exemplos Jira

# Corrigir uma issue Jira (MEUPROJ deve estar configurado)
psm fix MEUPROJ-123

# Corrigir usando alias (recomendado)
psm fix meutrabalho#123

# Desenvolvimento de funcionalidade (funciona igual ao GitHub)
psm feature meutrabalho add-webhooks

# Nota: 'psm review' não é suportado para Jira (nenhum conceito de PR)
# Use 'psm fix' para issues Jira

Configuração CLI Jira

Instale o Jira CLI:

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

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

# Configurar (interativo)
jira init

O Jira CLI lida com a autenticação separadamente do PSM.

Estrutura de Diretórios

~/.psm/
├── projects.json       # Apelidos de projeto
├── sessions.json       # Registro de sessão ativa
└── worktrees/          # Armazenamento de worktree
    └── <project>/
        └── <tipo>-<id>/

Nomenclatura de Sessão

O ID de sessão público (forma de dois pontos, ex.: omc:pr-123) é o identificador voltado para humanos armazenado em sessions.json e usado com psm attach/psm kill. O tmux reserva : e . para sua sintaxe de destino session:window.pane e silenciosamente os reescreve, então o nome real da sessão tmux usa uma forma segura para tmux onde esses caracteres se tornam _ (issue #3528). O PSM traduz o ID público para o nome seguro para tmux em cada limite tmux; anexe diretamente com o nome seguro para tmux.

Tipo	ID Público (psm attach/kill)	Sessão Tmux (tmux attach -t)	Diretório Worktree
Revisão de PR	omc:pr-123	psm_omc_pr-123	~/.psm/worktrees/omc/pr-123
Correção de Issue	omc:issue-42	psm_omc_issue-42	~/.psm/worktrees/omc/issue-42
Funcionalidade	omc:feat-auth	psm_omc_feat-auth	~/.psm/worktrees/omc/feat-auth

---

Protocolo de Implementação

Quando o usuário invoca um comando PSM, siga este protocolo:

Analisar Argumentos

Analise {{ARGUMENTS}} para determinar:

1. Subcomando: review, fix, feature, list, attach, kill, cleanup, status
2. Referência: project#número, URL ou ID de sessão
3. Opções: --branch, --base, --no-claude, --no-tmux, etc.

Subcomando: review <ref>

Propósito: Criar sessão de revisão de PR

Passos:

1. Resolver referência:

   # Ler apelidos de projeto
   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
   
   # Analisar formato de ref: alias#num, owner/repo#num ou URL
   # Extrair: project_alias, repo (owner/repo), pr_number, local_path
   

2. Buscar informações do PR:

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

3. Garantir que o repositório local exista:

   # Se o caminho local não existir, clonar
   if [[ ! -d "$local_path" ]]; then
     git clone "https://github.com/$repo.git" "$local_path"
   fi
   

4. Criar worktree:

   worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
   
   # Buscar branch do PR
   cd "$local_path"
   git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
   
   # Criar worktree
   git worktree add "$worktree_path" "pr-$pr_number-review"
   

5. Criar metadados da sessão:

   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": "<título>",
       "pr_author": "<autor>",
       "pr_url": "<url>"
     },
     "state": "active"
   }
   EOF
   

6. Atualizar registro de sessões:

   # Adicionar a ~/.psm/sessions.json
   

7. Criar sessão tmux (nome seguro para tmux; :/. são traduzidos para _):

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

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

   # --dangerously-skip-permissions impede o prompt "Você confia neste diretório?"
   # e prompts repetidos de aprovação de ferramenta que travam a sessão (issue #2508).
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" "claude --dangerously-skip-permissions" Enter
   
   # Após o claude iniciar (PSM_CLAUDE_STARTUP_DELAY, padrão 5s), entregue a tarefa.
   # Use -l (literal) para que caracteres especiais não sejam interpretados erroneamente pelo tmux.
   sleep "${PSM_CLAUDE_STARTUP_DELAY:-5}"
   tmux send-keys -t "psm_${project_alias}_pr-$pr_number" -l \
     "Revise o PR #$pr_number: \"$pr_title\" por @$pr_author ($head_branch → $base_branch). URL: $pr_url." Enter
   

9. Saída de informações da sessão:

   Sessão pronta!
   
     ID: omc:pr-123
     Worktree: ~/.psm/worktrees/omc/pr-123
     Tmux: psm_omc_pr-123
   
   Para anexar: tmux attach -t psm_omc_pr-123   (ou: psm attach omc:pr-123)
   

Subcomando: fix <ref>

Propósito: Criar sessão de correção de issue

Passos:

1. Resolver referência (igual ao review)

2. Buscar informações da issue:

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

3. Criar branch de funcionalidade:

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

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

5. Criar metadados da sessão (similar ao review, type="fix")

6. Atualizar registro, criar tmux, iniciar claude: Igual ao review, mas passar o contexto da issue como prompt de tarefa inicial:

   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" "claude --dangerously-skip-permissions" Enter
   # Após o claude iniciar, entregue a tarefa (veja PSM_CLAUDE_STARTUP_DELAY):
   tmux send-keys -t "psm_${project_alias}_issue-$issue_number" -l \
     "Corrija a issue #$issue_number: \"$issue_title\". URL: $issue_url. Branch: $branch_name." Enter
   

Subcomando: feature <project> <nome>

Propósito: Iniciar desenvolvimento de funcionalidade

Passos:

1. Resolver projeto (do alias ou caminho)

2. Criar branch de funcionalidade:

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

3. Criar worktree:

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

4. Criar sessão, tmux, iniciar claude com contexto da funcionalidade como prompt 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 \
     "Implemente a funcionalidade \"$feature_name\" para o projeto $project. Branch: $branch_name." Enter
   

Subcomando: list [project]

Propósito: Listar sessões ativas

Passos:

1. Ler registro de sessões:

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

2. Verificar sessões tmux:

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

3. Verificar worktrees:

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

4. Formatar saída:

   Sessões PSM Ativas:
   
   ID                 | Tipo    | Status   | Worktree
   -------------------|---------|----------|---------------------------
   omc:pr-123        | review  | ativo    | ~/.psm/worktrees/omc/pr-123
   omc:issue-42      | fix     | desanexado | ~/.psm/worktrees/omc/issue-42
   

Subcomando: attach <sessão>

Propósito: Anexar a sessão existente

Passos:

1. Analisar ID da sessão: project:tipo-número

2. Verificar se a sessão existe:

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

3. Anexar:

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

Subcomando: kill <sessão>

Propósito: Matar sessão e limpar

Passos:

1. Matar sessão tmux:

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

2. Remover 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. Atualizar registro:

   # Remover de sessions.json
   

Subcomando: cleanup

Propósito: Limpar PRs mesclados e issues fechadas

Passos:

1. Ler todas as sessões

2. Para cada sessão de PR, verificar se foi mesclada:

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

3. Para cada sessão de issue, verificar se foi fechada:

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

4. Limpar sessões mescladas/fechadas:

   • Matar sessão tmux
   • Remover worktree
   • Atualizar registro

5. Relatório:

   Limpeza completa:
     Removido: omc:pr-123 (mesclado)
     Removido: omc:issue-42 (fechado)
     Mantido: omc:feat-auth (ativo)
   

Subcomando: status

Propósito: Mostrar informações da sessão atual

Passos:

1. Detectar sessão atual do tmux ou cwd:

   tmux display-message -p "#{session_name}" 2>/dev/null
   # ou verificar se cwd está dentro de um worktree
   

2. Ler metadados da sessão:

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

3. Mostrar status:

   Sessão Atual: omc:pr-123
   Tipo: review
   PR: #123 - Adicionar suporte a webhooks
   Branch: feature/webhooks
   Criado: 2 horas atrás
   

---

Tratamento de Erros

Erro	Resolução
Worktree existe	Oferecer: anexar, recriar ou abortar
PR não encontrado	Verificar URL/número, verificar permissões
Sem tmux	Avisar e pular criação da sessão
Sem CLI gh	Erro com instruções de instalação

Comando Teleport

O comando omc teleport fornece uma alternativa leve para sessões PSM completas. Ele cria git worktrees sem gerenciamento de sessão tmux — ideal para desenvolvimento rápido e isolado.

Uso

# Criar worktree para uma issue ou PR
omc teleport #123
omc teleport owner/repo#123
omc teleport https://github.com/owner/repo/issues/42

# Criar worktree para uma funcionalidade
omc teleport minha-funcionalidade

# Listar worktrees existentes
omc teleport list

# Remover um worktree
omc teleport remove issue/meu-repo-123
omc teleport remove --force feat/meu-repo-minha-funcionalidade

Opções

Flag	Descrição	Padrão
`--worktr

… [truncado para tradução]