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

# Hooks

# Hooks

Hooks are local event handlers that run inside the gateway when matching Fased
events occur. They are useful for small runtime extensions such as session
memory, startup files, command logging, and plugin-side tool-result transforms.

Hooks are local runtime extensions. For inbound HTTP automation, read
[Webhooks](/automation/webhook).

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
flowchart TD
  Event["Gateway event"] --> Registry["Hook registry"]
  Registry --> Handler["Enabled hook handler"]
  Handler --> Result["Messages or side effect"]
  Handler --> Logs["Logs and diagnostics"]

  classDef main fill:#1f2937,stroke:#ff8a65,color:#ffffff
  classDef aux fill:#101827,stroke:#38bdf8,color:#ffffff
  class Event,Registry,Handler main
  class Result,Logs aux
```

## Normal path

Most users only need the bundled `session-memory` hook.

1. Enable `session-memory` during onboarding or from **Agent > Memory**.
2. Use **Extensions > Hooks** to inspect enabled hook packs.
3. Use **Advanced > Config** only when a hook has no UI yet.
4. Restart the gateway if the UI says runtime hook state has not caught up.

Custom hooks and hook packs are executable code. Review the source before
installing or enabling them.

## Bundled hooks

**`session-memory`**

Event: `/new`, `/reset`. Archives recent session context into the Agent
workspace memory area. Normal setup path: onboarding or Agent > Memory.

**`boot-md`**

Event: gateway startup. Runs `BOOT.md` from each Agent workspace on gateway
start. Normal setup path: operator startup automation.

**`bootstrap-extra-files`**

Event: agent bootstrap. Adds extra workspace files into Agent bootstrap
context. Normal setup path: advanced workspace setup.

**`command-logger`**

Event: commands. Appends command events to `~/.fased/logs/commands.log`.
Normal setup path: debug command usage.

Useful commands:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased hooks list
fased hooks enable session-memory
fased hooks disable session-memory
fased hooks info session-memory
fased hooks check
```

## Discovery

Hooks are loaded from these sources, later sources winning name conflicts:

1. extra hook directories from `hooks.internal.load.extraDirs`
2. bundled hooks: `<fased>/dist/hooks/bundled/`
3. managed hooks: `~/.fased/hooks/`
4. workspace hooks: `<workspace>/hooks/`

Each hook is a directory:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
my-hook/
├── HOOK.md
└── handler.ts
```

## Hook packs

Hook packs are npm packages that expose one or more hooks through
`package.json -> fased.hooks`.

Install with:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased hooks install <path-or-spec>
```

Rules:

* npm specs are registry-only
* local directories and local archives are supported for operator-controlled
  installs
* Git, URL, and arbitrary remote specs are rejected
* hook entries must resolve inside the package directory
* dependencies install with `npm install --ignore-scripts`

Example:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "fased": {
    "hooks": ["./hooks/my-hook"]
  }
}
```

Keep hook-pack dependency trees small and treat third-party hook packs as
executable code.

## Hook metadata

`HOOK.md` combines metadata and human docs.

```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}}
---
name: my-hook
description: "Short description"
metadata:
  { "fased": { "emoji": "hook", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Explain what it does and how to enable it.
```

Supported `metadata.fased` fields:

* `emoji`
* `events`
* `export`
* `homepage`
* `requires`
* `always`
* `install`

`requires` can check binaries, environment variables, config keys, and OS
constraints before a hook is considered eligible.

## Handler shape

Handlers are async functions that inspect an event, optionally append messages
to the event, and may perform a small side effect.

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] new session ${event.sessionKey}`);
};

export default handler;
```

Handlers receive:

* `type`
* `action`
* `sessionKey`
* `agentId`
* `config`
* event-specific payload

Filter events early, keep handlers fast, and avoid throwing for ordinary
non-matching events.

## Event families

**Command**

Examples: `command:new`, `command:reset`, `command:custom`.

**Agent**

Example: `agent:bootstrap`.

**Gateway**

Examples: `gateway:startup`, `gateway:shutdown`.

**Message**

Examples: `message:received`, `message:sent`.

**Tool result**

Plugin-side tool-result transforms.

Tool-result hooks are intentionally narrow. They can transform tool output for
a participating plugin path. Tool, credential, wallet, mining, and marketplace
authority stay in their owning surfaces.

## Configuration

Current config shape:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  hooks: {
    internal: {
      enabled: true,
      load: {
        extraDirs: [],
      },
      entries: {
        "session-memory": {
          enabled: true,
          messages: 20,
        },
      },
    },
  },
}
```

For internal runtime hooks, use `hooks.internal.enabled` and
`hooks.internal.entries`. Top-level `hooks.enabled` belongs to HTTP webhook
ingress, not local runtime hooks.

## Debugging

Start with:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased hooks list
fased hooks info <name>
fased hooks check
fased logs --follow
```

Common causes:

**Hook not discovered**

Check directory name, `HOOK.md`, load source, and name collisions.

**Hook not eligible**

Check missing binary, env var, config key, or OS requirement.

**Hook not executing**

Check event name, enabled state, gateway restart, and logs.

**Handler errors**

Catch expected failures and write concise diagnostics.

## See also

* [Webhooks](/automation/webhook)
* [Automation](/automation)
* [Hooks CLI](/cli/hooks)
* [Agent workspace](/concepts/agent-workspace)