Fjall Docs — deploy AWS infrastructure into your own account

Session hooks give Claude Code ambient awareness of your Fjall state before its first turn.

What session hooks do

An agent makes better decisions when it already knows whether the CLI is logged in, which organisation it is logged in to, and which Fjall project the session opened in. A session hook supplies those facts at session start, so the agent spends no turn discovering them. fjall agent install-hooks writes one SessionStart entry into ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "fjall agent session-context",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Property	Value
Host	Claude Code only
File	`~/.claude/settings.json`
Hook key	`hooks.SessionStart`
Command	`fjall agent session-context`
Host timeout	10 seconds, after which Claude Code abandons the hook
Exit code	Always 0. A probe that cannot answer degrades one field instead of failing the session

Fjall identifies its own hook by exact command equality. An entry running any other command is treated as somebody else’s hook, so fjall agent uninstall-hooks leaves it alone and the next install adds a second, real entry beside it. Copy the command string verbatim if you hand-edit settings.json.

Claude Code is the only host the installer writes to. Agents on other hosts — Codex, Cursor, Copilot — get agent mode output the same way every caller does, by passing --agent; they just get no hooks.

Install hooks

Hooks are never installed automatically. Run the installer once:

fjall agent install-hooks

The installer also retires any legacy hooks.UserProjectConfig entry left behind by a CLI older than 19.0.0. That key was never read by Claude Code, and both install and uninstall delete it.

What the hook provides

The hook runs fjall agent session-context, which prints a TOON record. Run it yourself to see exactly what your agent receives:

fjall agent session-context

auth: logged_in
organisation: Acme
project: /work/api/fjall
cliVersion: 39.0.0
updateAvailable: none
skillVersion: 39.0.0

Field	Meaning
`auth`	`logged_in`, `logged_out`, or `unknown` when the probe could not ask
`organisation`	Organisation name when logged in, `none` when logged out, the last cached name or `unknown` when the probe could not ask
`project`	Absolute path of the Fjall config directory the session opened in, or `none` outside a project
`cliVersion`	Version of the installed CLI
`updateAvailable`	`<current> -> <latest>` when a newer CLI is published, otherwise `none`
`upgrade`	The upgrade command to run. Present only alongside an available update
`skillVersion`	Installed skill version, or its state: `missing`, `unstamped`, `incomplete`, `unreadable`
`skillStale`	`true` only when the installed skill lags the CLI
`degraded`	Each probe that could not answer, as `name: reason`. Present only when a probe failed

Degraded output

A failed probe never becomes a wrong answer. auth: unknown means the question could not be asked, which is different from auth: logged_out, and the degraded field names the probe that fell over so the agent can tell the two apart.

auth: unknown
organisation: Acme
project: /work/api/fjall
cliVersion: 39.1.0
updateAvailable: 39.1.0 -> 39.2.0
upgrade: npm install -g fjall@latest
skillVersion: 39.0.0
skillStale: true
degraded: "auth: auth probe timed out"

The command is cache-first and makes exactly one network call, a 2-second identity probe. Past that bound the answer is unknown, never logged_out, so a flaky link cannot tell your agent to re-authenticate.

Installer output

On success the installer prints the file it wrote and how to manage the hook:

Installed session hooks for:
  - Claude Code (~/.claude/settings.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

Upgrading from a CLI older than 19.0.0 adds one housekeeping line:

Installed session hooks for:
  - Claude Code (~/.claude/settings.json)
  Note: Claude Code: removed the legacy UserProjectConfig entry

Opting out

Suppress installation

FJALL_DISABLE_HOOKS=1 is read by the installer only, so it governs whether hooks get written and nothing else:

FJALL_DISABLE_HOOKS=1 fjall agent install-hooks

The installer skips every target and reports Skipped: all (opt-out active). Setting the variable on any other command has no effect, and it does not disable a hook that is already installed. To stop an installed hook running, remove it.

Remove and stay removed

fjall agent uninstall-hooks

This command:

Removes the Fjall SessionStart entry (and any legacy UserProjectConfig entry) from ~/.claude/settings.json.
Writes a ~/.fjall/hook-opt-out sentinel file, or $FJALL_CONFIG_DIR/hook-opt-out when you have relocated the state root.
Skips future installs while the sentinel exists.

Removed session hooks from:
  - Claude Code (~/.claude/settings.json)

Opt-out sentinel written to ~/.fjall/hook-opt-out
Future CLI upgrades will not re-install hooks.

To re-enable: fjall agent install-hooks --force-install

Re-enabling after opt-out

fjall agent install-hooks --force-install

--force-install deletes the opt-out sentinel and installs a fresh hook.

Idempotency and repair

Situation	What happens
Running the installer again	Rewrites the existing entry in place. No duplicate is created
Two copies of the Fjall hook	Collapsed to one canonical entry
An out-of-date Fjall entry (old command, wrong timeout)	Rewritten to the current canonical entry
Other hooks in `SessionStart`	Left untouched. Only entries matching the Fjall command are rewritten or removed
`settings.json` is broken JSON, or its `hooks` or `hooks.SessionStart` value has the wrong shape	The installer refuses to write, asks you to repair the file first, and exits non-zero
No `settings.json` yet	The installer creates the directory and the file
Uninstalling when no hook is present	Reports `Skipped: Claude Code: hook not found` and still writes the opt-out sentinel

Fjall never rewrites a settings.json it cannot parse, because overwriting it would destroy whatever else you keep there.

Security considerations

Property	Detail
Read-only	The hook runs `fjall agent session-context`, which only reads. It never deploys or changes AWS infrastructure
One bounded call	The single network call is a 2-second identity probe against the Fjall API. Everything else is read from local config and cache
Existing credentials	The probe uses the credential already stored at `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`). It never prompts and never mints new ones
Masked failures	Probe failure reasons pass through the credential mask before rendering
Local output	Hook output goes to the agent’s context window on your machine, not to any third-party service

Next Steps

Agent Mode

Drive Fjall from an AI coding agent with structured TOON output.

Log In

Authenticate the CLI so the hook can report your organisation.

Connect AWS

Connect an AWS account to give the agent real deployment context.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

Session Hooks

What session hooks do

Install hooks

What the hook provides

Degraded output

Installer output

Opting out

Suppress installation

Remove and stay removed

Re-enabling after opt-out

Idempotency and repair

Security considerations

Next Steps

Agent Mode

Log In

Connect AWS

​What session hooks do

​Install hooks

​What the hook provides

​Degraded output

​Installer output

​Opting out

​Suppress installation

​Remove and stay removed

​Re-enabling after opt-out

​Idempotency and repair

​Security considerations

​Next Steps

Agent Mode

Log In

Connect AWS

What session hooks do

Install hooks

What the hook provides

Degraded output

Installer output

Opting out

Suppress installation

Remove and stay removed

Re-enabling after opt-out

Idempotency and repair

Security considerations

Next Steps