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

# Session Hooks

> Install Fjall session hooks to inject deployment context into Claude Code, Codex, and other AI coding agents automatically.

Session hooks give an AI coding agent ambient awareness of your Fjall deployment state at the start of each session.

## What session hooks do

When you work with an AI coding agent (Claude Code, Codex, Cursor, GitHub Copilot), the agent makes better decisions when it knows your deployment context: which organisation, applications, and AWS accounts you are working with.

A session hook injects that context automatically when an agent session starts. Instead of the agent running `fjall status` itself, the hook runs a lightweight status check and supplies the result as ambient context.

## Install hooks

Hooks are not installed automatically. Run the installer once:

```bash theme={null}
fjall agent install-hooks
```

The installer writes a hook entry into each detected agent configuration file:

| Agent       | Configuration file        | Hook key                  |
| ----------- | ------------------------- | ------------------------- |
| Claude Code | `~/.claude/settings.json` | `hooks.UserProjectConfig` |
| Codex       | `~/.codex/hooks.json`     | `pre-session` event       |

Each hook runs `fjall status --agent --budget minimal`, which outputs a compact summary of your deployment state in roughly 50 tokens.

### What the hook provides

```
apps: 3 total (2 healthy, 1 deploying)
organisation: my-org
environment: production
```

This gives the agent enough context to make informed decisions without consuming your token budget.

### Installer output

On success, the installer prints the files it wrote and how to manage the hooks:

```
Installed session hooks for:
  - Claude Code (~/.claude/settings.json)
  - Codex (~/.codex/hooks.json)

To remove: fjall agent uninstall-hooks
To disable temporarily: set FJALL_DISABLE_HOOKS=1
Docs: https://docs.fjall.io/cli/agent-mode/session-hooks
```

## Opting out

### Temporary (single invocation)

Set the environment variable before running a command:

```bash theme={null}
FJALL_DISABLE_HOOKS=1 fjall deploy my-app --agent
```

While `FJALL_DISABLE_HOOKS=1` is set, `fjall agent install-hooks` skips installation.

### Permanent (survives upgrades)

```bash theme={null}
fjall agent uninstall-hooks
```

This command:

1. Removes Fjall session hooks from all detected agent configuration files.
2. Writes a `~/.fjall/hook-opt-out` sentinel file.
3. Stops future installs while the sentinel exists.

### Re-enabling after opt-out

```bash theme={null}
fjall agent install-hooks --force-install
```

The `--force-install` flag removes the opt-out sentinel and installs fresh hooks.

## Idempotency and updates

| Behaviour                   | What happens                                                       |
| --------------------------- | ------------------------------------------------------------------ |
| Running the installer again | Updates the existing hook in place. It does not create duplicates. |
| Malformed hook entry        | The installer overwrites it cleanly.                               |
| Updated hook command        | A later install rewrites the hook entry with the current command.  |

## Security considerations

| Property             | Detail                                                                              |
| -------------------- | ----------------------------------------------------------------------------------- |
| Read-only            | Hooks run only the `fjall status` command. They never modify infrastructure.        |
| Existing credentials | The hook runs with whatever credentials are already configured in your environment. |
| No external data     | No data leaves your machine beyond what `fjall status` reads from the Fjall API.    |
| Local output         | Hook output goes to the agent's context window, not to any third-party service.     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Mode" icon="robot" href="/cli/agent-mode">
    Use Fjall from AI coding agents with structured TOON output.
  </Card>

  <Card title="Log In" icon="key" href="/cli/login">
    Authenticate the Fjall CLI before running agent commands.
  </Card>

  <Card title="Connect AWS" icon="aws" href="/cli/connect">
    Connect an AWS account so the CLI has deployment context to inject.
  </Card>
</CardGroup>