Every time an agent finishes a session, you want to save what it learned. Every time an initiative changes state, you want your team notified. Hooks make these automations happen without you lifting a finger.

Open the Hooks tab in Tools (Mod+7).

Overview

Hooks are lifecycle automation triggers. They watch for specific events in kill9 and fire automated responses. A hook is a rule: when X happens, do Y. They run in the background — you set them up once and they keep working.

kill9 includes built-in hooks for essential behavior. You can also create custom hooks for your own automation needs.

What you can do

With hooks, you can:

Automatically extract memories from conversations
Record chronicle entries when significant events occur
Track costs and usage across sessions
Send notifications when work completes or changes state
Run custom commands in response to lifecycle events
Enforce policies automatically (like requiring tests before merging)

How it works

What hooks are

A hook has two parts: a trigger (the event that activates it) and an action (what happens when it fires). When the trigger event occurs, kill9 runs the action automatically.

You configure hooks at two levels:

Organization level — hooks that apply to all projects. Set these once and they work everywhere.
Local level — hooks specific to a single project. These override org-level hooks when there's a conflict.

When hooks fire

Hooks can fire at many points in the kill9 lifecycle:

Auth events — when you log in, log out, or your session expires
Session start and end — when an agent session begins or completes
Pre-turn and post-turn — before and after each agent response in a conversation
Tool before, after, and error — when an agent is about to use a tool, after it finishes, or when it fails
Workflow state changes — when an initiative, epic, or story moves to a new state
Entity creation and deletion — when new work items are created or removed

Each trigger point gives the hook access to relevant context — the agent name, the session ID, the tool being used, the state being transitioned, and more.

Built-in hooks

kill9 ships with several built-in hooks that handle essential behavior:

Memory extraction — after each agent turn, scans the conversation for facts worth saving and writes them to the memory store
Concept extraction — identifies key concepts from conversations and indexes them for search
Chronicle recording — synthesizes session activity into chronicle entries at meaningful moments (state changes, session completion, document approval)
Cost tracking — records token usage and costs for each session and model
Usage statistics — aggregates usage data for the stats dashboard

You don't need to configure these — they're active by default.

Custom hooks

Create custom hooks for your own automation. Open Tools (Mod+7), go to the Hooks tab, and click Create.

Set the trigger — choose which event activates the hook. Then set the action — choose what happens. Actions include:

Sending notifications (Slack, email, webhook)
Updating entities (changing state, adding labels)
Running commands (shell scripts, build steps)
Calling external services (APIs, integrations)

Examples of custom hooks:

When a story moves to "done," post a message to your team's Slack channel
When an initiative is created, assign it a default priority
When ktest finishes running tests, log the results to a dashboard
When a document is approved, automatically move the linked initiative to the next state

Save the hook and it activates immediately. No restart needed.

Trust and review

Hooks defined in files — your project's .kill9/hooks.json (or .toml) and your machine-wide ~/.config/kill9/hooks.json — run real shell commands. Since a project you clone could ship its own hooks file, kill9 will not run a file-based hook until you've reviewed and approved it. Until then it's listed as pending and simply doesn't fire. Editing a hook's command re-flags it for review.

Review from the terminal:

bash

cortex hooks list          # see every file hook and whether it's trusted
cortex hooks trust <id>    # approve one (or "all")
cortex hooks untrust <id>  # revoke approval

Cloud organization command hooks are read-only and are not executable. They appear in Settings so you can see what your org has configured, but kill9 never runs a remotely controlled command. Executable hooks come only from the local filesystem: your project's .kill9/hooks.json (or ~/.config/kill9/hooks.json), after you approve it with cortex hooks trust .

Codex-compatible hooks

kill9's command hooks follow the same contract as OpenAI Codex hooks, so a Codex hook script generally works unmodified. A hook reads a JSON event on stdin (with both kill9 and Codex field names, e.g. tool_input / tool_name) and can steer the agent by printing JSON on stdout: deny an action, auto-approve a permission prompt, rewrite a tool's arguments before it runs, or inject extra context. Config can be written as JSON or TOML.

Managing hooks

All hooks appear in the Hooks tab in Tools. From there you can:

Toggle hooks on or off without deleting them
Edit the trigger or action of any hook
Delete hooks you no longer need
View logs showing when each hook fired and what it did

Tips

Start with built-in hooks. Don't create custom hooks until you've used kill9 enough to know what you want to automate.
Custom hooks for notifications are the most useful early on — knowing when work completes without checking the app saves time.
Be careful with pre-turn hooks that modify agent context. They run on every message and can slow things down if they're heavy.
Use local-level hooks for project-specific automation (like running a specific test suite) and org-level hooks for general policies (like cost limits).
Check hook logs if something unexpected happens. A misconfigured hook can cause surprising behavior.

Extensions — browsing and managing all extension types
Memories — where auto-extracted memories end up
Chronicles — where chronicle entries get recorded
Core concepts — how hooks fit into the system

Hooks