Gerenciamento de Sessões

O Helm persiste todo o estado para que o trabalho sobreviva entre conversas do Claude Code. Arquivos de sessão, handoffs, artefatos e checkpoints garantem que nada se perca.

Como Funciona

1. helm init cria .helm/session.yaml e helm.yaml
2. Agentes rodam dentro do Claude Code via /helm e atualizam o estado da sessão
3. helm save faz checkpoint do estado para handoff seguro
4. helm resume mostra onde retomar em uma nova sessão do Claude Code

Estrutura de Arquivos

.helm/                    # Estado em tempo de execução (gitignored)
  session.yaml            # Estado atual da sessão
  session.yaml.backup     # Auto-backup antes de cada escrita
  handoffs/               # Documentos de handoff entre agentes
  artifacts/              # Saída por agente (relatórios, specs)
  checkpoints/            # Snapshots da sessão (máx 5, rotação FIFO)

helm.yaml                 # Configuração do projeto (commitado)

session.yaml

O arquivo de estado central que rastreia informações do projeto, agente atual, perfil de execução e status de conclusão dos agentes.

project:
    name: my-api
    type: brownfield
    state: build
execution_profile: guided
current_agent: build
language: pt-BR
workflow: standard
agents:
    survey:
        status: completed
        score: 100
        timestamp: "2026-03-24T23:00:00Z"
    research:
        status: completed
        score: 100
        timestamp: "2026-03-24T23:15:00Z"

helm.yaml

Configuração do projeto commitada no controle de versão.

version: v0.1
installed_at: "2026-03-24T22:39:37Z"
project_type: brownfield
language: pt-BR

Handoffs

Cada agente completado escreve um handoff em .helm/handoffs/{agente}.md com frontmatter YAML e conteúdo:

---
agent: research
status: completed
score: 100
next_agent: planning
blockers: []
timestamp: 2026-03-24T23:15:00Z
---

# Research Handoff

## Summary
...

O próximo agente lê este handoff antes de começar. Handoffs ausentes bloqueiam a progressão.

Artefatos

Agentes produzem artefatos armazenados em .helm/artifacts/{agente}/:

Checkpoints

helm save valida a integridade da sessão antes de fazer checkpoint:

• Verifica campos obrigatórios em session.yaml
• Verifica que arquivos de handoff existem para agentes completados
• Verifica que diretórios de artefatos existem para agentes completados
• Rotaciona checkpoints antigos (mantém últimos 5, FIFO)
• Faz auto-backup de session.yaml antes de escrever

Continuidade Entre Sessões

Para retomar o trabalho em uma nova sessão do Claude Code:

1. Execute helm resume para ver o estado atual e próximos passos
2. Abra o Claude Code e digite /helm
3. O orquestrador lê o estado da sessão e direciona para o agente correto
4. O agente lê o handoff do predecessor e continua de lá