Waypoint

Waypoint is a docs-first repository operating system for Codex.

It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:

• AGENTS.md for startup instructions
• .waypoint/WORKSPACE.md for live state, with timestamped multi-topic entries
• .waypoint/docs/ for durable project memory, with summary, last_updated, and read_when frontmatter on routable docs
• .waypoint/DOCS_INDEX.md for docs routing
• repo-local skills for planning and audits

Install

npm install -g waypoint-codex

Or use it without installing globally:

npx waypoint-codex@latest --help

Start using it

Inside your Codex project:

waypoint init --with-automations --with-roles
waypoint doctor

That scaffolds:

repo/
├── AGENTS.md
├── .agents/skills/
└── .waypoint/
    ├── WORKSPACE.md
    ├── DOCS_INDEX.md
    ├── docs/
    ├── context/
    └── ...

Main commands

• waypoint init — scaffold or refresh the repo
• waypoint doctor — check for drift and missing pieces
• waypoint sync — rebuild .waypoint/DOCS_INDEX.md and sync optional automations/rules
• waypoint upgrade — update the global Waypoint CLI and refresh the current repo with its existing config
• waypoint import-legacy — import from an older repo layout

Shipped skills

• planning
• error-audit
• observability-audit
• ux-states-audit

Optional reviewer roles

If you initialize with --with-roles, Waypoint scaffolds:

• code-health-reviewer
• code-reviewer
• docs-researcher
• plan-reviewer

The intended workflow is post-commit: after your own commit lands, run code-reviewer and code-health-reviewer in parallel in the background, then fix real findings before you call the work finished.

Update

waypoint upgrade

If you only want to update the CLI without refreshing the repo:

waypoint upgrade --skip-repo-refresh

Learn more

• Overview
• Architecture
• Upgrading
• Importing Existing Repositories