Skip to main content

​
clawdia hooks

Manage agent hooks (event-driven automations for commands like /new, /reset, and gateway startup). Related:

​
List All Hooks

clawdia hooks list
List all discovered 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: 
Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new command is issued
  😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance
Example (verbose): 
clawdia hooks list --verbose
Shows missing requirements for ineligible hooks. Example (JSON): 
clawdia hooks list --json
Returns structured JSON for programmatic use.

​
Get Hook Information

clawdia hooks info <name>
Show detailed information about a specific hook. Arguments:
  • <name>: Hook name (e.g., session-memory)
Options:
  • --json: Output as JSON
Example: 
clawdia hooks info session-memory
Output: 
💾 session-memory ✓ Ready

Save session context to memory when /new command is issued

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

Requirements:
  Config: ✓ workspace.dir

​
Check Hooks Eligibility

clawdia hooks check
Show summary of hook eligibility status (how many are ready vs. not ready). Options:
  • --json: Output as JSON
Example output: 
Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

​
Enable a Hook

clawdia hooks enable <name>
Enable a specific hook by adding it to your config (~/.clawdia/config.json). Note: Hooks managed by plugins show plugin:<id> in clawdia hooks list and can’t be enabled/disabled here. Enable/disable the plugin instead. Arguments:
  • <name>: Hook name (e.g., session-memory)
Example: 
clawdia hooks 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

clawdia hooks disable <name>
Disable a specific hook by updating your config. Arguments:
  • <name>: Hook name (e.g., command-logger)
Example: 
clawdia hooks disable command-logger
Output: 
⏸ Disabled hook: 📝 command-logger
After disabling:
  • Restart the gateway so hooks reload

​
Install Hooks

clawdia hooks install <path-or-spec>
Install a hook pack from a local folder/archive or npm. What it does:
  • Copies the hook pack into ~/.clawdia/hooks/<id>
  • Enables the installed hooks in hooks.internal.entries.*
  • Records the install under hooks.internal.installs
Options:
  • -l, --link: Link a local directory instead of copying (adds it to hooks.internal.load.extraDirs)
Supported archives: .zip, .tgz, .tar.gz, .tar Examples: 
# Local directory
clawdia hooks install ./my-hook-pack

# Local archive
clawdia hooks install ./my-hook-pack.zip

# NPM package
clawdia hooks install @clawdia/my-hook-pack

# Link a local directory without copying
clawdia hooks install -l ./my-hook-pack

​
Update Hooks

clawdia hooks update <id>
clawdia hooks update --all
Update installed hook packs (npm installs only). Options:
  • --all: Update all tracked hook packs
  • --dry-run: Show what would change without writing

​
Bundled Hooks

​
session-memory

Saves session context to memory when you issue /new. Enable: 
clawdia hooks 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: 
clawdia hooks enable command-logger
Output: ~/.clawdia/logs/commands.log View logs: 
# Recent commands
tail -n 20 ~/.clawdia/logs/commands.log

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

# Filter by action
grep '"action":"new"' ~/.clawdia/logs/commands.log | jq .
See: command-logger documentation

​
soul-evil

Swaps injected SOUL.md content with SOUL_EVIL.md during a purge window or by random chance. Enable: 
clawdia hooks enable soul-evil
See: SOUL Evil Hook

​
boot-md

Runs BOOT.md when the gateway starts (after channels start). Events: gateway:startup Enable: 
clawdia hooks enable boot-md
See: boot-md documentation