Extending

Project instructions, hooks, and themes

Standing rules every turn reads, commands that fire on lifecycle events, and how the terminal looks.

AGENTS.md

Put your project's standing rules in AGENTS.md at the repository root. Every turn reads it.

Markdown
# Conventions

- Errors wrap with context; never return a bare `err`.
- Tests go next to the code, not in a tests/ directory.
- Migrations are additive. Never edit one that has shipped.

CLAUDE.md is honoured too, so a repository already set up for Claude Code works as-is.

/init analyses the repository and writes a first draft for you. It's a starting point — the rules that matter are the ones you'd tell a new hire, and it can't know those.

Instructions versus memory

AGENTS.md is checked into the repository: everyone gets it, it's reviewed like code, it applies from the first turn on a fresh clone. Memory that you save as you work can follow you across sessions and connected clients, according to its scope.

Use the file for rules that are true of the codebase. Let memory handle everything else.

Sticky instructions for one session

Code
/instruct we're only touching the API crate today
/instruct              what's pinned
/instruct clear

For a constraint that applies to this session and shouldn't outlive it.

Hooks

Shell commands that fire on lifecycle events:

JSON
{
  "hooks": {
    "turn_end": ["afplay /System/Library/Sounds/Glass.aiff"]
  }
}

A sound when a long turn finishes is the common one. So is a desktop notification, or appending to a log.

Themes

Code
/theme            what's available
/theme <name>     switch

Custom themes are JSON. If you've spent time on a terminal colour scheme, the agent can match it.

If it doesn't work

It's ignoring AGENTS.md. Check it's at the repository root, and that the rules are specific. "Write good code" isn't actionable; "never return a bare err" is.

A hook doesn't fire. Hooks run through your shell — an alias that only exists in an interactive profile won't resolve. Use an absolute path.

Rules conflict. A sticky /instruct beats AGENTS.md for the session. Memory that contradicts the file is worth resolving in the file.

Next