Introduction
Waypoint is a development record system for AI-assisted codebases. Git stores what changed. Waypoint stores why.
AI coding agents — Claude Code, GitHub Copilot, Cursor, and others — are powerful at execution but have a fundamental context limitation: they understand the current state of a codebase, but not the history of decisions that produced it. This is often described as "agents start cold." That is not quite right. Agents have access to CLAUDE.md, memory systems, long context windows, and project instructions. They know what the code is. What they don't know is why it is that way:
- Why was this approach chosen over the alternatives?
- What was tried before, and why did it fail?
- Why does this function look overcomplicated — was there a reason?
- What constraint drove this architecture decision?
Git commit messages capture some of this, but only at commit time, only in summary form, and only for what made it in. The reasoning behind uncommitted work, abandoned approaches, and mid-session pivots is lost entirely. This matters more as AI agents take larger shares of development work. When a human writes code, they carry context in their head and transfer it through review and conversation. When an agent writes code, the reasoning lives only in the transcript of that session — and that transcript is ephemeral.
Waypoint makes the transcript persistent and queryable.
What it does
Waypoint has four phases:
| Phase | What happens |
|---|---|
| Capture | A Stop hook fires after every agent turn and records the session as a structured event log — prompts, plans, file reads and edits, bash commands, tool calls, git state. No AI summarisation. No API key. Just structured logging. |
| Store | The session is posted to the Waypoint server, which indexes it by the files it touched and makes it available to every developer on the team. Sessions are not committed to git — the repo stays clean. |
| Reinject | At the start of a new session, the agent calls get_waypoint_context(filepath) via MCP to get the history of a specific file, or list_waypoints() to see what was worked on recently across the repo. The agent synthesises what is relevant to the current task. |
| Share | Because sessions live on the server rather than in individual git histories, context recorded by one developer is immediately available to every other developer — without any merge, sync, or additional workflow. |
Summarisation happens at query time, not capture time. The reading agent is already Claude (or Copilot, or another capable model) — it is better placed to weight what is relevant than a pre-computed summary written without knowing what would be asked.
Who it's for
Teams using AI agents in shared codebases — When multiple developers use AI agents on the same codebase, each agent session starts without knowledge of what previous sessions decided. An agent session last Tuesday already tried this approach and abandoned it for a specific reason. Without Waypoint, the next developer's agent tries it again. Work gets repeated. Mistakes get repeated. Waypoint solves the team context problem without requiring developers to write additional documentation.
Individual developers on complex, long-running projects — Even solo, a developer returning to a module after two weeks faces the same problem. The reasoning behind decisions fades. With Waypoint, the agent reading context at the start of a session gets the actual decision history automatically.
Engineering organisations adopting AI-assisted development at scale — At scale, the loss of decision context is an audit and compliance problem as much as a productivity problem. Waypoint provides a structured record of what agents did, why, and when — queryable by file, by developer, by session, by commit.
Agent compatibility
Claude Code (CLI, desktop, VS Code, JetBrains) — full automatic capture and retrieval. All surfaces share the same .claude/settings.json hook; waypoint init covers all of them.
VS Code GitHub Copilot (IDE) — automatic capture and retrieval (Preview). VS Code's agent hooks read .claude/settings.json by default, so no extra setup is needed beyond waypoint init.
Cursor (IDE) — retrieval works today; capture is unverified. The stop hook delivers transcript_path, but Cursor's transcript format hasn't been validated against Waypoint's parser. Manual hook wiring required.
Windsurf (IDE) — retrieval only. Windsurf has no session-end hook; its per-turn hook requires a different integration model not yet implemented.
Session records are model-neutral — a session captured in Claude Code is fully readable in Cursor or Windsurf via MCP.
See Agent Compatibility for full configuration details.
What makes it different
It does not require developers to write documentation. Every existing approach to preserving AI decision context requires the developer to do something extra: write an ADR, update a wiki, annotate a commit message. Waypoint captures context automatically as a side effect of the agent session. There is no additional workflow.
It is not a summary — it is a record. AI-generated summaries of sessions are tempting but lossy. A summary reflects what the summarising model thought was important, not necessarily what will be relevant to a future session. Waypoint stores raw events and lets the reading agent decide what is relevant to the current task.
It is keyless and fast at capture time. The Stop hook does not call any AI API. It parses the transcript locally and posts it to the server. There is no latency cost from summarisation, no per-session AI spend, and no external API dependency in the capture path.
It keeps git clean. Sessions are stored on the server, not committed to the repository. Developers don't accumulate .wp files in their git history, and the repo doesn't grow with every session.
Context is shared automatically. Because sessions are on the server, every developer's agent queries the same history. There's no need to commit, push, or sync session files — context from one developer's session is available to every other developer immediately.
Deployment options
| Scenario | Platform | Database |
|---|---|---|
| Laserowl Cloud | Managed — no setup needed | Managed Postgres |
| Self-hosted cloud | Railway, Render, Vercel, Netlify | External Postgres |
| On-premises | Docker Compose (any Linux server) | Bundled Postgres |
| Enterprise on-prem | Docker Compose + private registry | Postgres (your infra) |
Next steps
- Installation — install the CLI and run
waypoint init - Quick Start — walk through your first recorded session
- Session Recording — exactly what gets captured and how