ai-hist sync is the command that builds your history. It reads your local agent files, dedupes, and indexes everything into a SQLite database with full-text search. The first run imports everything; every run after that is incremental — it tracks byte offsets per file and only reads what is new.
ai-hist syncWhat gets imported
A single sync covers every supported source in one pass:
- Claude Code — local JSONL history
- Codex CLI — local JSONL history
- Cursor — per-session JSONL transcripts
- OpenCode — local SQLite database
- Agent Relay — workspace messages via the Relaycast API (when configured)
- Trajectories — compacted per-run JSON files capturing decisions and retrospectives
See Sources for exactly where each reads from on disk and how to configure the API-backed ones.
Incremental by design
Sync is cheap to run often. For the file-based sources (Claude Code, Codex, Cursor), it tracks a byte offset per file in a .sync-state.json state file and only reads the bytes appended since last time. Re-running ai-hist sync after a long coding session reads just the new lines, not the whole file.
Deduplication is enforced at the database level — entries are unique on the combination of source, timestamp, and prompt — so syncing the same data twice never creates duplicates.
Cursor transcript lines carry no per-line timestamp, so sync uses the file's modification time at sync time. Running sync regularly keeps those timestamps close to reality.
Continuous sync with watch
To keep history current without thinking about it, run watch mode. It runs the same sync on a loop:
ai-hist watch # sync every 60s
ai-hist watch --interval 30 # sync every 30sFor a fully managed background loop, schedule ai-hist sync with your OS scheduler — a launchd agent on macOS or a cron entry on Linux. The relayhistory README includes ready-to-copy launchd and cron snippets.
# Linux: sync every minute via cron
echo "* * * * * ~/.local/bin/ai-hist sync >> /tmp/ai-hist-sync.log 2>&1" | crontab -Pushing to the cloud
Everything above is local. When you want your history in Relayloop Cloud — for durable backup and team features — authenticate once, then push:
ai-hist login # authenticate via Agent Relay Cloud
ai-hist push # send new local history to the cloud (incremental, idempotent)There is no ai-hist cloud subcommand — push is the cloud counterpart to local sync. It is cursor-based and idempotent, so you can run it as often as you like. Local sync and cloud push are independent: the local CLI keeps working offline either way.