Skip to main content
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:
AgentConfiguration fileHook key
Claude Code~/.claude/settings.jsonhooks.UserProjectConfig
Codex~/.codex/hooks.jsonpre-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:
  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

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

​
Idempotency and updates

BehaviourWhat happens
Running the installer againUpdates the existing hook in place. It does not create duplicates.
Malformed hook entryThe installer overwrites it cleanly.
Updated hook commandA later install rewrites the hook entry with the current command.

​
Security considerations

PropertyDetail
Read-onlyHooks run only the fjall status command. They never modify infrastructure.
Existing credentialsThe hook runs with whatever credentials are already configured in your environment.
No external dataNo data leaves your machine beyond what fjall status reads from the Fjall API.
Local outputHook 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.