Gerenciar múltiplos agentes com agent view

Despache e gerencie muitas sessões Claude Code a partir de uma tela. Agent view mostra o que cada sessão está fazendo e quais precisam de sua entrada.

Agent view, aberto com claude agents, é uma tela para todas as suas sessões em background: o que está em execução, o que precisa de sua entrada e o que está concluído. Despache novas sessões, observe seu estado rapidamente em vez de rolar pelos transcritos e intervenha apenas quando uma precisar de você. Cada sessão em background é uma conversa completa do Claude Code que continua em execução sem um terminal anexado, então você pode abri-la, responder e sair sempre que quiser.

Use agent view quando você tiver várias tarefas independentes que Claude pode trabalhar sem você observar cada passo. Despache uma correção de bug, uma revisão de pull request e uma investigação de teste instável como três linhas, continue trabalhando em outra janela e verifique quando uma linha mostrar que precisa de você ou tem um resultado.

Quando você quer trabalhar de forma mais direta em qualquer sessão de um agente, anexe-se à linha para entrar na conversa completa.

Para comparar agent view com subagentes, equipes de agentes e worktrees, consulte Executar agentes em paralelo. Agent view executa sessões em sua máquina e você despacha cada uma; para ter Claude iniciar e rastrear sessões paralelas na nuvem a partir de uma conversa em vez disso, consulte Projects.

Início rápido

Este passo a passo aborda o loop de visualização do agente principal: despache uma tarefa, observe sua linha ser atualizada conforme Claude trabalha, espreite para verificar e responda, e anexe para a conversa completa. A sessão que você despacha continua em execução após você fechar a visualização do agente, portanto você pode sair e voltar a ela.

claude agents

Você pode usar claude agents como seu ponto de entrada principal em vez de claude: despache cada tarefa da visualização do agente, anexe quando quiser a conversa completa e pressione ← para retornar à tabela.

Dentro de uma sessão regular claude, a dica ← do rodapé do prompt conta os agentes em background que estão aguardando você, como ← 2 agents, e retorna para ← for agents quando nenhum precisa de entrada. Contagens acima de 99 aparecem como 99+. A contagem é atualizada aproximadamente a cada dez segundos enquanto o terminal está em foco e imediatamente quando o foco retorna. Ela muda brevemente de cor quando se move e quando um agente é concluído, e quando uma sessão em background é concluída enquanto nenhuma precisa de sua entrada, ela brevemente mostra o número concluído, como ← 2 done. Ambos os flashes estão desativados quando a configuração prefersReducedMotion está ativada, e a dica fica oculta no modo leitor de tela.

Monitorar sessões com agent view

Execute claude agents para abrir agent view. Ele assume o terminal completo e lista cada sessão agrupada por estado, com sessões fixadas e as que precisam de você no topo. Cada linha mostra o nome da sessão, atividade atual e sua idade, contada a partir de quando a sessão foi criada; a idade de uma sessão concluída congela em quanto tempo a execução levou.

O nome é tingido com a cor definida por /color naquela sessão, incluindo quando você coloca uma sessão em background com ← ou /background.

Por padrão, a lista mostra cada sessão em background que você iniciou, em todos os seus projetos. Uma sessão funcionando em um repositório e outra em um worktree diferente aparecem aqui, independentemente de qual diretório você abriu agent view. Para limitar a lista a um projeto, passe --cwd:

claude agents --cwd ~/projects/my-app

Isso mostra apenas sessões iniciadas sob esse diretório. Uma sessão que se moveu para um worktree sob ~/projects/my-app/.claude/worktrees/ ainda é listada.

Sessões interativas que você tem abertas em outros terminais não aparecem até que você as coloque em background. Subagents e teammates que uma sessão gera não são listados como linhas separadas.

Pinned
  ✽ clawd walk cycle          Drawing the walk-cycle sprite frames          3m

Ready for review
  ∙ jump physics              Opened PR with collision fix                 #2048  2h

Needs input
  ✻ power-up design           double jump or wall climb?                    1m

Working
  ✽ collision detection       Adding swept-AABB checks to CollisionSystem   2m
  ✢ playtest level 3          run 12 · all checkpoints cleared           in 4m

Completed
  ✻ title screen              result: menu, options, and credits done       9m
  ∙ sound effects             result: 14 SFX exported to assets/audio       4h
  … 6 more

Ler estado da sessão

Cada linha começa com um ícone cuja cor e animação mostram o estado da sessão:

Separadamente, a forma do ícone mostra se o processo subjacente está em execução:

O rótulo #N ou !N que pode aparecer na borda direita de uma linha é um link para o pull request ou merge request da sessão, não parte do ícone de estado.

O título da aba do terminal mostra a contagem de aguardando-entrada enquanto agent view está aberto: 2 awaiting input · claude agents quando sessões precisam de entrada, ou claude agents quando nenhuma precisa.

Para ler o estado da sessão a partir de um script ou outro programa, use claude agents --json em vez dos arquivos sob ~/.claude/jobs/.

Enquanto agent view está aberto, Claude Code também envia uma notificação através do seu canal de notificação de terminal configurado quando uma sessão em background local começa a precisar de sua entrada, termina ou falha. Sessões que executam em um cronograma, como sessões /loop, notificam apenas quando precisam de sua entrada. As notificações usam a mesma configuração preferredNotifChannel que o resto do Claude Code e disparam o hook Notification com o tipo agent_needs_input ou agent_completed.

Sessões em background não precisam de nenhum terminal aberto para continuar funcionando. Um processo supervisor separado as executa, então você pode fechar agent view, fechar seu shell ou iniciar uma nova sessão interativa e seu trabalho despachado continua.

O estado da sessão persiste no disco através de atualizações automáticas e reinicializações do supervisor. As sessões também são preservadas quando sua máquina dorme. Seus processos retomam ao acordar e o supervisor se reconecta a eles em vez de tratar a lacuna de tempo como inatividade. Desligar ainda interrompe as sessões em execução; veja Sessions show as failed or stopped after shutdown para saber como recuperá-las.

Uma sessão que estava no meio de uma resposta quando a máquina dormiu pode voltar sem responder. Quando você abre uma sessão que parou de responder, o supervisor reinicia seu processo e a sessão continua a resposta interrompida de onde parou.

Resumos de linha

O resumo de uma linha em cada linha é gerado por um modelo Haiku-class para que a linha possa informar o que a sessão está fazendo, o que precisa ou o que produziu sem abrir o transcript. Enquanto uma sessão está ativamente funcionando, o texto da linha é atualizado no máximo uma vez a cada 15 segundos a partir da saída recente da própria sessão sem enviar uma solicitação de modelo, e o modelo escreve um resumo novo quando cada turno termina.

Uma linha funcionando mostra o que a sessão diz que está fazendo, e uma linha bloqueada mostra a pergunta que está fazendo. Durante um turno longo, o modelo também reescreve o resumo a cada poucos minutos para que uma linha ocupada não continue mostrando um resumo desatualizado. O texto de resumo preenche a largura restante da linha; abra o painel de espiada para ler uma sentença que a borda do terminal corta.

Quando a lista é agrupada por diretório, o resumo abre com o estado da sessão como uma palavra colorida, como Needs input · double jump or wall climb?. No agrupamento de estado padrão, o cabeçalho do grupo já nomeia o estado, então a linha mostra apenas o resumo.

O resumo de fim de turno e cada reescrita de meio de turno são uma solicitação curta de Haiku-class através de seu provedor normal, cobrada e tratada sob os mesmos termos de uso de dados que a sessão em si. As atualizações de 15 segundos entre reescritas de modelo reutilizam a saída da própria sessão e não enviam uma solicitação. Em um provedor de terceiros ou gateway sem um modelo Haiku-class configurado, a solicitação usa o modelo principal da sessão em vez disso; defina ANTHROPIC_DEFAULT_HAIKU_MODEL para escolher um.

Status de pull request

Quando uma sessão abre um pull request, Claude Code adiciona um rótulo na borda direita da linha, vinculado ao pull request:

• Claude Code escreve o rótulo como #1234 para um pull request e como !1234 para um merge request do GitLab.
• Claude Code emite o link mesmo quando não consegue detectar suporte a hiperlink, por exemplo sobre SSH ou tmux. Defina FORCE_HYPERLINK=0 para renderizar o rótulo como texto simples.
• Depois que você envia um acompanhamento para a sessão, Claude Code mantém o rótulo enquanto a linha retorna ao progresso ao vivo.

Uma sessão que trabalha em um pull request existente está vinculada a ele da mesma forma. Claude Code encontra o pull request de forma diferente dependendo do comando que Claude executa:

• Quando Claude edita, comenta, fecha ou marca um pull request como pronto com gh, Claude Code vincula o pull request que a saída do próprio comando nomeia. Um comando gh cuja saída capturada não nomeia nenhum pull request não cria um link; gh pr merge é o caso comum, porque imprime seu resultado apenas para um terminal interativo.
• Quando Claude verifica um pull request com gh pr checkout ou faz push para um branch, Claude Code procura o branch com gh pr view e vincula seu pull request aberto.
• O pull request não precisa existir ainda quando Claude faz push: Claude Code tenta novamente a busca do branch após até cinco comandos git, gh, glab ou curl posteriores executados no mesmo diretório, então um pull request criado após o push, incluindo um que Claude cria através da API REST do GitHub, vincula quando uma tentativa o encontra.

