Hooks

Hooks let a repository run shell commands automatically at points in a worktree's lifecycle — for example, installing dependencies as soon as a new worktree is created, so an agent starts in a ready-to-build tree.

Hooks live in a per-repo .flightdeck/hooks.toml. FlightDeck creates this file (empty, only commented) the first time it opens a project, and gitignores it by default — so hooks only affect the machine that opts in until you deliberately share them (see Sharing hooks).

The file

# <repo>/.flightdeck/hooks.toml

# Runs in a new worktree right after it is created for an Agent Tab.
[worktree_created]
commands = [
  "npm install",
]

# Runs in an Agent Tab's worktree after it is rebased onto an updated base branch.
[worktree_update]
commands = [
  "npm install",
]

Available hooks

Hook	When it runs	Working directory
`worktree_created`	Right after a new worktree is created for an Agent Tab. It does not run when an existing worktree is reused, or for a tab that runs directly on the base branch (which creates no worktree).	The new worktree.
`worktree_update`	After an Agent Tab's worktree is rebased onto an updated base branch (the Rebase action). Useful when the base moving under the worktree means dependencies or generated files need refreshing.	The rebased worktree.

More hooks may be added over time. A hooks.toml written by a newer FlightDeck still loads on an older one — unknown hooks are simply ignored.

How commands run

Each hook has a commands array. Commands run sequentially, in the hook's working directory, through your shell (sh -c on macOS/Linux, cmd /C on Windows). If a command exits non-zero, the remaining commands for that hook are skipped — a hook behaves like a set -e script.

Multi-line commands

A single command may span multiple lines using TOML's triple-quoted strings. The whole block runs as one shell script, so it shares one working directory and environment:

[worktree_created]
commands = [
  "cp .env.example .env",
  """
  npm install
  npm run build
  """,
]

Here the first array entry runs as its own script, then the triple-quoted entry runs as a second script containing both npm lines.

Best-effort, never destructive

Hooks are best-effort. A failing hook is surfaced as a warning but never rolls back the worktree it ran in — the worktree already exists, and FlightDeck never throws away your work. If a worktree_created command fails, the Agent Tab is still created and its agent still starts; you'll see a toast naming the command that failed.

Hook output is captured (not streamed to the terminal), so a noisy command can never corrupt the FlightDeck UI. Hooks are meant for non-interactive setup — for an interactive process, open a shell in the tab instead.

.flightdeck/hooks.toml is added to your .gitignore by default, alongside the other .flightdeck/ runtime entries. This keeps hooks opt-in per machine: a hook runs arbitrary commands, so committing one to a shared repo should be a deliberate choice.

To share your hooks with the team:

Remove the .flightdeck/hooks.toml line from your .gitignore.
Commit .flightdeck/hooks.toml.