Claude Code Hook Setup

January 30, 2026 · View on GitHub

Claude Note integrates with Claude Code through hooks. This document explains how to configure them.

Overview

Claude Code fires hooks at key moments:

PostToolUse: After any tool is used
UserPromptSubmit: When user sends a message
Stop: When session ends

Claude Note listens to these events to track sessions and trigger synthesis.

Configuration

Option 1: Global Settings

Edit ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          { "type": "command", "command": "claude-note enqueue", "timeout": 5000 }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "claude-note enqueue", "timeout": 5000 }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "claude-note enqueue", "timeout": 5000 }
        ]
      }
    ]
  }
}

Option 2: Per-Project Settings

Create .claude/settings.json in your project root with the same content.

Hook Details

PostToolUse

Fired after every tool use (file read, edit, bash command, etc.).

Used for:

Keeping session state fresh
Detecting activity patterns

UserPromptSubmit

Fired when the user sends a message.

Used for:

Question detection (adds to open questions tracker)
Session activity tracking

Stop

Fired when the session ends (user exits or session times out).

Used for:

Triggering synthesis
Finalizing session log

Environment Variables

Claude Code provides these variables to hooks:

Variable	Description
`CLAUDE_SESSION_ID`	Unique session identifier
`CLAUDE_WORKING_DIR`	Current working directory

Verifying Setup

Start a Claude Code session
Check the queue:
```
claude-note status
```
You should see pending events

Troubleshooting

Hooks not firing

Verify settings.json location and syntax:
```
cat ~/.claude/settings.json | jq .
```
Check if claude-note is in PATH:
```
which claude-note
```

Test hook manually:

claude-note enqueue test "test-session-id"

Events queued but not processed

Check if worker is running:

# macOS
launchctl list | grep claude-note

# Linux
systemctl --user status claude-note

Check worker logs:

tail -f /path/to/vault/.claude-note/logs/worker-*.log

Synthesis not running

Verify Claude CLI is installed:
```
which claude
```
Check if you're authenticated:
```
claude --version
```
Check synthesis mode in config:
```
cat ~/.config/claude-note/config.toml
```

Minimal Setup

If you only want session logging (no synthesis), you can use just the Stop hook:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "claude-note enqueue", "timeout": 5000 }
        ]
      }
    ]
  }
}

And set mode to "log":

[synthesis]
mode = "log"

Advanced: Filtering by Directory

To only capture sessions in specific directories, add a matcher regex:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "/Users/you/work/.*",
        "hooks": [
          { "type": "command", "command": "claude-note enqueue", "timeout": 5000 }
        ]
      }
    ]
  }
}

The matcher is a regex against the working directory.