Hooks System

The ChatCLI Hooks System lets you execute automatic actions in response to application lifecycle events. With hooks, you can auto-format code after edits, send notifications, block dangerous commands, log audit trails, and much more.

Hooks are additive: global and workspace configurations are merged. Workspace hooks complement global ones — they never replace them.

Configuration

Hooks are defined in JSON files at two levels:

Level	File	Scope
Global	`~/.chatcli/hooks.json`	All projects and sessions
Workspace	`.chatcli/hooks.json`	Current project only

Workspace hooks are additive — they combine with global hooks. If the same event has hooks at both levels, all are executed (global first, then workspace).

File Structure

{
  "hooks": [
    {
      "event": "PostToolUse",
      "type": "command",
      "command": "gofmt -w {{.FilePath}}",
      "toolPattern": "write|patch",
      "description": "Auto-format Go files after edits"
    },
    {
      "event": "SessionEnd",
      "type": "http",
      "url": "https://hooks.example.com/chatcli",
      "description": "Notify team of session end"
    }
  ]
}

Available Events

ChatCLI emits 9 lifecycle events that hooks can bind to:

Event	When it fires	Blocking
`SessionStart`	When a new ChatCLI session starts	No
`SessionEnd`	When the session ends (exit/quit)	No
`PromptSubmit`	When the user submits a prompt	No
`PreToolUse`	Before executing a tool	Yes
`PostToolUse`	After a tool executes successfully	No
`ToolError`	When a tool fails	No
`AgentStart`	When entering agent/coder mode	No
`AgentEnd`	When exiting agent/coder mode	No
`CompactDone`	After a history compaction	No

The PreToolUse event is blocking: if the hook returns exit code 2, the tool execution is blocked. This allows you to create guardrails that prevent dangerous operations.

Hook Types

Command (Shell)
HTTP (Webhook)

Executes a shell command on the operating system. The command has access to environment variables with event context.

{
  "event": "PostToolUse",
  "type": "command",
  "command": "gofmt -w {{.FilePath}}",
  "toolPattern": "write|patch",
  "description": "Auto-format Go files after write/patch"
}

Exit codes:

0 — Success (execution continues normally)
1 — Error (logged, but does not block)
2 — Blocks the operation (only for PreToolUse)

The command is executed via sh -c on Linux/macOS and cmd /c on Windows.

Sends an HTTP POST request to the specified URL. The request body contains a JSON payload with the event data.

{
  "event": "SessionEnd",
  "type": "http",
  "url": "https://hooks.example.com/chatcli/events",
  "description": "Send session end notification"
}

JSON payload sent:

{
  "event": "SessionEnd",
  "timestamp": "2026-03-29T14:30:00Z",
  "session_id": "abc123",
  "tool": "",
  "data": {
    "duration": "45m12s",
    "messages": 32
  }
}

Webhooks are fired asynchronously and do not block ChatCLI execution.

ToolPattern — Tool Filtering

The toolPattern field lets you filter which tools trigger the hook. It accepts glob patterns:

Pattern	Matched tools
`write`	Only `write`
`write\|patch`	`write` or `patch`
`exec*`	`exec`, `exec_background`, etc.
`mcp_*`	All MCP tools
`*`	All tools (default if omitted)

{
  "event": "PreToolUse",
  "type": "command",
  "command": "echo 'BLOCKED: exec not allowed' && exit 2",
  "toolPattern": "exec*",
  "description": "Block all exec commands"
}

Environment Variables

Command hooks receive environment variables with event context:

Variable	Description	Example
`CHATCLI_HOOK_EVENT`	Name of the event that triggered the hook	`PostToolUse`
`CHATCLI_HOOK_TOOL`	Tool name (if applicable)	`write`
`CHATCLI_HOOK_SESSION`	Current session ID	`session_abc123`
`CHATCLI_HOOK_FILE`	Affected file path (if applicable)	`/project/main.go`
`CHATCLI_HOOK_CWD`	Current working directory	`/Users/dev/project`
`CHATCLI_HOOK_MODE`	Current mode (chat, agent, coder)	`agent`

Complete Examples

Auto-Format
Notifications
Block Commands
Audit

Auto-format Go files after any edit:

{
  "hooks": [
    {
      "event": "PostToolUse",
      "type": "command",
      "command": "if [[ \"$CHATCLI_HOOK_FILE\" == *.go ]]; then gofmt -w \"$CHATCLI_HOOK_FILE\"; fi",
      "toolPattern": "write|patch",
      "description": "Auto-format Go files"
    }
  ]
}

Send a Slack notification at the end of each session:

{
  "hooks": [
    {
      "event": "SessionEnd",
      "type": "http",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "description": "Notify Slack on session end"
    }
  ]
}

Block rm -rf and DROP TABLE in production:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "type": "command",
      "command": "if echo \"$CHATCLI_HOOK_ARGS\" | grep -qE 'rm -rf|DROP TABLE'; then echo 'BLOCKED: dangerous command' >&2; exit 2; fi",
      "toolPattern": "exec*",
      "description": "Block dangerous shell commands"
    }
  ]
}

Log all tool executions:

{
  "hooks": [
    {
      "event": "PostToolUse",
      "type": "command",
      "command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) $CHATCLI_HOOK_EVENT $CHATCLI_HOOK_TOOL $CHATCLI_HOOK_FILE\" >> ~/.chatcli/audit.log",
      "description": "Audit log for all tool executions"
    }
  ]
}

Use Cases

Auto-Format

Run formatters (gofmt, prettier, black) automatically after file edits.

Notifications

Send alerts to Slack, Discord, or email at the end of sessions or on errors.

Guardrails

Block dangerous commands (rm -rf, DROP TABLE, force push) with PreToolUse.

Audit

Log all agent actions to files for compliance.

Auto-Test

Run tests automatically after every code edit.

Linting

Run linters (golangci-lint, eslint) after every write/patch.

Next Steps

Coder Security

Security policies and approval for coder operations.

Security

Understand the ChatCLI security model.

Compact UI

Minimalist display mode for coder mode.

Coder Mode

The full engineering cycle with integrated hooks.

Home

Getting Started

Core Concepts

Features

Support

Configuration

File Structure

Available Events

Hook Types

ToolPattern — Tool Filtering

Environment Variables

Complete Examples

Use Cases

Auto-Format

Notifications

Guardrails

Audit

Auto-Test

Linting

Next Steps

Coder Security

Security

Compact UI

Coder Mode

Home

Getting Started

Core Concepts

Features

Support

​Configuration

​File Structure

​Available Events

​Hook Types

​ToolPattern — Tool Filtering

​Environment Variables

​Complete Examples

​Use Cases

Auto-Format

Notifications

Guardrails

Audit

Auto-Test

Linting

​Next Steps

Coder Security

Security

Compact UI

Coder Mode

Configuration

File Structure

Available Events

Hook Types

ToolPattern — Tool Filtering

Environment Variables

Complete Examples

Use Cases

Next Steps