Waymaker
Sync

Getting Started with Waymaker Sync

Waymaker Sync enables **Trinity Architecture** — one markdown file creates three synchronized views:

IDESetup
Last updated: September 25, 2026•5 minutes read

Getting Started with Waymaker Sync

Difficulty: Beginner

Quick Start

  1. Install the CLI — CLI installation in the developer docs
  2. Set your API key — create one in Admin (API Keys) and follow Authentication
  3. Initialise your project — waymaker init
  4. Configure sync — the CLI's sync configure command, pointed at your workspace, project and taskboard (Setting up sync)

That's it! You're ready to sync. Without Step 4, sync start and sync watch stop with No sync session.

Overview

Waymaker Sync enables Trinity Architecture — one markdown file creates three synchronized views:

  • IDE View: Edit in VS Code, Cursor, or any editor
  • Document View: Readable in Commander Explorer
  • Task View: Cards on Commander taskboard

Learn more about Trinity Architecture

What You'll Get

  • AI that remembers yesterday's decisions
  • Persistent context across Claude/Cursor/Windsurf sessions
  • Automatic sync between IDE and Commander
  • 2-4 hours saved daily re-explaining context to AI

Prerequisites

  • Waymaker Account: Free account at waymakerone.com
  • Node.js: Version 18 or higher
  • IDE: VS Code, Cursor, or Windsurf

Step-by-Step Setup

Step 1: Install the CLI

Follow CLI installation in the developer docs. It covers installing with npm and checking the version.

Step 2: Set your API key

The CLI authenticates with an API key, not a browser sign-in. Create your own in Admin — see API Keys — and set it as WAYMAKER_API_KEY as described in Authentication.

Step 3: Initialize Your Project

In your project directory, run the CLI's init command — see waymaker init in the developer docs. It creates an empty .commander/config.json. It does not set up sync — that is the next step.

Step 4: Configure Sync

Create a sync session that points at the workspace, project and taskboard you want to sync with: the CLI's sync configure command, with its --workspace, --project and --taskboard options — see Setting up sync in the developer docs. It writes .commander/sync-session.json. Skip this and Step 6 stops with No sync session.

Step 5: Create Your First Synced File

Create a task file with sync frontmatter:

mkdir -p docs/02-working/tasks/backlog

Create docs/02-working/tasks/backlog/my-first-task.md:

---
sync:
  type: task
  status: active
  priority: medium
---

# My First Synced Task

This is my first task that will sync to Commander.

## Checklist

- [ ] Learn about Waymaker Sync
- [ ] Create more synced documents
- [ ] Explore the Commander taskboard

Step 6: Start Syncing

Run the CLI's sync watch — the daemon that watches your files and sends each change to Commander. (sync start is different: it flushes any queued changes once and says how many went through.) Both are in the command reference in the developer docs.

Step 7: View in Commander

Open commander.waymakerone.com to see your synced task on the taskboard.

Verify Everything Works

Check Sync Status

Ask the CLI for the sync status (see the command reference). While the watcher is running it prints Sync Watcher (live): files watched, pending changes, last sync and, if there are any, recent errors. When no watcher is running it prints the sync session (project path, workspace, when it was configured) and the pending queue instead.

Use MCP Tools (for AI Assistants)

If using Claude Code, Cursor, or another MCP-compatible assistant:

waymaker_sync_status

Folder Conventions

Organize your docs for clean sync:

docs/
├── 01-planning/
│   └── product-requirements/   # type: epic
├── 02-working/
│   ├── tasks/
│   │   ├── backlog/            # type: task, status: backlog
│   │   ├── active/             # type: task, status: active
│   │   └── completed/          # type: task, status: done
│   └── sessions/               # type: session
└── 03-knowledge/
    └── patterns/               # type: document

Tip: Moving a file to completed/ automatically marks the task as done in Commander.

Common Commands

Every sync command — start, stop, status, watch, configure — is listed in the CLI command reference in the developer docs, generated from the CLI itself.

Troubleshooting

"Not authenticated"

WAYMAKER_API_KEY is missing or invalid. Set a current key — see Authentication.

"No sync session"

Step 4 was skipped in this directory. Run the CLI's sync configure here — see Setting up sync. Re-running init does not fix this; it only creates the config file.

Files Not Syncing

  1. Check frontmatter — Must have sync: block
  2. Check file location — Must match watch_patterns in config
  3. Check daemon — Ask the CLI for the sync status

For more issues, see Troubleshooting Guide.

Next Steps

  1. Configure your AI assistant — Teach Claude/Cursor to write correct frontmatter
  2. Learn frontmatter options — Types, statuses, priorities, and more
  3. Understand Trinity Architecture — How one file becomes three views

Need help? Contact support@waymakerone.com