hook

name	hook
description	Write and read agex tracking events.
type	command

agex hook write <event> [key=value ...] / agex hook read --agent <backend>

write

Called by installed hooks (see agex gamify, Phase 7). Appends a JSON line to .agex/data/<event>.json. Silent. Safe for concurrent invocation (file locking via portalocker).

agex hook write post-tool-use tool=Read

read

Renders tracked events as a markdown table. Prints the source JSON path for deeper inspection.

agex hook read --agent claude-code

Notes

• Event names are free-form; conventional names: post-tool-use, user-prompt, stop, sessions.
• Extra positional key=value pairs are captured into the payload. Empty keys (e.g., =foo) are dropped.
• Timestamp (ts) is attached automatically; a positional ts=<value> overrides it (useful for replays).
• The positional <event> name is authoritative — it always wins over any event=... pair in args.
• Malformed JSON lines in .agex/data/*.json (e.g., from a partial write) are skipped with a warning on hook read, not raised.