Lifecycle hooks
Hooks are your own shell scripts that Plexus runs at key moments in a session's life, so every new worktree starts ready to work.
The three events
A hook is attached to one lifecycle event. Each hook has a name and a multi-line command, run through sh -c on macOS and Linux or cmd.exe /C on Windows — write it as a small script, not just a single line.
| Event | When it fires | Typical use |
|---|---|---|
| Create | A new session worktree is created | Install dependencies, scaffold local config, warm caches |
| Run | The agent starts or resumes | Start a dev server, tail a log, kick off a watcher |
| Teardown | A session is torn down | Stop background processes, clean up scratch resources |
Hooks run on your machine with your permissions, your full PATH, and your toolchain. Only enable repo-committed hooks from repos you trust. Plexus strips Anthropic credentials (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN) from a hook's environment, but everything else is reachable.
Where hooks are defined
Hooks live at three levels, and lower levels inherit from higher ones:
- Global — apply to every workspace, project, and session.
- Workspace — apply to every project in that workspace.
- Project — apply to every session in that project.
Sessions never define their own hooks; they always inherit the composed plan from their project. To change what a session runs, edit its project-level hooks. Open Settings → Hooks, pick a scope, then pick the Create / Run / Teardown event tab to edit that combination.
Composition modes
A non-global level doesn't just add its hooks to the inherited ones — it declares a combine mode that says how its hooks join what it inherits.
| Mode | Effect |
|---|---|
| Override | Discard all inherited hooks; only this level's hooks run (the managed built-in still runs — see below). |
| Before | Run this level's hooks ahead of the inherited ones. |
| After (default) | Run this level's hooks behind the inherited ones. |
| Parallel | Run this level's hooks concurrently, alongside the rest. |
Set the mode from the Combine mode dropdown on each event tab at the workspace or project scope.
Resolution and execution order
Plexus resolves the plan top-down — global → workspace → project — applying each level's combine mode. The resulting plan then runs in four phases, always in this order:
- Before — sequential. A non-zero exit can abort the launch (see below).
- Action — the event's managed built-in (for Create, the copy-paths step).
- Parallel — concurrent, best-effort. A failure here never aborts.
- After — sequential, and always runs.
Within the Hooks defined here list, use the up/down controls to set the order of your own hooks at that level. The live Resolved plan preview shows the final four-phase plan exactly as it will run — every hook, its source badge (Global / Workspace / Project / Built-in / From repo), and whether it's enabled. This is the fastest way to confirm inheritance did what you expect. Toggle any hook off without deleting it; disabled hooks stay in the list and appear dimmed in the preview.
The managed copy-paths built-in
On the Create event, Plexus runs a managed built-in that copies configured files into the new worktree — this is how gitignored files like .env reach the session. It lives in the Action phase and is immune to Override: even a project that overrides every inherited hook still gets the copy-paths step. Configure it with worktree.copyEnabled and worktree.copyPaths (default .env, .env.local) — see Worktrees for the full path rules.
Repo-committed hooks
A team can share hooks by committing them to the repo at .plexus/hooks.json. The file maps each event to an ordered array of { name, command } entries; command may be multi-line and may call a repo script.
{
"create": [
{ "name": "Install deps", "command": "pnpm install" },
{ "name": "Setup", "command": "set -e\nbash .plexus/hooks/setup.sh" }
],
"run": [],
"teardown": []
}
When this manifest is present and hooks.repoScriptsEnabled (default on) is true, its hooks replace the app-managed project hooks — so cloning the repo is enough for a teammate to get the same setup. Plexus shows a "Repo hooks active" banner with a Run repo-committed hooks toggle on the Project scope; turn it off to fall back to the app-managed hooks without deleting the file. If the manifest fails to parse, the error is surfaced in the editor and Plexus falls back to the app-managed hooks rather than breaking the session.
Aborting on failure
hooks.abortOnFailure (default on) stops a session launch if a Create hook in the before or action phase exits non-zero — so you never get a half-set-up worktree. Run and teardown hooks never abort the lifecycle. Override the setting to make Create hooks non-blocking.