> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

# `equabot hooks`

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

Related:

* Hooks: [Hooks](/hooks)
* Plugin hooks: [Plugins](/plugin#plugin-hooks)

## List All Hooks

```bash theme={null}
equabot 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):**

```bash theme={null}
equabot hooks list --verbose
```

Shows missing requirements for ineligible hooks.

**Example (JSON):**

```bash theme={null}
equabot hooks list --json
```

Returns structured JSON for programmatic use.

## Get Hook Information

```bash theme={null}
equabot hooks info <name>
```

Show detailed information about a specific hook.

**Arguments:**

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

**Options:**

* `--json`: Output as JSON

**Example:**

```bash theme={null}
equabot hooks info session-memory
```

**Output:**

```
💾 session-memory ✓ Ready

Save session context to memory when /new command is issued

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

Requirements:
  Config: ✓ workspace.dir
```

## Check Hooks Eligibility

```bash theme={null}
equabot 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

```bash theme={null}
equabot hooks enable <name>
```

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

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

**Arguments:**

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

**Example:**

```bash theme={null}
equabot 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

```bash theme={null}
equabot hooks disable <name>
```

Disable a specific hook by updating your config.

**Arguments:**

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

**Example:**

```bash theme={null}
equabot hooks disable command-logger
```

**Output:**

```
⏸ Disabled hook: 📝 command-logger
```

**After disabling:**

* Restart the gateway so hooks reload

## Install Hooks

```bash theme={null}
equabot hooks install <path-or-spec>
```

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

**What it does:**

* Copies the hook pack into `~/.equabot/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:**

```bash theme={null}
# Local directory
equabot hooks install ./my-hook-pack

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

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

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

## Update Hooks

```bash theme={null}
equabot hooks update <id>
equabot 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:**

```bash theme={null}
equabot hooks enable session-memory
```

**Output:** `~/equa/memory/YYYY-MM-DD-slug.md`

**See:** [session-memory documentation](/hooks#session-memory)

### command-logger

Logs all command events to a centralized audit file.

**Enable:**

```bash theme={null}
equabot hooks enable command-logger
```

**Output:** `~/.equabot/logs/commands.log`

**View logs:**

```bash theme={null}
# Recent commands
tail -n 20 ~/.equabot/logs/commands.log

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

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

**See:** [command-logger documentation](/hooks#command-logger)

### soul-evil

Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.

**Enable:**

```bash theme={null}
equabot hooks enable soul-evil
```

**See:** [SOUL Evil Hook](/hooks/soul-evil)

### boot-md

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

**Events**: `gateway:startup`

**Enable**:

```bash theme={null}
equabot hooks enable boot-md
```

**See:** [boot-md documentation](/hooks#boot-md)