Session Recording
How Waypoint captures agent sessions automatically using the Stop hook.
The Stop hook
Supported agents fire a Stop event after every agent turn — when the agent finishes responding and control returns to the user. Waypoint registers a hook for this event during waypoint init:
{ "hooks": { "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "waypoint generate" }] }] }}This is written to .claude/settings.json. Claude Code reads this file natively; VS Code GitHub Copilot (Preview) reads the same file. Every time a session turn ends, waypoint generate runs automatically — no manual steps required.
For agents without native Stop hook support, waypoint generate can be run manually from the terminal after a session. See Agent Compatibility.
What waypoint generate captures
waypoint generate reads the session transcript from stdin (provided by the agent's hook system) and builds a structured event log. No AI summarisation happens at capture time — raw events are stored as-is. This keeps the hook fast, cheap, and free of any API key dependency.
Session metadata:
| Field | Description |
|---|---|
id | Session ID from the transcript |
date | Session date |
username | System username of the developer |
agentModel | Agent model used (e.g. claude-sonnet-4-6) |
gitBranch | Active branch |
gitCommit | Latest commit SHA at time of capture |
committedFiles | Files committed during the session |
uncommittedFiles | Files changed but not yet committed |
gitRepo / gitOrg | Repository and GitHub org name |
Event types:
| Type | What it captures |
|---|---|
user_prompt | Prompts from the developer |
agent_response | Text responses from the agent |
agent_plan | Task lists from TodoWrite — each item with content, status (pending / in_progress / completed), and optional priority |
bash_command | Shell commands and their exit codes; flagged thirdParty: true when the command invokes an external service (see below) |
file_edit | File edits — path and tool used (Edit, Write, MultiEdit) |
file_read | Files read by the agent |
tool_use | MCP and other tool calls; flagged thirdParty: true for non-Waypoint MCP tools |
waypoint_context | Records when the agent called get_waypoint_context, including whether prior history was found |
Events are stored in order, preserving the full arc of a session: what was asked, what was planned, what was tried, what failed, and what was ultimately committed.
Third-party service detection
bash_command and tool_use events are automatically flagged as thirdParty: true when they involve an external service:
- Known external CLIs —
railway,gh,aws,gcloud,az,stripe,heroku,vercel,fly,firebase,supabase,doppler,twilio,netlify,wrangler,pulumi,terraform,helm, and others - HTTP clients to external URLs —
curlorwgetcalls to non-localhost addresses - Non-Waypoint MCP tools — any MCP tool call (via
mcp__*prefix) that isn'tget_waypoint_contextorlist_waypoints
These events are highlighted in the session UI — orange in the timeline bar, an ↗ external badge on the event card, and listed in the "External service calls" sidebar section.
Storage
Sessions are posted to the Waypoint server after every turn:
[waypoint] Posted to server https://waypoint.yourcompany.com[waypoint] DoneThe server stores sessions in its database, indexes them by the files they touched, and makes them available to every developer on the team via get_waypoint_context and list_waypoints.
Sessions are not written to local files or committed to git. This keeps the repository clean and ensures all developers query the same shared history.
If no server is configured, the hook exits with a warning and the session is not saved:
[waypoint] No server configured — session not saved. Run `waypoint connect <url>` to set up.Run waypoint connect <server-url> to configure the server.