Waymaker sync

Overview

Waymaker Sync enables bidirectional synchronization between your IDE and Commander. Write markdown files in your IDE, and they automatically sync to Commander as documents with tasks extracted.

Key Feature: Trinity Architecture - One markdown file = IDE view + Document view + Task view

Prerequisites

• Authenticated: waymaker auth login
• Project initialized: waymaker init

Usage

waymaker sync <subcommand> [options]

Subcommands

Subcommand	Description
start	Start the sync daemon
stop	Stop the sync daemon
status	Check sync daemon status
all	Sync all files immediately

Start Sync Daemon

Start watching for file changes:

waymaker sync start

Output:

Sync daemon started
Watching: /path/to/project
Taskboard: Sprint 42
Patterns: **/*.md

Press Ctrl+C to stop

The daemon runs in the background, watching for file changes and syncing them to Commander.

Stop Sync Daemon

waymaker sync stop

Output:

Sync daemon stopped

Check Sync Status

waymaker sync status

When running:

Waymaker Sync Status

Status: Running
Project: /path/to/project
Taskboard: Sprint 42

Statistics:
  Files Watched: 24
  Last Sync: 2 minutes ago

When stopped:

Waymaker Sync Status

Status: Not running
Project: /path/to/project

Start with: waymaker sync start

Sync All Files

Immediately sync all matching files:

waymaker sync all

Output:

Syncing all files...

Synced 12 files:
  docs/readme.md
  docs/api/endpoints.md
  specs/feature-x.md
  ...

Done!

Dry Run Mode

Preview what would be synced:

waymaker sync all --dry-run

Output:

Would sync 12 files:
  docs/readme.md (modified)
  docs/api/endpoints.md (new)
  specs/feature-x.md (unchanged)
  ...

Run without --dry-run to sync

Options Reference

start

Option	Description
(none)	Starts both IDE→Commander and Commander→IDE sync

The daemon automatically:

• Watches for local file changes
• Subscribes to Commander taskboard changes in real-time
• Handles conflicts when both sides edit while offline

sync-all

Option	Description
--dry-run	Preview changes without syncing
--force	Re-sync all files even if unchanged
--batch-size N	Files per batch (default: 50)
--concurrency N	Parallel syncs (default: 5)

Note: Use sync-all (with hyphen) not sync all.

How Sync Works

Trinity Architecture

1. IDE View: Write markdown in VS Code, Cursor, or any editor
2. Document View: File syncs to Commander as a document
3. Task View: Checklists become tasks in the connected taskboard

Bidirectional Flow

IDE → Commander:

• Save markdown file
• Daemon detects change
• Content syncs to Commander document
• Tasks extracted from checklists

Commander → IDE:

• Update task in Commander
• Change syncs to local file
• IDE shows updated content

Watch Patterns

By default, sync watches all markdown files (**/*.md). Customize in .commander/config.json:

{
  "workspace_id": "...",
  "project_id": "...",
  "taskboard_id": "...",
  "watch_patterns": [
    "docs/**/*.md",
    "specs/**/*.md"
  ],
  "ignore_patterns": [
    "node_modules/**",
    ".git/**"
  ]
}

Sync Metadata

After syncing, files may include frontmatter with sync IDs:

---
sync_id: doc_abc123
last_synced: 2026-02-03T10:30:00Z
---

# Feature X

## Requirements

- [ ] User authentication
- [ ] Payment integration

Typical Workflow

1. Initialize and Start Sync

cd /path/to/project
waymaker auth login
waymaker init
waymaker sync start

2. Work in Your IDE

Edit markdown files normally. Changes sync automatically.

3. Check Task Status

View your taskboard in the terminal:

waymaker kanban

Or check in Commander: commander.waymakerone.com

4. End of Session

Stop the daemon when done:

waymaker sync stop

AI Agent Workflow

AI assistants can use sync for task management:

# Check sync status
waymaker sync status

# Sync all files after making changes
waymaker sync all

# Preview sync (for validation)
waymaker sync all --dry-run

Troubleshooting

Files Not Syncing

Symptoms: Changes aren't appearing in Commander.

Solutions:

1. Verify daemon is running: waymaker sync status
2. Check file matches watch patterns
3. Manual sync: waymaker sync all
4. Restart daemon: waymaker sync stop && waymaker sync start

"Not initialized"

Symptoms: waymaker sync start fails with "not initialized" error.

Solutions:

waymaker init

"Not authenticated"

Symptoms: Sync commands fail with authentication errors.

Solutions:

waymaker auth login

Sync Conflicts

Symptoms: .conflict.md file appears next to your original file.

What happened: Both sides edited the same task while the daemon was offline.

Resolution:

1. Open both files (main file has Commander version, .conflict.md has your version)
2. Merge changes into the main file
3. Delete the .conflict.md file
4. Save — merged version syncs to Commander

See Troubleshooting for details.

Reset Sync State

To start fresh:

# Remove sync metadata from files
# (manual: remove frontmatter sync_id from files)

# Force re-sync
waymaker sync all --force

Performance Notes

• Sync debounces rapid changes (waits 1 second after last change)
• Large files (>1MB) are skipped by default
• Binary files are ignored

Related Commands

• auth - Authentication
• init - Project initialization
• kanban - Terminal taskboard view
• serve - MCP server for AI assistants