Quando uma sessão está vinculada a mais de um pull request, o rótulo mostra uma contagem em vez disso, como 3 PRs, colorido pelo pull request aberto que mais precisa de atenção. Abra o painel de espiada para ver todos eles.

O número do pull request é colorido pelo seu status:

Para uma tarefa que termina em um pull request, verifique este rótulo para o resultado: revise e mescle o pull request quando seu número ficar verde.

Peek and reply

Pressione Space em uma linha selecionada para abrir o painel de espiada. Ele abre com a sentença que a linha trunca na borda do terminal, e qual sentença é depende do estado da sessão:

• Uma sessão que está aguardando você: a pergunta exata que está fazendo, acima da entrada de resposta
• Uma sessão concluída: seu resultado
• Uma sessão funcionando: sua sentença de status completa

Quaisquer pull requests vinculados à sessão são listados em seguida. Para uma sessão que está aguardando você, uma linha como waiting 3m abaixo deles mostra há quanto tempo está aguardando, e é a única hora mostrada no painel. A idade na borda direita da linha é um número diferente: ela conta a partir de quando a sessão começou.

Na maioria das vezes, o painel de espiada é suficiente e você não precisa abrir o transcript completo.

Digite uma resposta no painel de espiada e pressione Enter para enviá-la para essa sessão. Quando a sessão faz uma pergunta com opções predefinidas, o painel de espiada as mostra como uma lista numerada e você pode pressionar uma tecla numérica para escolher uma. Um prompt de permissão mostra como texto descrevendo o que a sessão quer executar, sem opções numeradas. Digite uma resposta para respondê-lo, ou anexe para responder com o prompt padrão. Para outras sessões bloqueadas, pressione Tab para preencher a entrada com uma resposta sugerida que você pode editar antes de enviar. Prefixe uma resposta com ! para enviar um comando Bash em vez disso.

Quando um hook PermissionRequest ou PreToolUse retorna uma saída que Claude Code não consegue validar para a chamada que a sessão está pedindo, a linha mostra o evento do hook e hook output invalid: com o erro de validação antes do texto da solicitação pendente. Para um hook que falha de outra forma, a linha diz que o hook falhou. A sessão ainda aguarda a mesma solicitação.

Uma resposta que não pode ser entregue, porque o serviço em background está inacessível ou o envio falha, é salva e enviada para a sessão como seu próximo prompt quando seu processo começar novamente, e a mensagem de erro diz que a resposta foi salva. Uma resposta prefixada com ! não é salva, porque o texto salvo chegaria à sessão como um prompt simples em vez de executar como um comando Bash.

Com voice dictation ativada, segure ou toque sua tecla push-to-talk enquanto a entrada de resposta está focada para ditar uma resposta em vez de digitá-la. O mesmo funciona na entrada de despacho na parte inferior de agent view.

Use ↑ e ↓ para espreitar sessões adjacentes sem fechar o painel, ou → para anexar.

Anexar a uma sessão

Pressione Enter ou → em uma linha selecionada para anexar. Agent view é substituído pela sessão interativa completa. Quando você anexa, Claude publica um breve resumo do que aconteceu enquanto você estava ausente.

Enquanto anexado, a sessão se comporta como qualquer outra sessão Claude Code: comandos, atalhos de teclado e recursos todos funcionam, com as exceções abaixo.

Enquanto você está anexado, /install-github-app e a lista de configurações /mcp funcionam normalmente, já que um humano no terminal pode completar seus diálogos. Quando ninguém está anexado, esses comandos não conseguem abrir seus diálogos, então a sessão aparece sob Needs input em agent view com uma linha como open this session to manage MCP servers, e a resposta do transcript diz o mesmo. Anexe e execute o comando novamente para continuar; a linha de necessidade de entrada é limpa quando você anexa. /mcp reconnect <server>, /mcp enable e /mcp disable funcionam sem anexar de qualquer forma.

Sessões anexadas sempre renderizam em modo fullscreen, independentemente de sua configuração tui, porque uma sessão em background não tem scrollback de terminal para anexar. Role com PgUp, PgDn ou a roda do mouse, e pressione Ctrl+O para modo de transcript. O scroll nativo do seu terminal e o modo de cópia tmux mostram apenas o viewport atual, o mesmo que quando você executa qualquer aplicativo fullscreen.

Pressione ← em um prompt vazio, ou execute /exit, para desanexar e retornar a agent view, independentemente de você ter aberto a sessão a partir de agent view ou com claude attach <id> a partir do seu shell.

← também desanexa enquanto o overlay /btw está aberto. Requer Claude Code v2.1.257 ou posterior. Uma pergunta lateral que ainda está respondendo continua em execução enquanto você está ausente. Na próxima vez que você anexar, o overlay reabre com ela, ou com sua resposta.

No Windows, se você pressionar ← dentro de cerca de meio segundo de anexar, Claude Code mostra Ambiguous ←, press again to detach, porque naquela janela o terminal pode reentrega um pressionamento de antes de você anexar. Pressione ← novamente para desanexar.

Ctrl+Z também desanexa mas volta para onde você começou em vez disso: agent view se você anexou de lá, ou seu shell se você executou claude attach. Use Ctrl+Z quando um diálogo tem foco e não está respondendo a ←.

Ctrl+C mantém seu comportamento de interrupção padrão enquanto anexado: ele cancela uma resposta em execução ou comando shell ! em vez de desanexar. Pressionar Ctrl+C duas vezes em um prompt vazio desanexa, o mesmo que em qualquer sessão.

Desanexar nunca interrompe uma sessão em background: ←, Ctrl+Z, /exit e duplo Ctrl+C ou duplo Ctrl+D a deixam em execução. Para encerrar uma sessão de dentro dela, execute /stop.

Alternar sessões sem sair do terminal

Em uma sessão em execução em primeiro plano, uma que você iniciou no terminal em vez de anexar a partir de agent view, pressionar ← em um prompt vazio a coloca em background e abre agent view com essa linha selecionada, para que você possa alternar sessões sem sair do terminal. O mesmo pressionamento único desanexa uma sessão anexada.

Se você pressionar ← logo após deletar o último texto do prompt ou mover pelo histórico do prompt, Claude Code pede que você confirme: o primeiro pressionamento mostra Press ← again to open agents, ou Press ← again to go back to agents em uma sessão anexada, e o segundo pressionamento alterna.

Quando ← coloca uma sessão em primeiro plano em background, agent view mostra Your conversation moved to the background acima da lista, com a linha dessa sessão já selecionada. De lá:

• Pressione Enter para reabrir a conversa.
• Pressione Esc para desfazer a alternância e retornar à conversa. Se Esc mostra Still starting — try again in a moment, a sessão em background ainda não está pronta, então pressione Esc novamente em um momento.
• Pressione Ctrl+C duas vezes para sair para seu shell.

Quando Claude Code não consegue reabrir a conversa, ele sai e imprime um comando claude --resume que a retoma.

A lista de tarefas do Claude se move para a sessão em background com a conversa, então a lista de verificação está intacta quando você retorna àquela linha.

A linha em que você pressionou ← também mantém um nome em negrito e não esmaecido depois que você move a seleção com as teclas de seta ou o mouse, para que você possa dizer de qual sessão você veio.

Se uma ferramenta está em execução quando você pressiona ←, Claude Code aguarda até cerca de dez segundos para que ela termine antes de colocar em background, e Claude continua a resposta na sessão em background. Pressione ← novamente para colocar em background imediatamente em vez de aguardar. Quando o trabalho em andamento não pode ser transferido para a sessão em background, Claude Code mostra o diálogo Background this session? primeiro, o mesmo que com /background.

O limite de dez segundos não se aplica enquanto os subagents em primeiro plano que Claude iniciou na conversa ainda estão em execução. Claude Code continua aguardando para que seu trabalho seja transferido, e mostra um aviso Still backgrounding after the current tool enquanto aguarda. Pressione ← novamente para colocar em background sem aguardar, o que reinicia esses subagents do início. Claude Code não aguarda os subagents que um workflow dinâmico está executando. Quando um workflow tem subagents em execução, Claude Code mostra o diálogo Background this session? em vez disso.

Claude Code não coloca a sessão em background enquanto você tem texto não enviado na entrada do prompt, porque o texto fica na caixa de entrada do seu terminal e não se moveria para a sessão em background. Se você digitar na entrada enquanto Claude Code aguarda para colocar a sessão em background, ele cancela a alternância com Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.

Pressionar ← cria a linha da sessão mesmo quando a conversa não tem mensagens ainda, então → ainda retorna a ela.

Você pode desativar este atalho com a configuração leftArrowOpensAgents em /config.

Organizar a lista

