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 hooks

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.

The Claude Stop hook

Claude Code also gets a second hook, wired into hooks.Stop. It fires when Claude finishes responding: if STATE.md hasn't been saved today, it blocks with a one-time reminder to do the end-session update (rewrite the state sections, append today's sessions/ entry) before Claude's reply finishes. It fires at most once per day, and a loop guard means it never nags twice for the same stop. This is the deterministic half of "session ends, state gets saved": the hook triggers it, your agent does the actual write.

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 hook coverage is an open community target; Claude Code and Antigravity are both wired.

See also: Agent Setup · STATE.md · The Keeper.