CLI reference for `zirkabot hooks` (agent hooks)

Read when…
  • You want to manage agent hooks
  • You want to install or update hooks

zirkabot hooks

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

Related:

List All Hooks

zirkabot 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):

zirkabot hooks list --verbose

Shows missing requirements for ineligible hooks.

Example (JSON):

zirkabot hooks list --json

Returns structured JSON for programmatic use.

Get Hook Information

zirkabot hooks info <name>

Show detailed information about a specific hook.

Arguments:

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

Options:

  • --json: Output as JSON

Example:

zirkabot hooks info session-memory

Output:

💾 session-memory ✓ Ready

Save session context to memory when /new command is issued

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

Requirements:
  Config: ✓ workspace.dir

Check Hooks Eligibility

zirkabot 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

zirkabot hooks enable <name>

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

Note: Hooks managed by plugins show plugin:<id> in zirkabot hooks list and can’t be enabled/disabled here. Enable/disable the plugin instead.

Arguments:

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

Example:

zirkabot 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

zirkabot hooks disable <name>

Disable a specific hook by updating your config.

Arguments:

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

Example:

zirkabot hooks disable command-logger

Output:

⏸ Disabled hook: 📝 command-logger

After disabling:

  • Restart the gateway so hooks reload

Install Hooks

zirkabot hooks install <path-or-spec>

Install a hook pack from a local folder/archive or npm.

What it does:

  • Copies the hook pack into ~/.zirkabot/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
zirkabot hooks install ./my-hook-pack

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

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

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

Update Hooks

zirkabot hooks update <id>
zirkabot 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:

zirkabot hooks enable session-memory

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

See: session-memory documentation

command-logger

Logs all command events to a centralized audit file.

Enable:

zirkabot hooks enable command-logger

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

View logs:

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

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

# Filter by action
grep '"action":"new"' ~/.zirkabot/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:

zirkabot hooks enable soul-evil

See: SOUL Evil Hook

boot-md

Runs BOOT.md when the gateway starts (after channels start).

Events: gateway:startup

Enable:

zirkabot hooks enable boot-md

See: boot-md documentation