Sync model

Your strategy lives authoritatively on the AlienMonster server. The .alienmonster/ directory on disk is a cache. This page explains how the two stay aligned and which commands to reach for when they don't.

Server is authoritative, disk is cache

Every write — whether you made it via Claude.ai, Claude Code, Cursor, or the web UI — lands on the server first. The server assigns a revision, then your local cache catches up on the next sync. Nothing on disk is ever the source of truth.

This matters because coding agents that read local files can legitimately see old strategy. The sync commands are how you close that gap.

Revisions and content hashes

Each server-side strategy state has two identifiers:

• An HLC (hybrid logical clock) — a monotonic revision number that advances on every server write.
• A content hash — a short SHA over the rendered file set.

Your local cache remembers both. status compares local vs server and tells you whether to sync.

status — what is my cache doing

npx alienmonster status prints the sync trust surface: cache freshness, auth state, lock state, and any local modifications.

$ npx alienmonster status
  👾 Project: my-project
     Auth: ok (you@example.com)
     Local revision: 42
     Server revision: 42
     Status: up-to-date

Supports --json and --porcelain for scripting. See CLI reference.

sync — conditional refresh

npx alienmonster sync checks the server revision against your cache and only rewrites files if the hashes differ. No-op if you're already current.

$ npx alienmonster sync
  Local revision: 42, server revision: 43
  Refreshing .alienmonster/... ✓

--force rewrites regardless of hash (equivalent to export).

watch — stay live

npx alienmonster watch subscribes to server-sent events and auto-runs sync when any primitive write advances the revision. Falls back to polling on disconnect.

Useful while you're actively editing strategy from one surface and coding from another — for example, running a Claude.ai strategy session in a browser tab while your terminal agent works on the same repo.

export — full rewrite

npx alienmonster export unconditionally rewrites .alienmonster/ from the server. Useful when your cache is in a weird state and you want a clean slate.

Troubleshooting stale cache

• status shows "behind N revisions" — expected when the server has advanced. Run sync.
• sync fails with "lock held" — another sync / watch / export is running in the same directory. Wait a few seconds, then retry. Dead-process locks auto-release after 30 seconds.
• status shows auth expired — run logout then login.
• Cache seems corrupted or out of sync even after sync — run export for a full rewrite.
• For more failure modes, see Troubleshooting.