Rodando várias sessões do Claude Code: como saber qual precisa de você

01Por que sessões paralelas ficam confusas

Rodar duas ou três sessões do Claude Code lado a lado virou uma forma normal de trabalhar: uma corrige um bug, outra escreve testes, outra explora um refactor. Cada sessão para no seu próprio ritmo. Os problemas são sempre os mesmos:

• chega um alerta e você não sabe de qual aba do terminal ele veio;
• uma sessão está esperando um prompt de permissão há vinte minutos enquanto você olhava outra;
• você responde na janela errada.

Os três se resumem a identificação. Todo alerta deve dizer de onde veio, e toda resposta deve voltar para a sessão que perguntou.

02Primeiro, separe bem as sessões

Use worktrees para o mesmo repositório

Duas sessões editando o mesmo checkout vão atropelar as mudanças uma da outra. A flag --worktree do Claude Code (-w na forma curta) cria um git worktree isolado e inicia a sessão nele:

claude --worktree feature-auth
claude --worktree fix-login

Por padrão, cada worktree é criado em .claude/worktrees/<name>/ na raiz do repositório, numa nova branch chamada worktree-<name>. Rode cada comando no seu próprio terminal. Adicione .claude/worktrees/ ao seu .gitignore para que os worktrees não apareçam como arquivos não rastreados.

Quando você sai, o Claude Code verifica o worktree. Se estiver limpo e você nunca tiver nomeado a sessão, o Claude Code remove o worktree e a branch; caso contrário, pergunta se deve mantê-lo. Para voltar depois a um worktree mantido, rode o comando claude --worktree <name> --resume que ele exibe ao sair. Se preferir gerenciar os worktrees você mesmo, git worktree add ../project-feature-a -b feature-a também funciona; inicie o claude dentro dessa pasta.

Um efeito colateral útil para as notificações: cada sessão agora tem seu próprio nome de pasta, como feature-auth, que é exatamente o que você quer num alerta.

Dê nomes às sessões

Nomes facilitam encontrar e retomar sessões:

claude -n auth-refactor

Dentro de uma sessão em andamento, /rename auth-refactor faz o mesmo, e o nome aparece na barra do prompt. Depois, claude --resume auth-refactor leva você direto de volta. No seletor de sessões (claude --resume sem nome), Ctrl+W amplia a lista para todos os worktrees do repositório.

03Coloque o projeto em todo alerta feito por você

Todo command hook recebe JSON na entrada padrão com campos comuns a todos os eventos, incluindo session_id, cwd, transcript_path e hook_event_name. Numa sessão em worktree, cwd é a raiz do worktree e acompanha o Claude se ele mudar de diretório. Leia esse campo no seu hook e use a última parte do caminho como rótulo.

No Mac e no Linux, salve isto como ~/.claude/hooks/notify-session.sh e torne o arquivo executável com chmod +x. É preciso ter o jq.

#!/bin/sh
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
event=$(printf '%s' "$input" | jq -r '.hook_event_name')

case "$event" in
  Stop) msg="Claude has finished" ;;
  *)    msg="Claude needs you" ;;
esac

notify-send "Claude Code: $project" "$msg"

No Mac, troque a última linha por uma notificação via osascript, como mostrado no guia do macOS. No Windows, leia o mesmo JSON no PowerShell com ConvertFrom-Json; o guia do Windows traz um exemplo completo.

Depois, registre-o para os eventos que interessam em ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/notify-session.sh" }] }
    ],
    "Notification": [
      { "matcher": "permission_prompt", "hooks": [{ "type": "command", "command": "~/.claude/hooks/notify-session.sh" }] }
    ]
  }
}

Duas observações sobre caminhos. Coloque variáveis como "$input" entre aspas, porque nomes de pastas podem ter espaços. E, se você referenciar um script com ${CLAUDE_PROJECT_DIR}, lembre que ele continua apontando para a pasta onde a sessão começou, mesmo depois que o Claude passa para um worktree. Leia cwd do input quando precisar da pasta atual.

Se você trabalha no tmux, o pane ou a janela costuma ser um rótulo melhor que a pasta. O guia do tmux mostra como encontrar e ir para o pane certo.

04A parte difícil: responder à sessão certa

Um alerta com rótulo diz qual sessão precisa de você. Mas você ainda precisa ir até aquele terminal para responder. Com três sessões, isso significa achar a aba certa, rolar até o prompt e digitar. Um hook feito por conta própria não consegue enviar sua resposta de volta com facilidade, porque só o hook que está esperando dentro daquela sessão pode devolver uma decisão ao Claude Code.

É essa lacuna que o Claude Code Notifier preenche. É uma ferramenta independente, não feita pela Anthropic. Sua ferramenta de linha de comando, ccn, é instalada como hooks do Claude Code no Mac, Windows e Linux, então toda sessão que você inicia fica coberta, em qualquer terminal, sem configurar sessão por sessão. Cada notificação traz o nome e a pasta do projeto, então no seu iPhone ou Android você vê qual sessão a enviou. Como o hook que enviou a solicitação é o mesmo que espera sua resposta, uma aprovação, uma escolha ou uma instrução de acompanhamento enviada pelo celular volta para a sessão que perguntou.

Alguns detalhes que importam quando há várias sessões:

• Vários computadores. Um celular pode ser pareado com vários computadores, e um computador com vários celulares. ccn devices lista os celulares pareados com este computador.
• Presença. Se você digitou nos últimos 30 segundos, nada espera pelo celular e o terminal pergunta normalmente. Se você estiver ausente, a sessão espera a resposta do celular até um limite que você escolhe (hold_ceiling_seconds) e para de esperar assim que você toca no teclado.
• Notificações no desktop sem celular. Antes de você parear um celular, o ccn mostra uma notificação no computador quando qualquer sessão termina, precisa de uma permissão ou faz uma pergunta.

Se você roda só uma sessão por vez e fica na mesa, um alerta de desktop com rótulo provavelmente basta. O guia comparativo mostra as opções lado a lado.

05Perguntas frequentes