Skip to main content

​
fluffbuzz hooks

Manage agent hooks (event-driven automations for commands like /new, /reset, and gateway startup). Running fluffbuzz hooks with no subcommand is equivalent to fluffbuzz hooks list. Related:

​
List All Hooks

fluffbuzz hooks list
List all discovered hooks from workspace, managed, extra, and bundled directories. Gateway startup does not load internal hook handlers until at least one internal hook is configured. 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
  📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued
Example (verbose): 
fluffbuzz hooks list --verbose
Shows missing requirements for ineligible hooks. Example (JSON): 
fluffbuzz hooks list --json
Returns structured JSON for programmatic use.

​
Get Hook Information

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

Save session context to memory when /new or /reset command is issued

Details:
  Source: fluffbuzz-bundled
  Path: /path/to/fluffbuzz/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/fluffbuzz/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.fluffbuzz.com/automation/hooks#session-memory
  Events: command:new, command:reset

Requirements:
  Config: ✓ workspace.dir

​
Check Hooks Eligibility

fluffbuzz 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

fluffbuzz hooks enable <name>
Enable a specific hook by adding it to your config (~/.fluffbuzz/fluffbuzz.json by default). Note: Workspace hooks are disabled by default until enabled here or in config. Hooks managed by plugins show plugin:<id> in fluffbuzz hooks list and can’t be enabled/disabled here. Enable/disable the plugin instead. Arguments:
  • <name>: Hook name (e.g., session-memory)
Example: 
fluffbuzz 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
If the hook came from <workspace>/hooks/, this opt-in step is required before the Gateway will load it. After enabling:
  • Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).

​
Disable a Hook

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

​
Notes

  • fluffbuzz hooks list --json, info --json, and check --json write structured JSON directly to stdout.
  • Plugin-managed hooks cannot be enabled or disabled here; enable or disable the owning plugin instead.

​
Install Hook Packs

fluffbuzz plugins install <package>        # ClawHub first, then npm
fluffbuzz plugins install <package> --pin  # pin version
fluffbuzz plugins install <path>           # local path
Install hook packs through the unified plugins installer. fluffbuzz hooks install still works as a compatibility alias, but it prints a deprecation warning and forwards to fluffbuzz plugins install. Npm specs are registry-only (package name + optional exact version or dist-tag). Git/URL/file specs and semver ranges are rejected. Dependency installs run with --ignore-scripts for safety. Bare specs and @latest stay on the stable track. If npm resolves either of those to a prerelease, FluffBuzz stops and asks you to opt in explicitly with a prerelease tag such as @beta/@rc or an exact prerelease version. What it does:
  • Copies the hook pack into ~/.fluffbuzz/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)
  • --pin: Record npm installs as exact resolved name@version in hooks.internal.installs
Supported archives: .zip, .tgz, .tar.gz, .tar Examples: 
# Local directory
fluffbuzz plugins install ./my-hook-pack

# Local archive
fluffbuzz plugins install ./my-hook-pack.zip

# NPM package
fluffbuzz plugins install @fluffbuzz/my-hook-pack

# Link a local directory without copying
fluffbuzz plugins install -l ./my-hook-pack
Linked hook packs are treated as managed hooks from an operator-configured directory, not as workspace hooks.

​
Update Hook Packs

fluffbuzz plugins update <id>
fluffbuzz plugins update --all
Update tracked npm-based hook packs through the unified plugins updater. fluffbuzz hooks update still works as a compatibility alias, but it prints a deprecation warning and forwards to fluffbuzz plugins update. Options:
  • --all: Update all tracked hook packs
  • --dry-run: Show what would change without writing
When a stored integrity hash exists and the fetched artifact hash changes, FluffBuzz prints a warning and asks for confirmation before proceeding. Use global --yes to bypass prompts in CI/non-interactive runs.

​
Bundled Hooks

​
session-memory

Saves session context to memory when you issue /new or /reset. Enable: 
fluffbuzz hooks enable session-memory
Output: ~/.fluffbuzz/workspace/memory/YYYY-MM-DD-slug.md See: session-memory documentation

​
bootstrap-extra-files

Injects additional bootstrap files (for example monorepo-local AGENTS.md / TOOLS.md) during agent:bootstrap. Enable: 
fluffbuzz hooks enable bootstrap-extra-files
See: bootstrap-extra-files documentation

​
command-logger

Logs all command events to a centralized audit file. Enable: 
fluffbuzz hooks enable command-logger
Output: ~/.fluffbuzz/logs/commands.log View logs: 
# Recent commands
tail -n 20 ~/.fluffbuzz/logs/commands.log

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

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

​
boot-md

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