Waymaker
WaymakerDocs
Developer Documentation
Documentation

Team Collaboration with Waymaker Sync

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