Agent view agrupa sessões para que as que precisam de entrada estejam no topo, com Ready for review e Needs input acima de Working e Completed. Esses nomes de grupo não mapeiam um-para-um para os estados acima: uma sessão se move para Ready for review quando tem um pull request aberto, e Completed coleta sessões concluídas, falhadas e interrompidas juntas.

Pressione Ctrl+S para agrupar por diretório em vez disso. Sua escolha persiste entre execuções.

Dentro de um grupo:

• Pressione Ctrl+T para fixar uma sessão no topo e manter seu processo em execução enquanto inativo
• Pressione Shift+↑ ou Shift+↓ para reordenar sessões
• Pressione Ctrl+R para renomear uma sessão
• Pressione Enter em um cabeçalho de grupo para recolhê-lo

Para remover uma sessão da lista, pressione Ctrl+X para interrompê-la e Ctrl+X novamente dentro de dois segundos para deletá-la. Pressionar Ctrl+X em um cabeçalho de grupo deleta cada sessão naquele grupo após confirmação.

O segundo pressionamento deleta a sessão mesmo quando a tentativa de parada falha, por exemplo porque o serviço em background não está respondendo: a confirmação permanece ativa por mais dois segundos, e a exclusão encerra o processo da sessão em si. Pressione Esc para descartar a confirmação sem deletar.

Exceto nos casos mantidos cobertos em What deleting a session removes, deletar remove a sessão da lista, e um worktree que Claude criou para ela é removido, mantido ou deixado no lugar dependendo de como você deleta e o que o worktree contém. O transcript de conversa sempre fica em sua máquina local, disponível através de claude --resume.

Para trazer uma sessão de volta no Claude Code v2.1.212 ou posterior, digite /resume na entrada de despacho. Um seletor abre com sessões passadas do repositório a partir do qual você abriu agent view, mais recentes primeiro, incluindo sessões que você deletou da lista; sessões que já têm uma linha não são listadas. ↑/↓ movem a seleção, Enter retoma a sessão selecionada como uma sessão em background para que ela se rejunte à lista como uma linha, e Esc fecha o seletor.

O seletor abre apenas para um /resume simples. Um resume direcionado, com escopo ou restrito não pode ser servido pelo seletor, então agent view mostra a dica attach to a session to run it em vez disso quando:

• /resume nomeia um id ou um termo de busca
• a visualização tem escopo com --cwd
• a visualização foi iniciada com --safe-mode
• a visualização foi aberta com um sinalizador como --permission-mode ou --settings

Sessões concluídas que não cabem na tela se dobram em uma linha … N more. Falhas e sessões com um pull request aberto sempre permanecem visíveis. O grupo Completed preenche o espaço vertical deixado após os grupos ativos, e em um terminal curto o cabeçalho se compacta para uma única linha de resumo para que sessões que estão funcionando ou precisam de entrada permaneçam visíveis.

Filtrar sessões

Digite na entrada de despacho para filtrar em vez de despachar:

Atalhos de teclado

Pressione ? em agent view para ver cada atalho em contexto. A tabela abaixo os resume.

Ctrl+S, Ctrl+T e Ctrl+G seguem seu keybindings.json. Rebind ou unbind Ctrl+S e Ctrl+T com as ações agents:switchView e agents:togglePin no contexto Agents, e Ctrl+G através da vinculação chat:externalEditor do contexto Chat. Os outros atalhos na tabela não podem ser revinculados.

Despachar novos agentes

Você pode despachar novas sessões em background a partir de agent view, enviar uma sessão interativa existente para o background ou iniciar uma diretamente do shell.

From agent view

Digite um prompt na entrada na parte inferior de agent view e pressione Enter para iniciar uma nova sessão em background. A sessão é nomeada automaticamente a partir do prompt; renomeie-a mais tarde com Ctrl+R.

O nome automático é um rótulo curto escrito por um modelo da classe Haiku. Um nome que a sessão recebe mais tarde também aparece em sua linha, incluindo o título gerado que a sessão recebe quando você aceita um plano naquela sessão.

Cole uma imagem no prompt para incluir uma captura de tela ou diagrama com a tarefa.

