Hooks

Hooks are what make cognitiveOS zero-maintenance. They read and update STATE.md around each session, so you never run a "save" command and never maintain anything by hand. There are two layers: slash commands you invoke, and a deterministic session-start hook that fires on its own.

Slash-command hooks (Claude Code)

init generates three slash commands into .claude/commands/:

/start-session   # load STATE.md, print where you left off
/end-session     # roll closed loops + old wins to sessions/, overwrite STATE.md
/dump            # capture a thought to brain-dump/, zero friction

/end-session is the one that keeps STATE.md flat: it overwrites current state, moves closed loops and older wins to sessions/, and prunes Agent Notes. You run /end-session when wrapping up, and the next session starts already knowing where you stopped.

Deterministic session-start hook

So you never even have to type /start-session, init wires a hook into your agent's native config that loads STATE.md the moment a session opens. It can't be skipped and needs zero typing.

Both run the same command:

npx -y cognitiveos start --hook --agent=claude       # or --agent=antigravity

The merge is safe by design. If the config is absent it's created; if it exists, the hook is appended after a backup and the write is idempotent (running init again never duplicates it); if the file is malformed it's left untouched and the snippet is printed for you to paste manually. It never overwrites your existing settings.

If the hook ever misfires, nothing breaks. The agent skill still instructs your agent to read STATE.md first thing.

Verifying the wiring

cognitiveos check          # reports if a hook or command is missing
cognitiveos check --fix    # restores missing hooks (idempotent, never touches your content)

Tip (make it instant and offline): the hook runs npx cognitiveos start --hook, which resolves a local or global install before hitting the network. Install once so session-start never fetches:

npm i -g cognitiveos

Codex and Antigravity hook coverage is an open community target.

See also: Agent Setup · STATE.md.