@theethosteam/zjai-checkpoint

The ZJ AI project heartbeat. A tiny, dependency-free CLI that a Claude Code hook in a project repo runs to log a checkpoint to the central ZJ AI activity feed — so the master brain (BIGDADDYZJ/zj.ai) stays aware of work done in any project, without the brain (Memory Bank) being installed there.

Two layers, kept distinct:

• 💓 This = sync/awareness — a heartbeat into the shared feed (ingest-event).
• 🧠 Knowledge — lives in the brain's projects/<name>.md card, never in the repo.

How it works

On invocation it reads (best-effort) the repo's .zjai.md identity + git state + the hook's stdin, composes one event, and POSTs it to {SUPABASE_URL}/functions/v1/ingest-event with the x-ingest-secret header. It never blocks a session (always exits 0) and skips silently if INGEST_SECRET is unset.

Event shape: { title, category:"checkpoint", node:<slug>, source:<slug>, ref, is_public }. Title example: checkpoint · Zeus · The Gutter Doctor Plus · main@1a2b3c · 3 behind — fix nav (SessionEnd/clear).

The title stamps the machine (ZJAI_MACHINE, else hostname) + the clone's branch@sha + commits behind its last-fetched origin/main — so the brain sees which machine did the work and how fresh its clone was (it derives true staleness by comparing the reported sha to main's real HEAD). No network call in the hook.

Install in a project (per-repo)

1. .claude/settings.json (committed to the project repo):

{
  "hooks": {
    "SessionEnd": [
      { "matcher": "clear",  "hooks": [{ "type": "command", "command": "npx -y @theethosteam/zjai-checkpoint SessionEnd clear",  "timeout": 30 }] },
      { "matcher": "logout", "hooks": [{ "type": "command", "command": "npx -y @theethosteam/zjai-checkpoint SessionEnd logout", "timeout": 30 }] },
      { "matcher": "other",  "hooks": [{ "type": "command", "command": "npx -y @theethosteam/zjai-checkpoint SessionEnd other",  "timeout": 30 }] }
    ],
    "PreCompact": [
      { "matcher": "auto",   "hooks": [{ "type": "command", "command": "npx -y @theethosteam/zjai-checkpoint PreCompact auto",   "timeout": 30 }] }
    ]
  }
}

2. Set INGEST_SECRET in that project's Claude Code environment settings (one shared secret across projects). Also set ZJAI_MACHINE in each machine's env to its roster name (Zeus / Prikash / cloud) so heartbeats are attributed correctly (defaults to hostname if unset).
3. Optional: add - **Feed:** public to the repo's .zjai.md to log public events (default is private).

Config

| Env | Default | Purpose | |-----|---------|---------| | INGEST_SECRET | — (required) | auth to ingest-event; absent ⇒ no-op | | ZJAI_MACHINE | hostname | friendly machine name (Zeus / Prikash / cloud) stamped on each heartbeat | | SUPABASE_URL | https://naqtcrwktccslcrormwo.supabase.co | zj.ai project URL |

Dry run (no POST)

echo '{"cwd":"'"$PWD"'"}' | npx -y @theethosteam/zjai-checkpoint SessionEnd clear --print

Prints the exact JSON it would send.

Source of truth + the hub-and-connector model: BIGDADDYZJ/zj.ai → docs/hub-and-connector-README.md.