Waymaker
WaymakerDocs
Developer Documentation
Documentation

Team Collaboration with Waymaker Sync

Deprecated. waymaker sync will be removed in the next release of the Waymaker CLI. Every waymaker sync command now prints this notice on stderr and still runs, so existing scripts keep working until then. Move to the taskboard GitHub repository connection for a roadmap built from your repo, or to the Waymaker MCP server to let an AI assistant read and write Commander directly.

The golden rule

Git is the source of truth. Waymaker Sync is a layer on top of it. Your Git workflow doesn't change — Git still handles merges, conflicts, history, and branches. Sync handles pushing markdown files to Commander (as documents) and pulling task state back.

What everyone shares

Shared resourceWhere it comes from
Git repositoryYour normal remote
Commander workspaceAn org-level container
ProjectA specific project inside that workspace
Taskboard (optional)Where extracted tasks land

Individual setup

Each team member runs this themselves — don't share a sync session between people.

git clone https://github.com/your-org/your-project.git
cd your-project

npm install -g @waymakeros/cli
export WAYMAKER_API_KEY=wm_sk_your_own_key   # each person's own API key

waymaker init
waymaker sync configure --workspace <workspaceId> --project <projectId> --taskboard <taskboardId>

Use the same --workspace/--project/--taskboard IDs across the team (put them in your project's README) — but each person authenticates with their own API key and gets their own sync session.

.commander/sync-session.json holds a per-person session ID — gitignore it, don't commit it:

# .gitignore
.commander/

Start syncing

waymaker sync watch

Watches for local file changes and syncs bidirectionally with Commander while it's running. For a one-off push instead of a continuous watcher:

waymaker sync file docs/02-working/tasks/auth-feature.md

What happens when someone edits a file

  1. Alice edits docs/02-working/tasks/auth-feature.md locally, with waymaker sync watch running
  2. Sync pushes the change to Commander
  3. Bob (also running sync watch) and Carol (in the Commander UI) see the update
  4. Alice commits and pushes to Git as normal — Git history is unaffected by sync

Checking status

waymaker sync status

Shows session info, queue depth, and which documents are synced. Useful when someone says "my changes aren't showing up" — check the queue isn't stuck before assuming something's broken.

Next steps