Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

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:

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:

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)

fjall agent uninstall-hooks

This command:

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

Re-enabling after opt-out

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

Agent Mode

Use Fjall from AI coding agents with structured TOON output.

Log In

Authenticate the Fjall CLI before running agent commands.

Connect AWS

Connect an AWS account so the CLI has deployment context to inject.

Core Commands

Infrastructure Codemods

Management Commands

Authentication

Agent Mode

Session Hooks

What session hooks do

Install hooks

What the hook provides

Installer output

Opting out

Temporary (single invocation)

Permanent (survives upgrades)

Re-enabling after opt-out

Idempotency and updates

Security considerations

Next Steps

Agent Mode

Log In

Connect AWS

​What session hooks do

​Install hooks

​What the hook provides

​Installer output

​Opting out

​Temporary (single invocation)

​Permanent (survives upgrades)

​Re-enabling after opt-out

​Idempotency and updates

​Security considerations

​Next Steps

Agent Mode

Log In

Connect AWS

What session hooks do

Install hooks

What the hook provides

Installer output

Opting out

Temporary (single invocation)

Permanent (survives upgrades)

Re-enabling after opt-out

Idempotency and updates

Security considerations

Next Steps