Session Management

Helm persists all state so work survives across Claude Code conversations. Session files, handoffs, artifacts, and checkpoints ensure nothing is lost.

How It Works

1. helm init creates .helm/session.yaml and helm.yaml
2. Agents run inside Claude Code via /helm and update session state
3. helm save checkpoints state for safe session handoff
4. helm resume shows where to pick up in a new Claude Code session

File Structure

.helm/                    # Runtime state (gitignored)
  session.yaml            # Current session state
  session.yaml.backup     # Auto-backup before every write
  handoffs/               # Agent-to-agent handoff documents
  artifacts/              # Per-agent output (reports, specs)
  checkpoints/            # Session snapshots (max 5, FIFO rotation)

helm.yaml                 # Project config (committed)

session.yaml

The central state file tracking project info, current agent, execution profile, and agent completion status.

project:
    name: my-api
    type: brownfield
    state: build
execution_profile: guided
current_agent: build
language: en-US
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

Project configuration committed to version control.

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

Handoffs

Each completed agent writes a handoff at .helm/handoffs/{agent}.md with YAML frontmatter and content:

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

# Research Handoff

## Summary
...

The next agent reads this handoff before starting. Missing handoffs block progression.

Artifacts

Agents produce artifacts stored at .helm/artifacts/{agent}/:

Checkpoints

helm save validates session integrity before checkpointing:

• Checks required fields in session.yaml
• Verifies handoff files exist for completed agents
• Verifies artifact directories exist for completed agents
• Rotates old checkpoints (keeps last 5, FIFO)
• Auto-backs up session.yaml before writing

Cross-Session Continuity

To resume work in a new Claude Code session:

1. Run helm resume to see current state and next steps
2. Open Claude Code and type /helm
3. The orchestrator reads session state and routes to the correct agent
4. The agent reads its predecessor's handoff and continues from there