Multi-User Sync

Commands for synchronizing decision graphs across multiple users. Uses an append-only event log model – each user emits events to their own JSONL file, and git handles merging.

How Event-Based Sync Works

The problem: each user has a local .deciduous/deciduous.db (gitignored). How do you share decisions?

The solution: an append-only event log.

Every add, link, or status command emits an event to .deciduous/sync/events/<user>.jsonl
Event files are git-tracked, so git pull brings in teammate events
deciduous events rebuild replays all events to reconstruct the database
Checkpoints capture full state snapshots to avoid replaying the entire history

Each node has two IDs:

id (integer) – local database primary key, different per machine
change_id (UUID) – globally unique, stable across all databases

`deciduous events init`

Initialize event-based sync in the repository. Creates the .deciduous/sync/ directory structure and configures gitignore to track sync files while ignoring the local database.

Terminal

$ deciduous events init
Created .deciduous/sync/events/
Created .deciduous/sync/checkpoints/
Updated .gitignore
Event-based sync initialized

`deciduous events status`

Show sync status – pending events, last checkpoint, and whether a rebuild is needed.

Terminal

$ deciduous events status
Sync status:
Event files: 2 (alice.jsonl, bob.jsonl)
Total events: 47
Last checkpoint: 2025-05-08 10:30:00 (24 nodes)
Pending events: 12 (since checkpoint)
Local DB nodes: 36
Status: rebuild recommended (new teammate events found)

`deciduous events rebuild`

Rebuild the local database from event logs and the latest checkpoint. Loads the checkpoint (if one exists), then replays all events after the checkpoint timestamp.

Flag	Description
`--dry-run`	Show what would be done without modifying the database

Terminal

$ deciduous events rebuild --dry-run
Would load checkpoint: 2025-05-08 10:30:00 (24 nodes, 28 edges)
Would replay 12 events from 2 users:
alice.jsonl: 7 events
bob.jsonl: 5 events
Result: 36 nodes, 41 edges

$ deciduous events rebuild
Loaded checkpoint: 24 nodes, 28 edges
Replayed 12 events
Database rebuilt: 36 nodes, 41 edges

`deciduous events checkpoint`

Create a checkpoint snapshot of the current graph state. Checkpoints allow future rebuilds to skip replaying old events.

Flag	Description
`--clear-events`	Clear event logs after creating the checkpoint

Terminal

$ deciduous events checkpoint
Created checkpoint: 36 nodes, 41 edges
Saved to .deciduous/sync/checkpoints/2025-05-09T143022.json

$ deciduous events checkpoint --clear-events
Created checkpoint: 36 nodes, 41 edges
Cleared 47 events from 2 event files
Checkpoint created and events cleared

`deciduous events emit <node_id>`

Emit an event for a specific node. Primarily for testing or manual sync scenarios.

Terminal

$ deciduous events emit 42
Emitted event for node 42 to .deciduous/sync/events/alice.jsonl

`deciduous migrate`

Add change_id columns to the database for multi-user sync support. Run this once on existing databases before using the events system.

Terminal

$ deciduous migrate
Added change_id column to nodes table
Added change_id column to edges table
Generated UUIDs for 36 existing nodes
Generated UUIDs for 41 existing edges
Migration complete

Typical Team Workflow

Terminal -- team sync workflow

# One-time setup (each team member)
$ deciduous events init
$ deciduous migrate

# Daily workflow: pull teammate events and rebuild
$ git pull
$ deciduous events rebuild

# Work normally -- events auto-emit on add/link/status
$ deciduous add goal "New feature" -c 90
Created node 37 (type: goal) [confidence: 90%]

# Push your events for teammates
$ git add .deciduous/sync/events/alice.jsonl
$ git commit -m "sync: decision graph events"
$ git push

# Periodically compact old events
$ deciduous events checkpoint --clear-events

Keyboard shortcuts

Deciduous