Hooks

Hooks are shell scripts that Command Code runs automatically before and after each tool call. They give you deterministic control over Command Code's behavior. Use hooks to enforce project rules, audit tool use, and integrate Command Code with workflows you already have.

What are hooks?

Hooks fire before a shell command runs, before a file read, and after a write. Each hook receives the tool's inputs as JSON on stdin and returns one of four actions: allow, deny, halt the session, or inject extra context for the next turn.

What you can do with hooks?

With hooks configured, you can:

Block dangerous bash commands before they execute, so rm -rf / never makes it past a policy guard.
Inject project-specific context when the agent reads sensitive files, nudging the model to redact secrets.
Audit every write to the disk by forwarding file paths to a local log.
Halt the session if a tool's output leaks sensitive information.

Supported events

Event	Fires	Can block the tool?
`PreToolUse`	Before a tool runs	Yes
`PostToolUse`	After the tool returns	No

More hook events are coming soon.

Supported tools

Tool	Matcher literal	What it covers
Shell	`shell`	Shell command execution
Read	`read`	File reads
Write	`write`	File creation or full overwrite
Edit	`edit`	In-place edits to an existing file

For matcher syntax (regex, case-insensitivity, matching multiple tools), see Hooks Reference: Settings schema.

How hooks work

A hook is any executable that reads a JSON payload on stdin and writes a JSON object on stdout. Write one in bash, Node.js, Python, or anything that can parse JSON.

Event fires: Command Code is about to run (or has just run) a tool.
Hook triggered: Command Code spawns your executable and writes the tool's details as JSON on its stdin.
Hook responds: Your executable writes a JSON response to stdout to allow, deny, inject context, or halt the session.

For the stdin and stdout schema, exit codes, environment variables, and execution semantics, see the Hooks Reference.

Quickstart

This quickstart wires up your first hook in Command Code.

1. Create the settings file

Create .commandcode/settings.json at the root of your project and paste in the snippet below. The PreToolUse hook triggers before every shell command and prints a message.

.commandcode/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [
          { "type": "command", "command": "echo '{\"systemMessage\":\"hook fired\"}'" }
        ]
      }
    ]
  }
}

The command field is what Command Code runs when the hook fires. Here it prints a JSON object with a systemMessage field, and Command Code surfaces that message when running shell commands.

2. Try it out

Hooks initialize on startup. Restart Command Code with cmd, then run a prompt such as Use the shell tool to list the files in the current directory. The message PreToolUse: hook fired should appear before the shell command executes.

Next steps

The quickstart hook emits a static message. Real hooks parse the JSON payload on stdin and return results, halt sessions, or inject context for the next turn. Learn more:

Configuration: scopes, precedence, and hook entries
Hooks Reference: full schema for every field
Best Practices: writing safe hooks and debugging
Examples: block bash, warn on sensitive reads, audit writes