Metadata-Version: 2.4
Name: waypoint-mcp
Version: 0.3.0
Summary: Every voyage, every navigator, one chart: track your projects across Claude Code, Codex, Gemini CLI, Copilot CLI and ChatGPT.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/STiFLeR7/waypoint-mcp
Project-URL: Issues, https://github.com/STiFLeR7/waypoint-mcp/issues
Project-URL: Changelog, https://github.com/STiFLeR7/waypoint-mcp/blob/main/CHANGELOG.md
Keywords: mcp,model-context-protocol,claude-code,codex,ai-agents,project-tracking,logbook
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tui
Requires-Dist: rich>=13; extra == "tui"
Requires-Dist: prompt_toolkit>=3; extra == "tui"
Dynamic: license-file

# Waypoint

**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/`](examples/logbook/): its [chart](examples/logbook/DASHBOARD.md) 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**
```bash
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)**
```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

Automatic session history (which project, which tool, when) comes from **Claude Code and Codex** only. The other tools follow the rule and can use the MCP tools, but their sessions don't show up on their own.

| Navigator (AI CLI) | Tier | What Waypoint wires |
|---|---|---|
| **Claude Code** | Supported | the rule, the local MCP server, session facts |
| **Codex** (CLI and desktop) | Supported | the rule, the local MCP server, session facts |
| Gemini CLI | Preview | the rule, the local MCP server |
| GitHub Copilot CLI | Preview | the rule, the local MCP server |
| Cursor, Windsurf, Kiro, Cline, Claude Desktop, Goose, opencode, Amp | Snippet | `waypoint connect <cli>` prints the config to paste; writes nothing |
| ChatGPT | Beacon | remote MCP server you host ([Raise the beacon](#raise-the-beacon)) |

- **The rule** tells the tool to add a log entry after meaningful work. **The local MCP server** (`waypoint mcp`, stdio) gives it four tools: `take_fix` (the overview), `read_chart` (one project), `log_watch` (append one log entry, with the tool's own id, under a lock; with `done`/`next` it also updates Done, Next and Updated in Now), and `status` (whether Waypoint is set up right: states and counts only, no paths).
- `waypoint connect <cli>` wires one CLI at any time, for every project. Add `--project <repo>` (repeatable) to wire only that repo: the rule goes into the repo (an import, a link to the logbook's rule, or a copied block) and the MCP entry is scoped to it; files Waypoint creates there stay out of git through `.git/info/exclude`. `waypoint disconnect <cli> [--project <repo>]` removes only what Waypoint added.
- MCP servers are registered through each CLI's own `mcp add` command where it has one (Codex and Copilot CLI per repo: Waypoint edits their repo file). If another server already uses the name `waypoint`, Waypoint registers as `waypoint-local`; `--no-mcp` installs only the rule. For Codex, Waypoint also offers to add the logbook to its sandbox's `writable_roots` (`--no-writable-root` skips it).
- `waypoint rules` reports each tool's rule: in sync, drifted, missing, or shadowed (Codex reads an `AGENTS.override.md` instead).
- **Known limits:** Claude Code deletes transcripts after 30 days by default. The Claude Code and Codex history formats are unofficial; the chart's source health says when a reader breaks.

## Reading the chart

| On the chart | Plain meaning |
|---|---|
| **Voyage**: underway / coasting / at anchor / in port | project: active / occasional / paused / done |
| **Hazards** | `- Attention:` lines, plus drifted rules and unreadable sources |
| **Unlogged watches** | AI sessions after the day of the project's last log entry |
| **Now behind log** | `## Now` was last updated before the newest log entry |
| **Adrift** | idle past its threshold (21 days if active, 60 if occasional) |
| **Uncharted waters** | folders with recent AI activity but no project file |
| **Harbour** | `projects/_archive/`: finished voyages, never deleted |

Waypoint never changes a project's Status, never archives, and never writes a log entry on its own: it flags, and you decide.

## What the signals mean

- **Activity** means a tool touched the project (a session, a commit or a log entry). It doesn't mean work got done.
- **Unlogged sessions** are Claude Code and Codex sessions from the day after the newest log entry onward. Log entries carry a date, not a time, so work later on the same day as an entry counts as logged.
- **Now behind log** means the project's `## Now` was last updated (its `- Updated:` date) before the newest log entry, so *Where you left off* and *Next* may be out of date. Projects without an `Updated` line never show it; `log_watch` sets it when you pass `done`/`next`.
- **A log entry** records what someone wrote down. It doesn't verify the code.
- **Available context** isn't proof that an agent read it.
- **Freshness:** `chart.html` and `DASHBOARD.md` are snapshots from the last `waypoint refresh`. The local MCP server reads the logbook live (AI activity is cached for up to 30 seconds). The beacon's dashboard fields are as of the last push; its log entries are read live.

## Privacy

- **Nothing leaves the machine on its own.** The engine has no listener, sends no network requests, and keeps no telemetry. `--push` runs git against the remote you configured.
- **The local MCP server answers only the AI tool that started it.** That tool sends the results to its model provider, as it does with anything it reads. Results hold project names, statuses, Summary, Done, Next and recent log entries. **Attention lines are left out** unless `waypoint.toml` sets `[mcp] include_attention = true`. Session titles, file paths, untracked folders and the feed are never returned.
- Log text is free text: what you or your tools write there goes wherever those results go. Returned text is data for the tool, never instructions.

## The three hulls

| Hull | What | Where |
|---|---|---|
| **Engine** | This repo: the spec, the `waypoint` CLI, templates, tests | installed from PyPI |
| **Logbook** | *Your* data: one Markdown file per project, plus the chart | its own private git repo |
| **Playground** | Experiments and prototypes | wherever you like |

They're never mixed: the engine ships, and the logbook stays yours.

## Raise the beacon

ChatGPT keeps no local history and can't start a local server. The **beacon** (`beacon/`, advanced) is a remote MCP server you host on Cloudflare Workers behind GitHub OAuth, answering only to your GitHub account. `take_fix` and `read_chart` read the chart; `log_watch` appends one `chatgpt` log entry to the logbook repo. Setup takes a Cloudflare account, a GitHub OAuth app and a fine-grained token: [`beacon/README.md`](beacon/README.md). Without it, paste a ChatGPT summary into the project's file as a `chatgpt` entry.

## Spec

The logbook format, the rule, the chart's JSON and every access contract are in [`docs/LOGBOOK-SPEC.md`](docs/LOGBOOK-SPEC.md) (v1.1). The story's glossary and voice are in [`docs/STORY.md`](docs/STORY.md).

## Development

```bash
python -m unittest                # stdlib only (the screen's tests skip)
python -m pip install -e ".[tui]" && python -m unittest   # with the screen's tests
python examples/build.py --check  # the example chart (Linux or macOS)
cd beacon && npm test             # the beacon
```

Design decisions are in [`docs/decisions/`](docs/decisions/); the release plan is [`docs/release/R0-SCOPE.md`](docs/release/R0-SCOPE.md).