Texto colado mais longo que 800 caracteres ou mais de três linhas se recolhe para um placeholder [Pasted text #N] para que a entrada permaneça em uma linha; o texto completo é enviado quando você despacha. Para revisar ou editar o texto recolhido antes de despachar, cole o mesmo texto novamente e o placeholder se expande de volta para a entrada.

Prefixe ou mencione partes do prompt para controlar como a sessão é iniciada:

Um pequeno conjunto de comandos é executado em agent view em si em vez de ser despachado:

• /exit e /quit fecham agent view
• /logout desconecta você
• /model define o modelo de despacho
• /login abre o diálogo de entrada para que você possa entrar novamente sem anexar a uma sessão
• Um /resume simples, ou seu alias /continue, abre um seletor das sessões passadas do repositório para trazer uma de volta como uma sessão em background. Requer Claude Code v2.1.212 ou posterior

Skills, seus próprios comandos e built-ins que expandem prompts como /init são enviados para uma nova sessão em background como seu primeiro prompt. Outros comandos built-in mostram uma dica attach to a session to run it em vez disso. Tudo que você digitou permanece na entrada ao lado da dica para que você possa editá-lo.

Empacotar uma tarefa recorrente como uma skill permite que você inicie o mesmo fluxo de trabalho a partir de agent view repetidamente sem redigitar o prompt.

Quando o mesmo @name corresponde tanto a um subagent quanto a um repositório irmão, o subagent tem precedência. A correspondência de primeira palavra também se aplica, portanto um prompt que começa com um de seus nomes de subagent despacha esse subagent em vez de tratar a palavra como texto simples. Use a forma @ quando quiser ser explícito, ou comece o prompt com uma palavra diferente para evitar a correspondência.

Dispatch to a specific directory

Uma nova sessão é executada no diretório em que você abriu agent view. Para direcionar um diretório diferente, use qualquer um destes:

• Abra claude agents naquele diretório.

• Abra claude agents em um diretório pai e mencione um repositório filho com @<repo> no prompt. Digitando @ lista estes destinos:

  • Repositórios Git um nível abaixo do diretório de lançamento
  • Os git worktrees registrados do repositório a partir do qual você iniciou que vivem dentro de sua árvore de diretórios, como os que Claude cria sob .claude/worktrees/, rotulados com seu branch verificado. Worktrees adicionados fora do repositório, como com git worktree add ../feature, não são listados
  • Qualquer diretório que já tenha uma sessão na lista

  Um diretório cujo nome contém um espaço não é listado.

• Do shell, cd para o diretório e execute claude --bg "<prompt>".

Quando agent view é agrupado por diretório, despachar envia o prompt para o diretório da linha selecionada, para que você possa selecionar um grupo e despachar nele sem redigitar o caminho.

From inside a session

Dois comandos movem trabalho da sessão em que você está para o background: /background envia a conversa atual para lá e libera seu terminal, e /fork envia uma cópia enquanto você continua trabalhando onde está.

Send the session to the background

Execute /background ou seu alias /bg para mover a conversa atual para uma sessão em background. Passe um prompt como /bg run the test suite and fix any failures para dar uma instrução adicional primeiro. Se Claude estiver respondendo quando você executar /bg, a resposta continua na sessão em background.

Sair de uma sessão que ainda tem trabalho em background em execução, como subagents, comandos shell em background, workflows ou monitors, mostra um diálogo Background work is running em vez de sair imediatamente. Escolha Move to background and exit para colocar a sessão em background da mesma forma que /background faz e retornar ao seu shell. A opção não é mostrada quando agent view está desativado.

Se uma sessão em background na lista já tem o nome da conversa, Claude Code numera o nome da nova linha, como my-session (2), e deixa o nome da linha existente sozinho. Para renomear a nova linha, selecione-a em agent view e pressione Ctrl+R.

Copy the session with /fork

Execute /fork para copiar a conversa atual para uma nova sessão em background enquanto a original continua em execução. A cópia começa com tudo na conversa até esse ponto; veja os pontos abaixo para onde a cópia é executada. Ela também carrega o modelo, permission mode, effort level e quaisquer diretórios ou concessões de permissão "não pergunte novamente" que você adicionou durante a sessão. A cópia aparece como sua própria linha em agent view.

Após o fork, as duas conversas são independentes: nada que a cópia faz entra na conversa original por conta própria, embora em sessões onde cross-session messaging está habilitado, Claude de qualquer sessão pode explicitamente enviar mensagens para a outra.

Copiar a sessão requer Claude Code v2.1.212 ou posterior; em v2.1.161 até v2.1.211, /fork inicia um subagent bifurcado em vez disso, que agora é /subtask. Quando agent view está desativado, /fork mantém o comportamento de subagent bifurcado e /subtask não está disponível.

Passe um prompt como /fork open a draft pull request with the work so far e a cópia começa a trabalhar nele imediatamente. Sem um prompt, a cópia aguarda sua primeira instrução: selecione sua linha em claude agents e pressione Space para enviar uma, ou execute claude attach <id>. A linha selecionada mostra space to send it a prompt enquanto aguarda.

A confirmação de /fork é uma linha mostrando o estado da cópia, como session running, o nome de sua linha de agent view e seu ID de sessão para claude attach. Clique no nome para alternar para a cópia: esta sessão se move para o background, o mesmo que pressionar ←, e agent view abre a sessão da cópia.

Exceto quando a cópia edita no local, Claude Code a instrui a criar seu próprio worktree antes de fazer alterações de código. Fora de um repositório git, apenas uma cópia movida para fora de um worktree criado por hook recebe a instrução; sem um hook WorktreeCreate, a cópia edita no local. Uma cópia movida para fora de seu worktree também é instruída a nunca editar, executar comandos em ou entrar naquele worktree, qualquer que seja a configuração de isolamento.

Onde a cópia começa depende de onde a sessão atual está em execução:

• Como qualquer sessão despachada, a cópia se move para seu próprio worktree antes de editar arquivos. Nesse caso, a confirmação não menciona onde a cópia é executada.
• Quando sua sessão se moveu para seu worktree vinculado após iniciar, a cópia começa de volta onde a sessão estava antes da movimentação e, a menos que edite no local, faz suas alterações de código em um worktree próprio lá. Quando seu worktree está verificado em um branch, essa instrução também diz a uma cópia cuja tarefa se baseia em seu trabalho para basear seu novo branch no seu, já que seu branch permanece verificado em seu worktree. A confirmação termina com runs in the origin tree.
• Quando você iniciou a sessão dentro de um worktree vinculado de um repositório que tem uma árvore de trabalho principal, a cópia começa naquela árvore de trabalho principal, com a mesma regra de worktree próprio, mas sem instrução de branch. A confirmação termina com runs in the origin tree aqui também.
• Uma sessão iniciada dentro de um worktree de um layout de repositório bare não tem árvore de trabalho principal para retornar, portanto a cópia permanece onde está, e a confirmação termina com edits this checkout. A mesma nota aparece quando o isolamento de worktree está desativado em uma sessão que não está dentro de um worktree vinculado, porque a cópia então edita os arquivos que você tem abertos.

Sessões iniciadas com flags de lançamento que a cópia não herdaria, como um prompt de sistema substituído ou uma allowlist --tools, não podem ser bifurcadas; Claude Code diz isso em vez de fazer uma cópia parcial. Uma sessão despachada a partir de agent view bifurca normalmente: a cópia é lançada com a mesma definição de agente e instruções anexadas que a sessão da qual veio.

What carries over when you background

Colocar em background inicia um novo processo que retoma da conversa salva, e o trabalho em andamento se move para ele: comandos shell em background em execução, subagents em background, workflows dinâmicos, tarefas agendadas que você criou com /loop e respostas automáticas de Claude a comentários de artefatos todos se transferem e continuam em execução lá. Um subagent se move junto com tudo que iniciou, portanto é transferido apenas quando todo esse trabalho pode se mover também. Para parar o trabalho em andamento em vez de transferi-lo, defina a variável de ambiente CLAUDE_DISABLE_ADOPT=1; Claude Code então pede que você confirme antes de colocar em background.

Quando um workflow dinâmico ainda tem subagents em execução, Claude Code pergunta antes de colocar em background com o diálogo Background this session?, que diz quantos subagents seriam reiniciados. Escolha Stay para deixá-los terminar primeiro. Se você confirmar, Claude Code reproduz a execução na sessão em background: subagents que ainda estavam em execução começam do início, portanto os tokens que usaram até agora são gastos novamente. Veja Resume after a pause para saber quais subagents concluídos retornam seus resultados salvos e quais são executados novamente.

Claude Code interrompe o trabalho que não pode ser transferido, como um monitor em execução, e interrompe um subagent em background que possui um monitor junto com ele. Quando algum desse trabalho está em execução, Claude Code mostra o diálogo Background this session? para que você possa confirmar antes de ser interrompido.

Uma vez em background, a sessão pode iniciar novos subagents, monitors e comandos em background, e esses continuam em execução em desanexações e reanexações posteriores.

As flags de configuração do lançamento original são transferidas para a sessão colocada em background, portanto seus servidores MCP, settings e modelo de fallback permanecem em vigor:

• --mcp-config e --strict-mcp-config
• --settings
• --add-dir
• --plugin-dir
• --fallback-model
• --allow-dangerously-skip-permissions

Diretórios que você adicionou durante a sessão com /add-dir também são transferidos. Transferir --allow-dangerously-skip-permissions mantém bypassPermissions acessível na sessão colocada em background, mas não concede nada novo: o modo ainda requer a aceitação interativa única descrita em Permission mode, model, and effort.

From your shell

Passe --bg ou sua forma longa --background para iniciar uma sessão que vai direto para o background:

claude --bg "investigate the flaky SettingsChangeDetector test"

O prompt é o argumento posicional, não um valor -p. Claude Code rejeita --bg combinado com -p ou --print antes de qualquer sessão ser criada, porque --print nunca inicia a sessão interativa à qual claude agents se anexa.

Para executar um subagent específico que você definiu, como um code-reviewer, como o agente principal da sessão, combine --bg com --agent:

claude --agent code-reviewer --bg "address review comments on PR 1234"

Se o nome não corresponder a nenhum de seus subagents, o lançamento falha: Claude Code imprime um aviso no agent named e ainda relata a sessão como colocada em background, mas a sessão sai imediatamente com um erro --agent '<name>' not found.

Quando a sessão colocada em background mais tarde retoma ou reinicia, Claude Code restaura o agente e suas restrições de ferramenta; para seu prompt de sistema, veja System prompt flags in resumed conversations. Ele procura o agente no diretório da própria sessão primeiro, desde que você tenha confiado naquele workspace, portanto um agente com escopo de projeto ainda carrega quando a sessão é retomada de outro diretório. Se o agente não existir mais, a sessão continua com as ferramentas padrão e sua transcrição abre com um aviso nomeando o agente.

Para continuar uma conversa existente em background, passe seu ID de sessão completo com --resume:

claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"

Em Claude Code v2.1.257 ou posterior, Claude Code continua aquela sessão sob o mesmo ID, ou inicia uma cópia sob um novo ID e imprime uma linha note: explicando por que não pôde continuar no local. Quando a sessão continua no local, claude agents mostra uma linha para ela.

Quando você combina --bg com --continue, um --resume simples, ou --resume com um nome ou caminho de arquivo, Claude Code sempre inicia tal cópia. Adicione --fork-session para iniciar uma cópia propositalmente, sem a nota.

Passe --name para definir o nome de exibição da sessão em agent view em vez do gerado automaticamente:

claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

Após colocar em background, Claude imprime o ID curto da sessão e os comandos para gerenciá-la. Quando o serviço que hospeda sessões em background não está já em execução, --bg pode primeiro imprimir Starting background service… acima desta saída. Quando você passa --name, o nome aparece após o ID curto:

backgrounded · 7c5dcf5d · flaky-test-fix
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

Run a shell command

Para executar um comando shell como um trabalho em background em vez de uma sessão Claude, passe --exec. O exemplo a seguir executa pytest -x como um trabalho em background:

claude --bg --exec 'pytest -x'

A partir de agent view, despache o mesmo tipo de trabalho digitando ! como o primeiro caractere da entrada de despacho: o ! aparece como um prefixo, tudo depois dele é o comando, e Enter inicia o trabalho.

O comando é executado como um trabalho com suporte PTY e aparece como uma linha em agent view, com a linha de saída mais recente como seu status. Um trabalho shell executa o comando no lugar de Claude, portanto nenhum modelo é invocado e a saída não é enviada para nenhuma sessão.

Para ver a saída, anexe à linha, pressione Space para espreitar sem anexar, ou execute claude logs <id> do seu shell. A saída capturada permanece na memória e não é escrita em disco. A linha e sua saída são limpas automaticamente cerca de cinco minutos após o comando sair, portanto leia-a antes disso se precisar do resultado.

How file edits are isolated

Toda sessão em background, seja iniciada a partir de agent view, /bg ou claude --bg, inicia no seu diretório de trabalho. Antes de editar arquivos, Claude move a sessão para um git worktree isolado sob .claude/worktrees/, para que sessões paralelas possam ler o mesmo checkout, mas cada uma escreve no seu próprio. Uma vez que a sessão está em seu worktree, Claude Code aplica isolamento de worktree para a sessão e para qualquer subagent que ela gera.

Claude pula o worktree quando:

• A sessão já está dentro de um git worktree vinculado, seja Claude o criou sob .claude/worktrees/ ou você o criou com git worktree add em outro lugar
• O arquivo que Claude está editando está dentro de um git worktree vinculado, como um que a sessão ou seu subagent criou com git worktree add
• O diretório de trabalho não é um repositório git e nenhum hook WorktreeCreate está configurado
• A escrita está fora do diretório de trabalho

Para desativar o isolamento de worktree para um repositório onde git worktrees são impraticáveis, defina worktree.bgIsolation como "none". As sessões em background editam sua cópia de trabalho diretamente sem se mover para um worktree primeiro. Adicione a configuração ao .claude/settings.json do projeto:

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Fora de um repositório git, as sessões escrevem no diretório de trabalho diretamente e não são isoladas uma da outra, portanto evite despachar sessões paralelas que editam os mesmos arquivos. Se você usar um sistema de controle de versão diferente, configure um hook WorktreeCreate e Claude isola edições da mesma forma que faz para git.

Quando o hook falha em um diretório que não é um repositório git, Claude pula o isolamento para aquele diretório e edita o diretório de trabalho no local. Dentro de um repositório git, Claude Code bloqueia escritas no checkout compartilhado até que Claude mova a sessão para um worktree.

Para encontrar o caminho do worktree de uma sessão, espreite a sessão ou anexe e verifique seu diretório de trabalho.

Um subagent que a sessão em background gera herda o diretório de trabalho da sessão, portanto suas edições de arquivo chegam ao worktree da sessão em vez de sua cópia de trabalho. Para dar a um subagent seu próprio worktree separado, defina isolation: worktree em seu frontmatter ou passe isolation: "worktree" ao gerá-lo.

Quando uma sessão em background fez alterações de código em um worktree que Claude entrou, Claude Code instrui Claude a preservar o trabalho antes de terminar, para que sobreviva se você deletar a sessão e seu worktree:

• Commit e push: Claude faz commit sem perguntar, e faz push do branch quando o repositório tem um remoto.
• Draft pull request: Claude abre um quando a tarefa pede, e o rótulo #N aparece na linha.
• Nunca: fazer push para main ou master, force-push e mesclar.
• Suas instruções git têm precedência: se a tarefa, CLAUDE.md ou memory diz que você lida com commit ou push você mesmo, Claude deixa git para você.

Uma sessão editando um checkout que não isolou a si mesma ainda pergunta antes de fazer commit ou alternar branches. Isso se aplica quando o isolamento é definido como "none", quando a movimentação do worktree falhou, ou quando a sessão foi iniciada dentro de um worktree que já existia.

Qualquer que seja a tarefa, Claude termina o trabalho com um relatório dizendo o que fez e onde o trabalho está: um caminho, um branch, um pull request ou a resposta em si.

What deleting a session removes

Delete uma sessão com Ctrl+X duas vezes em agent view ou com claude rm. Exceto nos casos mantidos abaixo, a sessão sai da lista. Sua transcrição permanece em sua máquina através de claude --resume, e a remoção sobrevive a reinicializações do supervisor.

O que acontece com um worktree que Claude criou para a sessão:

• Agent view o remove, incluindo alterações não confirmadas, portanto confirme o que você quer manter primeiro.

• claude rm o mantém, junto com a linha da sessão, quando tem alterações não confirmadas.

• Nem agent view nem claude rm removem um worktree que outra sessão em execução está usando ou bloqueou, e deletar novamente não muda isso. Claude Code mantém o worktree e a sessão, e nomeia o diretório mantido e o motivo; em agent view, a linha da sessão mostra not deleted. Feche a outra sessão, depois delete novamente.

• Quando você deleta uma sessão cujo worktree tem commits que Claude Code não pode confirmar que estão salvos em outro lugar, Claude Code mantém o worktree e a sessão, e a mensagem nomeia o branch do worktree e quantos commits não são enviados. A mensagem também oferece os dois caminhos adiante: fazer push dos commits ou deletar novamente para descartá-los.

  Commits em um remoto não bloqueiam a deleção. Nem commits na cópia local do branch padrão do seu remoto origin, desde que aquele branch esteja verificado em seu checkout principal, o diretório do repositório em si em vez de um worktree.

  Após aquela recusa, você escolhe:

  • Para manter os commits, faça push deles ou mescle-os naquele branch padrão, depois delete a sessão novamente.
  • Para descartá-los, delete a sessão novamente sem fazer push: pressione Ctrl+X duas vezes em sua linha em agent view, ou execute o comando claude rm <id> --discard-unpushed que a recusa imprimiu. Isso remove a sessão e o worktree junto com seu branch, descartando os commits não enviados e quaisquer alterações não confirmadas.

  Quando você deleta novamente, Claude Code descarta apenas o que a recusa mostrou: se o worktree ganhou um commit desde então, Claude Code o mantém novamente e mostra o estado atualizado.

  Quando os registros de outra sessão concluída também nomeiam o worktree, ele permanece quando você deleta novamente; faça push dos commits, depois delete novamente.

• Um worktree que git não reconhece mais, por exemplo após git worktree prune, não bloqueia a deleção. Claude Code deleta a sessão e deixa o diretório em disco.

• Quando git ou seu hook WorktreeRemove falha em remover o worktree, Claude Code mantém o worktree e a sessão, e a mensagem nomeia a causa. Para um hook, a mensagem diz como terminou, como exited 1, e cita o início de seu stderr. A mensagem também diz qual destes fazer a seguir:

  • Delete a sessão novamente para remover o diretório mesmo assim, pressionando Ctrl+X duas vezes em sua linha em agent view ou executando o comando claude rm <id> --force-remove-worktree <worktree-id> que a recusa de claude rm imprimiu. Claude Code oferece isso apenas quando pode confirmar que o diretório é um dos worktrees vinculados do repositório sob .claude/worktrees/ sem alterações não confirmadas em arquivos rastreados, sem repositório aninhado dentro dele e sem registro de outra sessão nomeando-o. O branch do worktree permanece no repositório.
  • Corrija o que está no caminho, como fazer commit ou stash das alterações não confirmadas, fechar o que está usando o diretório ou corrigir o hook, depois delete a sessão novamente.
  • Remova o diretório você mesmo, depois delete a sessão novamente.

Um worktree que você criou você mesmo e iniciou a sessão dentro é deixado no lugar de qualquer forma.

Uma sessão cujo diretório de worktree não pertence a nenhum repositório git, porque o repositório foi deletado ou um hook WorktreeCreate criou o diretório em outro lugar, ainda pode ser deletada. Enquanto arquivos permanecem no diretório:

• Agent view pede o mesmo duplo Ctrl+X antes de descartá-los. Para um diretório criado por hook, ele executa seu hook WorktreeRemove em vez disso, e sem um, ele recusa a deleção e mantém a sessão.
• claude rm mantém a sessão e worktree, e nomeia o motivo.

Qualquer caminho mantém um diretório que os registros de outra sessão concluída nomeiam.

Set the model

O nome do modelo mostrado no cabeçalho de agent view é o padrão de despacho. Novas sessões que você inicia a partir da entrada usam este modelo, que vem da configuração model em suas settings de usuário. Defina-o selecionando um modelo no seletor /model, ou edite a configuração diretamente.

Para substituir o padrão de despacho para toda a sessão de agent view, passe --model ao abrir agent view. Veja Permission mode, model, and effort.

Para alterar o padrão de despacho de dentro de agent view, digite /model seguido de um nome de modelo na entrada de despacho e pressione Enter. O cabeçalho é atualizado para mostrar esse modelo com um marcador (session), e as sessões que você despacha depois usam-no. Digite /model default para limpar a substituição e retornar ao padrão de despacho. Essa substituição dura o resto da execução atual de claude agents e não escreve no seu arquivo de settings. O exemplo a seguir despacha uma sessão em Opus e a próxima em Sonnet:

/model opus
refactor auth
/model sonnet
run the test suite

Cada sessão em background pode ser executada em um modelo diferente. Para substituir para uma sessão:

• Do shell, passe --model com claude --bg.
• Anexe a uma sessão em execução e execute /model para alternar: uma escolha do seletor, ou um /model <name> digitado, salva como seu padrão para novas sessões a menos que você pressione s no seletor para uma alternância apenas de sessão. Uma alternância apenas de sessão persiste se a sessão for reiniciada.
• Despache um subagent cujo frontmatter define um campo model.

Permission mode, model, and effort

Uma sessão em background leva suas settings, provedor, permission mode, modelo e esforço de onde e como você a despachou. As subseções abaixo cobrem cada fonte e o que persiste quando o supervisor reinicia a sessão.

Settings and provider

Uma sessão em background lê suas settings do diretório em que é executada, da mesma forma que se você tivesse iniciado claude lá. Isso inclui valores env em settings de projeto, portanto uma ANTHROPIC_MODEL ou variável de provedor definida lá se aplica a toda sessão em background naquele diretório.

Uma sessão em background também é executada com o PATH do shell a partir do qual você a despachou, portanto os comandos que ela executa encontram as mesmas ferramentas que seu terminal faz. Ela mantém a seleção de provedor de nuvem daquele shell também, como CLAUDE_CODE_USE_BEDROCK ou CLAUDE_CODE_USE_VERTEX, junto com seus aliases ANTHROPIC_DEFAULT_*_MODEL e qualquer substituição CLAUDE_CODE_EXTRA_BODY que você exportou lá.

LLM gateway

Se você rotear Claude Code através de um LLM gateway, coloque as variáveis de gateway em um bloco env de um arquivo de settings em vez de exportá-las em seu shell, e as sessões em background as leem com o resto de suas settings. Set in a settings file mostra o bloco e qual arquivo de settings usar para a credencial.

Se você exportar um gateway ANTHROPIC_BASE_URL apenas em seu shell em vez disso, ele alcança uma sessão em background, junto com o ANTHROPIC_CUSTOM_HEADERS e credencial que você exportou com ele, apenas quando o supervisor foi ele próprio iniciado a partir de um shell que exportou o mesmo gateway, e apenas nestes casos:

• Você coloca sua própria sessão em background com ← ou /background
• Você despacha uma sessão para o diretório em que está
• Você acorda uma sessão parada no diretório em que está anexando ou respondendo a ela

Claude Code encaminha um gateway na frente de um provedor de nuvem. Se o shell a partir do qual você despacha seleciona o provedor e exporta seu endpoint de gateway com seu flag de bypass de auth, Claude Code encaminha o par endpoint-e-flag para a sessão sob as condições que se aplicam a ANTHROPIC_BASE_URL, junto com ANTHROPIC_CUSTOM_HEADERS. Por exemplo, exporte CLAUDE_CODE_USE_VERTEX=1 com ANTHROPIC_VERTEX_BASE_URL e CLAUDE_CODE_SKIP_VERTEX_AUTH=1, e Claude Code encaminha aquele endpoint e flag.

Claude Code aplica um gateway encaminhado apenas ao processo em execução daquela sessão e nunca o escreve em disco.

Permission mode

O permission mode depende de como você iniciou a sessão:

• Colocada em background com /bg ou ←: Claude Code mantém o permission mode em que a sessão estava, portanto uma que você alterou para acceptEdits ou auto permanece lá após desanexar
• Despachada a partir de um agent view que você abriu com ←: a configuração do alvo vem primeiro, e o permission mode da sessão da qual você veio se aplica quando nada mais define um
• Despachada a partir de claude agents iniciado em um shell, ou com claude --bg: a nova sessão começa da forma que uma nova sessão claude naquele diretório começaria, a menos que você a tenha despachado a partir de um agent view que você abriu com dispatch defaults. Which permission mode a session starts in lista a ordem

Para uma sessão que você despacha a partir de um agent view aberto com ←, Claude Code leva o permission mode do primeiro destes que se aplica:

1. O permissions.defaultMode do diretório alvo. Duas regras de fonte se aplicam:
   • auto e bypassPermissions têm efeito apenas a partir de settings gerenciadas, um arquivo --settings ou ~/.claude/settings.json.
   • Claude Code recusa um defaultMode do .claude/settings.json ou .claude/settings.local.json do projeto que seleciona um modo mais permissivo que o permission mode em que a sessão da qual você veio estava.
2. O permission mode da sessão da qual você veio

Quando Claude Code recusa o modo de uma fonte como muito permissivo, a próxima fonte na lista decide. Por exemplo, se você despacha a partir de uma sessão em plan mode para um diretório cujas settings verificadas pedem acceptEdits, a nova sessão começa em plan mode. Se você mover aquele defaultMode para ~/.claude/settings.json, ele se aplica independentemente do permission mode da sessão da qual você veio.

Permissividade corre plan, depois Manual e dontAsk, depois acceptEdits e auto, que cada um conta como mais permissivo que o outro, depois bypassPermissions.

Dispatch defaults

Para definir padrões para cada sessão que você despacha a partir de agent view, passe qualquer um de --permission-mode, --model, --effort ou --agent ao abri-lo:

claude agents --permission-mode plan --model opus --effort high

--effort aqui aceita os mesmos valores que o flag --effort de nível superior, incluindo ultracode.

--agent define o subagent usado quando um prompt de despacho não nomeia um, seja com @name ou como a primeira palavra. O padrão é a configuração agent se uma estiver definida, caso contrário o agente claude integrado catch-all. Nomear um subagent na entrada de despacho substitui ambos.

claude agents também aceita --dangerously-skip-permissions como abreviação para --permission-mode bypassPermissions, e --allow-dangerously-skip-permissions para tornar bypassPermissions disponível no ciclo Shift+Tab de cada sessão despachada sem iniciar naquele modo. Ambos correspondem aos flags CLI de nível superior.

Passe --restricted para iniciar cada sessão que você despacha a partir da visualização em restricted mode, como se cada uma fosse lançada com o flag de nível superior --restricted. Requer Claude Code v2.1.248 ou posterior.

Os padrões ativos aparecem no rodapé abaixo da entrada de despacho.

Claude Code recusa claude --bg --permission-mode bypassPermissions até que você tenha aceitado o aviso de bypass executando claude --dangerously-skip-permissions uma vez interativamente, já que esse modo permite que uma sessão que você não está observando aja sem aprovação. Passar --dangerously-skip-permissions ou --permission-mode bypassPermissions para claude agents mostra o mesmo aviso quando você não o aceitou antes, e aceitar aplica bypassPermissions às sessões que você inicia a partir da visualização. Passar --allow-dangerously-skip-permissions mostra o mesmo aviso também, e aceitar torna bypassPermissions disponível no ciclo Shift+Tab dessas sessões sem iniciá-las nele.

What persists across restarts

O permission mode, modelo e esforço que você escolheu para uma sessão em background, junto com os flags de configuração que ela carrega, todos persistem quando o supervisor mais tarde para e reinicia seu processo. Uma sessão que você lançou com claude --bg --dangerously-skip-permissions ou claude --bg --permission-mode bypassPermissions permanece em bypassPermissions após aquele reinício. Um modelo ou esforço que você alterou no meio da sessão com /model ou /effort é mantido também.

Se a sessão levou seu esforço de suas settings em vez de --effort ou /effort, Claude Code lê suas settings novamente cada vez que inicia um processo para a sessão. Depois que você edita o esforço salvo em settings.json, a mudança alcança sessões que você coloca em background com ← ou /bg, e seus reinícios posteriores. O esforço salvo é a chave effortLevel ou uma entrada modelSettings.

Claude Code também mantém um nome que você definiu com /rename ou Ctrl+R através daquele reinício, portanto você ainda pode executar claude --resume <name> para alcançar a sessão.

Um prompt que você guardou com Ctrl+S enquanto anexado é mantido com a sessão também. Reabra a sessão após seu processo ter sido parado ou reiniciado, e Ctrl+S restaura o texto guardado. Conteúdo colado no guarda não sobrevive ao reinício.

Settings, plugins, and MCP servers

Agent view aceita os mesmos flags de configuração que claude para carregar settings, plugins, servidores MCP e diretórios adicionais. Agent view aplica --settings e --plugin-dir a si mesmo e passa cada flag de configuração para as sessões que você despacha a partir dele, portanto um plugin ou servidor MCP que você carrega desta forma está disponível nessas sessões.

Repita --add-dir, --plugin-dir ou --mcp-config uma vez por valor. claude agents não suporta a forma separada por espaço, como --add-dir a b c.

Você pode colocar --settings e --plugin-dir antes ou depois de agents. Mantenha --add-dir e --mcp-config após agents: se você colocar qualquer um antes de agents, claude agents --json falha com um erro unknown option.

O exemplo a seguir abre agent view com uma substituição de settings e um diretório extra:

claude agents --settings ./ci-settings.json --add-dir ../shared-lib

--settings aceita um caminho de arquivo ou uma string JSON inline. Um caminho de arquivo deve apontar para um arquivo existente; Claude Code sai com um erro Settings file not found se não apontar.

Gerenciar sessões do shell

Cada sessão em background tem um ID curto que você pode usar do shell. O ID é impresso quando você inicia uma sessão com claude --bg, e o ID de cada sessão é seu nome de diretório em ~/.claude/jobs/. Esses comandos são úteis para scripts ou quando você não quer abrir agent view.

Listar sessões como JSON

claude agents --json imprime sessões ativas como um array JSON e sai: cada sessão ativa, mais sessões em background que ainda estão funcionando ou bloqueadas mesmo quando seu processo saiu. Adicione --all para também incluir sessões em background concluídas, e --cwd <path> para limitar a lista a sessões iniciadas sob esse diretório.

Cada entrada descreve uma sessão:

Ler estado da sessão de um script

claude agents --json é a forma suportada de ler estado da sessão de fora do Claude Code, por exemplo de uma barra de status, um agendador ou outra sessão Claude que supervisiona trabalho em background. Pesquise claude agents --json --all, que continua listando sessões cujo processo saiu, e leia state, status e waitingFor de cada entrada.

Uma sessão que terminou seu turno e está esperando sua próxima instrução lê done, não blocked. blocked sempre significa que a sessão precisa de algo de você antes de continuar.

Os arquivos em ~/.claude/jobs/<id>/ não são uma interface estável. Valores que uma sessão ou outro programa escreve em state, detail, tempo ou needs são substituídos na próxima atualização.

Se você quer que uma sessão relate progresso em suas próprias palavras, faça-a escrever um arquivo próprio, por exemplo em $CLAUDE_JOB_DIR/tmp, em vez de editar state.json.

Como as sessões em background são hospedadas

Claude Code trata cada sessão listada na visualização de agente como uma sessão em background, independentemente de você estar atualmente anexado a ela. Em contraste, uma sessão iniciada executando claude diretamente está vinculada a esse terminal e termina quando ele fecha, a menos que você a envie para o background.

Para verificar que tipo de sessão você está, execute /status. A linha Session kind lê background job · attached ou background job · unattended em uma sessão em background, dependendo se um terminal está anexado, e interactive em qualquer outra sessão.

O processo supervisor

O supervisor é um serviço em background que executa suas sessões em background para que continuem funcionando depois que você fecha a visualização de agente ou seu terminal. Claude Code o inicia na primeira vez que você coloca uma sessão em background ou abre a visualização de agente, e você não precisa gerenciá-lo.

Cada sessão é seu próprio processo Claude Code sob o supervisor, e o que acontece com esse processo depende do estado da sessão:

• Funcionando, pausado em um prompt de permissão ou outro diálogo, ou anexado: o processo continua em execução. Um subagent, workflow ou monitor em execução conta como funcionando.
• Terminado ou aguardando sua próxima mensagem, e desanexado por cerca de uma hora: o supervisor interrompe o processo para liberar recursos. Uma sessão que terminou seu turno fazendo uma pergunta a você conta como aguardando sua próxima mensagem. A conversa fica no disco, e na próxima vez que você anexar ou responder, a sessão retoma de onde parou. Fixe uma sessão com Ctrl+T para manter seu processo em execução.
• Saiu inesperadamente enquanto o supervisor está em execução: o supervisor reinicia o processo. Terminar uma sessão que você colocou em background com ← ou /background, por exemplo com kill, marca-a como parada em vez de reiniciá-la. Para sessões que terminaram com um desligamento, consulte Sessões aparecem como falhadas ou paradas após desligamento.
• Após uma atualização automática: o supervisor reinicia a si mesmo para a nova versão e move sessões inativas em background. Sessões que estão funcionando, aguardando você ou anexadas não são interrompidas.

Quando o processo de uma sessão para ou reinicia, os comandos de shell em background, workflows dinâmicos e subagents em background que Claude iniciou nela são transferidos para seu próximo processo; monitors em execução e comandos de shell que um subagent iniciou param com o processo. Deletar a sessão para tudo que ela transferiu. Para parar tudo com o processo em vez disso, defina CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF como 1.

O supervisor e suas sessões se autenticam com as mesmas credenciais armazenadas que suas sessões interativas. Para quais configurações e variáveis de shell chegam a uma sessão, incluindo PATH, consulte Configurações e provedor. Para endpoints de gateway, consulte Gateway LLM.

Onde o estado é armazenado

O estado da sessão é armazenado sob seu diretório de configuração Claude Code. Se você definir CLAUDE_CONFIG_DIR, o supervisor usa esse diretório em vez de ~/.claude e é executado como uma instância separada com suas próprias sessões.

Cada sessão em background tem a variável de ambiente CLAUDE_JOB_DIR definida para seu diretório ~/.claude/jobs/<id>, então comandos de shell que a sessão executa podem escrever arquivos temporários em $CLAUDE_JOB_DIR/tmp sem colidir com sessões paralelas.

Para inspecionar este estado sem ler os arquivos diretamente, execute claude daemon status. Ele relata se o supervisor está acessível, seu ID de processo e versão, o diretório do socket e quantas sessões em background estão ativas.

O comando também avisa quando o supervisor em execução está em uma versão diferente do claude que você invocou, o que acontece após uma atualização que o supervisor ainda não reiniciou. O aviso mostra ambas as versões e diz para você executar claude daemon stop --any para pegar a nova versão. Quando Claude Code é instalado como um serviço do SO, o comando sugerido é claude daemon stop sem a flag.

Sessões sobrevivem a esse desajuste de versão intactas: uma versão mais antiga do Claude Code que atualiza o state.json de uma sessão preserva campos que não reconhece e mantém a sessão listada. A lista de sessões em roster.json segue a mesma regra, então sessões iniciadas pela versão mais nova permanecem acessíveis e continuam aceitando entrada após o supervisor reiniciar.

Desativar a visualização de agente

Para desativar agentes em background e a visualização de agente completamente, defina a configuração disableAgentView como true ou defina a variável de ambiente CLAUDE_CODE_DISABLE_AGENT_VIEW. Os administradores podem impor isso através de configurações gerenciadas.

Troubleshooting

`claude agents` lista subagentes em vez de abrir a visualização de agentes

Se claude agents imprime uma contagem seguida pelos seus subagentes configurados e depois sai, a visualização de agentes não está disponível no seu ambiente. Execute claude update para instalar a versão mais recente.

Se a visualização de agentes ainda não abrir após atualizar, verifique se ela foi desativada por uma configuração ou variável de ambiente.

Agent view abre sem sessões

Antes de você despachar sua primeira sessão, agent view mostra os cabeçalhos de seção vazios com uma descrição sob cada um, mais uma explicação de uma linha acima da entrada, no lugar da lista de sessões. Digite um prompt na entrada na parte inferior e pressione Enter para despachar sua primeira sessão.

Backgrounding mostra um diálogo `Background this session?`

Se você pressionar ← para colocar a sessão atual em background e Claude Code mostrar um diálogo Background this session?, a sessão tem trabalho em andamento que o backgrounding interromperia, reiniciaria ou deixaria em execução sem supervisão, e Claude Code pergunta antes de fazer qualquer um desses:

• Trabalho que não pode se mover: a sessão tem trabalho que não pode se mover para a sessão em background, como um monitor em execução. O diálogo nomeia o trabalho que Claude Code interromperia e, separadamente, conta as tarefas que são transferidas.
• Um workflow com subagentes em execução: um dynamic workflow ainda tem subagentes em execução. O workflow em si é transferido, mas seus subagentes em execução reiniciam do início, e o diálogo diz quantos.
• Respostas automáticas de artefatos: Claude está respondendo a comentários em um artefato por conta própria. Essas respostas continuam na sessão em background, e o diálogo diz isso.

Execute /tasks para ver tudo que está em execução, depois confirme para colocar em background mesmo assim ou escolha Stay para deixar o trabalho terminar primeiro. Veja What carries over when you background para quais tipos de trabalho são transferidos e quais Claude Code interrompe.

Prompt rejected as too short

A entrada de dispatch espera uma descrição de tarefa, não um abridor conversacional. Um prompt com menos de quatro caracteres é rejeitado com uma dica Too short para que um pressionamento de tecla acidental não inicie uma sessão. Descreva o que você quer que a sessão faça, como investigate the flaky checkout test.

Sessions show as failed or stopped after shutdown

Desligar ou reiniciar sua máquina interrompe as sessões em execução em background. Uma sessão que estava aguardando sua entrada permanece sob Needs input quando você volta. Para qualquer outra sessão em execução, o que agent view mostra depende de quanto tempo atrás ela fez progresso pela última vez:

• Dentro de 48 horas, a sessão mostra como falhada. Anexe ou responda a ela e ela reinicia de onde parou.
• Passadas 48 horas, como após a máquina estar desligada por dias, a sessão mostra como parada com ended while the background service was off. Pressione Enter na linha e o rodapé mostra Press enter again to resume this session (it ended while the background service was off), or ctrl+x to delete it. Pressione Enter na mesma linha novamente para retomar sua conversa salva. Uma resposta, ou claude attach <id>, a retoma sem esse prompt de rodapé.

Quando transcript cleanup removeu a conversa salva de uma sessão parada, Claude Code recusa abrir a linha: a mensagem diz que não há nada para retomar. claude rm <id> deleta a linha, exceto nos casos mantidos descritos acima, e claude respawn <id> executa seu prompt original novamente. Veja This session's saved conversation is no longer on disk.

Sleep sozinho não interrompe as sessões. Sessões são preservadas durante o sleep e o supervisor se reconecta a elas ao acordar.

Opening a session says the conversation is already open

Dois processos não podem escrever no mesmo transcript. Quando a conversa salva de uma sessão parada já está aberta em outro processo Claude Code ao vivo, Claude Code recusa iniciar o processo da sessão. O que você vê depende do que mantém a conversa:

• Um terminal onde você retomou a conversa, por exemplo com claude --resume ou /resume: a linha mostra Open in a terminal com uma dica para continuar lá, e abrir a linha mostra Can't open — this session is running in another terminal. Continue naquele terminal, ou saia dele e abra a linha novamente.
• Outro processo Claude Code não interativo, por exemplo um processo de sessão em background para a mesma conversa que ainda não saiu: abrir a linha mostra This conversation is already open in another running Claude session. Use esse processo, ou aguarde sua saída e abra a linha novamente.

Claude Code salva uma resposta que você digitou com a tentativa recusada e a envia na próxima vez que a sessão inicia.

Opening a session says it has no saved transcript

Uma sessão parada que foi backgrounded from another conversation e parou antes de sua primeira resposta terminar não tem nada para retomar: até que essa primeira resposta termine, a conversa ainda vive apenas na sessão de que foi backgrounded. claude attach recusa abrir com This session has no saved transcript.

Em agent view, abrir essa linha mostra Press enter again to restart this session fresh abaixo da lista. Pressione Enter na mesma linha novamente para reiniciar a sessão com uma conversa vazia, ou execute claude respawn <id> do shell.

A conversa original está intacta; retome-a com claude --resume ou continue trabalhando nela. Veja a referência de erro para detalhes.

The terminal host died or the session stopped responding

O supervisor executa o terminal de cada sessão em background em seu próprio processo host. Quando esse processo morre ou para de responder, Claude Code mostra o motivo e oferece uma reinicialização; em ambos os casos a conversa é salva e a reinicialização a retoma. A referência de erro cita as mensagens completas.

Claude Code nunca reinicia uma linha executando um shell command, de Enter ou de claude attach, porque isso executaria o comando novamente; a mensagem da linha e claude attach ambas dizem que o comando não é executado novamente.

Terminal host died

No Linux e WSL, o supervisor verifica cada processo host a cada poucos segundos, independentemente de você abrir a sessão ou não, e marca a sessão como falhada quando o processo saiu mas sua conexão com o supervisor nunca fechou.

• Em agent view, a linha mostra terminal host process died — press Enter to restart. Pressione Enter nela e Claude Code reinicia a sessão em um novo processo host.
• Do shell, claude attach <id> reinicia uma sessão já marcada como falhada. Caso contrário, relata a causa e sai, dizendo-lhe para executar claude attach <id> novamente.

Session isn't responding

Quando o supervisor aceita uma abertura mas nenhuma saída chega por cerca de dez segundos, Claude Code encerra a tentativa e oferece uma reinicialização. Uma sessão que meramente travou, por exemplo durante o sleep da máquina, não chega a essa oferta: o supervisor a reinicia ao abrir por conta própria.

• Em agent view, o rodapé mostra Press enter again to restart this session — it isn't responding (its conversation is saved and resumes). Pressione Enter na mesma linha novamente e Claude Code interrompe o processo que não responde e reinicia a sessão; ele não interrompe nada sem esse segundo pressionamento.
• Do shell, claude attach <id> relata a causa e sai, dizendo-lhe para executar claude stop <id>, depois claude attach <id>.

A session fails before starting with a `possibly low memory` note

Quando o processo de uma sessão em background sai antes de terminar de iniciar e o host está com pouca memória, o status da linha nomeia a saída e adiciona possibly low memory — free some up and retry.

A nota é uma hipótese, não uma causa confirmada. Claude Code a adiciona apenas quando o processo saiu silenciosamente, sem escrever um erro e sem ser interrompido por um sinal, e o host relatou pouca memória naquele momento. Quando o processo escreveu um erro antes de sair, a linha mostra esse erro em vez disso.

Libere memória na máquina, depois anexe ou responda à linha e o supervisor inicia um novo processo para a sessão. Quando a memória permanece baixa, o supervisor também interrompe sessões ociosas para liberar recursos por conta própria, e interrompe sessões fixadas ociosas também se interromper as outras não liberou nada.

Agent view says the background service did not respond

Se anexar, espreitar ou claude logs relatar que o serviço de background não respondeu, o processo supervisor provavelmente travou. Interrompa-o e deixe o próximo claude agents iniciar um novo. Para manter suas sessões em background em execução durante a reinicialização, passe --keep-workers:

claude daemon stop --any --keep-workers

O novo supervisor se reconecta às sessões em execução. Sem --keep-workers, o comando também encerra as sessões em background. O sinalizador --any confirma que você deseja interromper um supervisor que foi iniciado sob demanda em vez de como um serviço instalado, que é o padrão.

Um supervisor que inicia mas não consegue aceitar conexões sai e libera seu bloqueio por conta própria, portanto o próximo claude agents inicia um novo sem essa parada manual. Os passos acima se aplicam quando um supervisor em execução trava.

Se o comando em vez disso sair dizendo que o processo registrado não pôde ser verificado como o supervisor, verifique o ID do processo relatado: se for um supervisor que você possui, interrompa-o você mesmo, depois delete ~/.claude/daemon.lock para que o próximo claude agents inicie novo.

No Windows, se o supervisor não responder à solicitação de parada, o comando imprime seu ID de processo. Encerre esse processo com taskkill /PID <pid> para concluir a recuperação. As sessões em background ainda são preservadas quando você passou --keep-workers.

Dispatch fails with `Could not resolve authentication method`

Se um dispatch em background falhar com Could not resolve authentication method enquanto sessões interativas autenticam normalmente, o worker que recebeu o dispatch não pegou as credenciais. Sessões em background obtêm suas credenciais do supervisor, então esse erro significa que nenhuma credencial armazenada estava disponível para o próprio processo supervisor. Confirme que você executou /login ou configurou uma chave de API, depois interrompa o supervisor:

claude daemon stop --any --keep-workers

O próximo claude agents ou claude --bg inicia um novo supervisor que lê suas credenciais armazenadas. Se você autenticar com uma variável de ambiente como ANTHROPIC_API_KEY em vez de /login, execute esse próximo comando a partir de um shell onde a variável está definida.

Veja a referência de erro para a lista completa de causas e correções.

Background sessions can't read Desktop, Documents, or Downloads on macOS

No macOS, o host da sessão em background é executado como seu próprio processo e solicita acesso a pastas protegidas separadamente do seu terminal. Se uma sessão em background relatar Operation not permitted ao ler ~/Desktop, ~/Documents, ~/Downloads ou outro local protegido, conceda acesso em Configurações do Sistema em Privacidade e Segurança > Arquivos e Pastas, ou ative Acesso Total ao Disco para a entrada.

Com o instalador nativo, a entrada aparece como Claude Code e a concessão persiste entre atualizações. Com outros métodos de instalação, como Homebrew ou npm, a entrada mostra o caminho do binário e pode precisar ser concedida novamente após atualizar.

Background sessions can't reach local-network hosts on macOS

No macOS 15 e posterior, o sistema bloqueia um processo de alcançar dispositivos na sua rede local até que você conceda permissão de Rede Local, então um comando direcionado a um endereço LAN pode falhar com connect: no route to host em uma sessão em background mesmo que funcione em um terminal em primeiro plano. O primeiro comando em uma sessão em background que se conecta a um endereço de rede local dispara o prompt de permissão de Rede Local do macOS para Claude Code. Conceda uma vez e esses comandos alcançam hosts LAN da mesma forma que fazem em um terminal em primeiro plano.

A session is slow to respond after attaching

Quando uma sessão que terminou ou está aguardando sua próxima mensagem fica desanexada por cerca de uma hora, o supervisor interrompe seu processo para liberar recursos. Anexar inicia um novo processo de onde parou e muda para a sessão imediatamente enquanto o processo reinicia. Sessões que estão funcionando, pausadas em um prompt de permissão ou outro diálogo, ou fixadas não são interrompidas dessa forma, portanto fixe uma sessão com Ctrl+T para mantê-la responsiva.

Enquanto o processo inicia, Claude Code mostra a cauda da transcrição da sessão formatada da forma que a sessão ao vivo a renderiza, com markdown, blocos de código destacados e chamadas de ferramenta como linhas esmaecidas, acima de uma área de prompt esmaecida com uma nota Session is starting. A sessão ao vivo a substitui assim que estiver pronta.

`.claude/worktrees/` is filling up

Deletar uma sessão em agent view remove a worktree que Claude criou para ela, mas alguns deletes mantêm a worktree ou deixam seu diretório no disco, então diretórios restantes podem se acumular. Diretórios que git não reconhece mais não aparecem em git worktree list, então remova aqueles à mão.

Liste entradas restantes com git worktree list no diretório do projeto e remova cada uma com git worktree remove <path>. Veja Clean up worktrees.

Limitações

Agent view está em visualização de pesquisa com as seguintes limitações:

• Limites de taxa se aplicam: sessões em background consomem o uso de sua assinatura da mesma forma que sessões interativas, então executar dez agentes em paralelo usa cota aproximadamente dez vezes mais rápido do que executar um.
• Sessões são locais: sessões em background são executadas em sua máquina. Elas são preservadas durante o sleep, mas param se a máquina desligar.
• Worktrees criadas pelo Claude são deletadas com a sessão em agent view: confirme as alterações antes de deletar uma sessão que editou arquivos em seu próprio worktree. Algumas exclusões mantêm o worktree em vez disso.

Recursos relacionados

Para outras maneiras de executar Claude em paralelo e para passar descobertas entre as sessões que você executa, consulte:

• Executar agentes em paralelo: compare agent view com subagentes, equipes de agentes e worktrees
• Mensagens entre sessões: tenha suas sessões passando descobertas uma para a outra
• Equipes de agentes: coordene múltiplas sessões que se mensageiam
• Use Claude Code na nuvem: execute sessões em um ambiente de nuvem gerenciado em vez de localmente
• Projects: tenha Claude coordenar sessões de nuvem paralelas de uma conversa e diga a você quais você precisa

Histórico de versões

Agent view evoluiu rapidamente durante a visualização de pesquisa. Se você estiver em uma versão mais antiga do Claude Code, alguns comportamentos nesta página podem diferir; em particular, claude agents rejeita flags que ainda não suporta com um erro de unknown option. A tabela abaixo lista quando cada flag e comportamento foi adicionado.