Recording Sessions

Recording starts with an explicit session and ends with a replay URL.

Start with record_start

Call record_start from an MCP-capable harness or a slash-command wrapper.

{
  "name": "Add JWT auth with refresh token",
  "harness": "claude-code",
  "agentName": "Claude",
  "workspaceName": "api-service"
}

The response includes the session ID and the public replay route:

{
  "sessionId": "2c0e9a50-9f8d-4e74-9cf8-4cb4c9b678e1",
  "status": "recording",
  "replayUrl": "https://looma-gold.vercel.app/sessions/2c0e9a50-9f8d-4e74-9cf8-4cb4c9b678e1"
}

Capture live events

While the session is active, Looma accepts normalized events from hooks or explicit record_event calls. Common event types include:

• terminal_command
• terminal_output
• file_diff
• file_read
• test_result
• session_checkpoint

Claude Code hooks can capture Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS, and failure events. The replay page can update while events arrive.

Stop with record_stop

Call record_stop when the agent is done.

{
  "sessionId": "2c0e9a50-9f8d-4e74-9cf8-4cb4c9b678e1",
  "finalOutput": {
    "title": "Final answer",
    "content": "Shipped the auth flow and verified login, refresh, and logout paths.",
    "format": "markdown"
  }
}

The finalOutput field is optional. Passing it makes the final agent response visible on /sessions/{sessionId} without digging through the timeline.

After stop, Looma marks the session as processing and prepares replay metadata.

{
  "sessionId": "2c0e9a50-9f8d-4e74-9cf8-4cb4c9b678e1",
  "status": "processing",
  "replayUrl": "https://looma-gold.vercel.app/sessions/2c0e9a50-9f8d-4e74-9cf8-4cb4c9b678e1"
}

record_stop is idempotent for completed or already-processing sessions. If Claude Code hooks also fire around the stop call, Looma returns the existing session/replay state instead of creating duplicate replay metadata.

Open the replay

Open /sessions/{sessionId} to review the session timeline, terminal output, diffs, test results, final output, chapters, notes, and Needs Review markers.