Waypoint MCP server

Waypoint

<!-- mcp-name: io.github.STiFLeR7/waypoint-mcp -->

Waypoint keeps one project log across your AI coding tools, so you can see where work stopped and what comes next.

You switch between projects and between Claude Code, Codex and ChatGPT. Each tool has its own memory, but none of them knows what the others did. Waypoint gives every tool the same record per project (what it is, where you left off, what's next, what needs attention), and shows where that record has fallen behind the actual activity.

The story: each project is a voyage, each AI tool a navigator, and the logbook is the ship's log they all write to. The dashboard is the chart.

It deals with two kinds of truth:

• Facts (where and when): which project, which tool, when, the last commit. Waypoint harvests these automatically from the tools' own local history and from git.
• Meaning (what and why): what got done, what's next, what's in the way. The AI tool writes this down as a short log entry, following one shared rule.

Where the two disagree, the chart says so. A tool that worked on a project but logged nothing leaves an unlogged watch (session). That's how the chart keeps itself honest, even when a tool forgets the rule.

$ waypoint refresh
Dashboard refreshed: 3 projects, 1 active this week, 1 attention item, 1 with unlogged sessions, 1 stale, 1 untracked folder.

That's the fictional logbook in examples/logbook/: its chart shows each case. waypoint refresh also writes chart.html, the same chart as a page you open in your browser.

Get started

Requires Python 3.11 or newer; no other dependencies. The arrow-key screen is optional: install waypoint-mcp[tui] (adds Rich and prompt_toolkit) and run waypoint.

macOS / Linux

pipx install waypoint-mcp         # or: python -m pip install waypoint-mcp
waypoint setup                    # fitting out: logbook, roots, the rule and MCP server for each AI CLI it finds
waypoint add ~/code/my-project    # chart a voyage (project); once per project
waypoint refresh                  # refresh the dashboard: DASHBOARD.md, dashboard.json and chart.html (--open opens it)
waypoint status                   # everything at a glance, with fixes for problems
waypoint archive <project>        # hide a finished project, keep its log (also: restore, remove, ignore)

Windows (PowerShell)

py -m pip install waypoint-mcp
waypoint setup
waypoint add $HOME\code\my-project
waypoint refresh

• waypoint not found? Its install folder isn't on PATH, and AI tools need it there too (they start waypoint mcp). Installed with pipx: run pipx ensurepath, then open a new terminal. Installed with pip: add the scripts folder pip warned about to PATH; until then python -m waypoint … (Windows: py -m waypoint …) runs it with that same Python.
• The screen (pipx install "waypoint-mcp[tui]"): waypoint setup walks through logbook, roots, projects and AI tools, shows every change in a Review and writes nothing before Apply; waypoint alone then manages projects (archive, restore, remove, ignore, track) and tools (connect, disconnect, fix drift) and shows status. Keys: ↑↓ move, Space toggle, Enter next, ← back, / search, Esc quit. Every action is also a plain command; without the extra, or with any setup flag, you get numbered prompts. NO_COLOR is honoured.
• setup shows every file it would change and asks once. It remembers the logbook, so later commands need no --logbook. It never edits your own CLAUDE.md or AGENTS.md text: it adds Waypoint's own file or a marked block, and waypoint rules --uninstall removes exactly those.
• Make the logbook a private git repo, then waypoint refresh --push pulls, redraws, commits only logbook data, and pushes.
• From a clone of this repo: python -m pip install -e .

Who's aboard

Shortened. The full README is on GitHub.