clawdbot/docs/cli/hooks.md

summary, read_when

summary	read_when
CLI reference for `clawdbot hooks` (internal hooks + Gmail Pub/Sub + webhook helpers)	You want to manage internal agent hooks You want to wire Gmail Pub/Sub events into Clawdbot hooks You want to run the gog watch service and renew loop

clawdbot hooks

Webhook helpers and hook-based integrations.

Related:

• Internal Hooks: Internal Agent Hooks
• Webhooks: Webhook
• Gmail Pub/Sub: Gmail Pub/Sub

Internal Hooks

Manage internal agent hooks (event-driven automations for commands like /new, /reset, etc.).

List All Hooks

clawdbot hooks internal list

List all discovered internal hooks from workspace, managed, and bundled directories.

Options:

• --eligible: Show only eligible hooks (requirements met)
• --json: Output as JSON
• -v, --verbose: Show detailed information including missing requirements

Example output:

Internal Hooks (2/2 ready)

Ready:
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new command is issued

Example (verbose):

clawdbot hooks internal list --verbose

Shows missing requirements for ineligible hooks.

Example (JSON):

clawdbot hooks internal list --json

Returns structured JSON for programmatic use.

Get Hook Information

clawdbot hooks internal info <name>

Show detailed information about a specific hook.

Arguments:

• <name>: Hook name (e.g., session-memory)

Options:

• --json: Output as JSON

Example:

clawdbot hooks internal info session-memory

Output:

💾 session-memory ✓ Ready

Save session context to memory when /new command is issued

Details:
  Source: clawdbot-bundled
  Path: /path/to/clawdbot/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/clawdbot/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.clawd.bot/internal-hooks#session-memory
  Events: command:new

Requirements:
  Config: ✓ workspace.dir

Check Hooks Eligibility

clawdbot hooks internal check

Show summary of hook eligibility status (how many are ready vs. not ready).

Options:

• --json: Output as JSON

Example output:

Internal Hooks Status

Total hooks: 2
Ready: 2
Not ready: 0

Enable a Hook

clawdbot hooks internal enable <name>

Enable a specific hook by adding it to your config (~/.clawdbot/config.json).

Arguments:

• <name>: Hook name (e.g., session-memory)

Example:

clawdbot hooks internal enable session-memory

Output:

✓ Enabled hook: 💾 session-memory

What it does:

• Checks if hook exists and is eligible
• Updates hooks.internal.entries.<name>.enabled = true in your config
• Saves config to disk

After enabling:

• Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).

Disable a Hook

clawdbot hooks internal disable <name>

Disable a specific hook by updating your config.

Arguments:

• <name>: Hook name (e.g., command-logger)

Example:

clawdbot hooks internal disable command-logger

Output:

⏸ Disabled hook: 📝 command-logger

After disabling:

• Restart the gateway so hooks reload

Bundled Hooks

session-memory

Saves session context to memory when you issue /new.

Enable:

clawdbot hooks internal enable session-memory

Output: ~/clawd/memory/YYYY-MM-DD-slug.md

See: session-memory documentation

command-logger

Logs all command events to a centralized audit file.

Enable:

clawdbot hooks internal enable command-logger

Output: ~/.clawdbot/logs/commands.log

View logs:

# Recent commands
tail -n 20 ~/.clawdbot/logs/commands.log

# Pretty-print
cat ~/.clawdbot/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .

See: command-logger documentation

Gmail

clawdbot hooks gmail setup --account you@example.com
clawdbot hooks gmail run

See Gmail Pub/Sub documentation for details.