Skip to content

Hooks and plugins

Two ways to extend Atelier beyond instructions and skills. Hooks are shell commands that run at fixed points of a session and can block, allow or annotate what the model is about to do. Plugins bundle skills, commands, sub-agents and hooks, and an admin installs them from a GitHub marketplace. Both use Claude Code’s formats, so what you have for Claude Code mostly works as it is; the differences are noted below.

A hook is a command Atelier runs for you at a point of a turn. Typical uses: refuse a command the model shouldn’t run, format a file after the model edits it, add a fact to the model’s context when a session starts, or make the model keep going until the tests pass.

Hooks run where a session has a folder: in Code, and in a chat you gave a folder. A chat without one runs no hooks. They run for a sub-agent’s tool calls too (PreToolUse and PostToolUse only).

All matching hooks from every source below run; there is no override order between them.

Source Where you write it Runs for
A project hooks in .atelier/settings.json or .atelier/settings.local.json, and with Claude Code compatibility on, .claude/settings.json or .claude/settings.local.json Sessions in that folder, wherever it lives (this computer, an SSH host, a codespace)
The admin Settings › Admin › Code › Automation › Hooks Sessions in folders on the backend’s own machine, never on a person’s own device
Claude Code’s user settings hooks in ~/.claude/settings.json (desktop app, compatibility on) Sessions in folders on this computer
Plugins hooks/hooks.json in an enabled plugin Sessions in folders on the backend’s own machine

The project files are re-read every few seconds. The Hooks row is a JSON text area holding the hooks object itself (without a "hooks" wrapper); Save is enabled once it parses. In every file the shape is the same:

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.atelier/hooks/no-push.sh\"", "timeout": 10 }]
}
]
}
}

Each event has a list of groups; a group has an optional matcher and a list of hooks. A hook has "type": "command", the command to run and an optional timeout in seconds (default 60, at most 3600). A hook that doesn’t fit (a timeout of 0 or above 3600, an empty command) is skipped without a message.

Event Fires matcher A hook can
SessionStart Before the first model request of a new session, and again after the model moves the session to another folder. Ignored Add context.
UserPromptSubmit When you send a message, before the model sees it. Ignored Block the message; add context.
PreToolUse Before each tool call runs, after deny rules and plan mode have had their say. A tool name Block the call; allow it, make it ask, or deny it; rewrite its input.
PostToolUse After a tool call ran (whether it succeeded or failed). A tool name Add feedback or context to the result. The call has already happened.
Stop When the model finishes a reply with nothing more to do. Ignored Send the model back to work.

A matcher is a regular expression that must match the whole tool name: Bash, Edit|Write, mcp__github__.*. An empty matcher or * matches every tool. Names are Atelier’s (Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Agent, Skill, TodoWrite, AskUser, …, and mcp__{connector}__{tool} for connector tools; see Tools). A matcher such as Bash(npm *) is a regular expression like any other and matches no tool.

The command runs on the machine the folder lives on (this computer, an SSH host or a codespace), through /bin/sh -c, or through PowerShell on Windows. It starts in the project’s folder with the event as JSON on standard input and two environment variables, CLAUDE_PROJECT_DIR and ATELIER_PROJECT_DIR, both set to the folder:

{
"session_id": "…",
"cwd": "/Users/ada/app",
"hook_event_name": "PreToolUse",
"permission_mode": "auto",
"tool_name": "Bash",
"tool_input": { "command": "git push origin main" }
}

permission_mode is auto, default, acceptEdits, plan or bypassPermissions. PostToolUse adds tool_response (the tool’s output as one string); UserPromptSubmit adds prompt; SessionStart adds source (always startup); Stop adds stop_hook_active (true from the second round on). There is no transcript_path. Tool inputs use Atelier’s field names: command for Bash, file_path for Read, Write and Edit, url for WebFetch.

Exit code.

Exit code Meaning
0 Fine. Standard output is read (below).
2 Block. What the hook wrote to standard error is the reason (or Blocked by hook: <command> if it wrote nothing).
Anything else A failure that blocks nothing. It is logged by the backend as Hook failed (exit N): <command> with the standard error; the conversation doesn’t show it.
Timeout Logged as Hook timed out after 60s: <command> (with the hook’s own timeout in place of 60); blocks nothing.

Standard output on exit 0. Plain text is added to the model’s context for UserPromptSubmit and SessionStart, and ignored by the other events. Output that starts with { is read as JSON:

Field Effect
hookSpecificOutput.permissionDecision allow, ask or deny (PreToolUse). deny blocks, with permissionDecisionReason as the reason.
decision "block" blocks, with reason; "approve" is the same as allow.
hookSpecificOutput.updatedInput An object that replaces the tool’s whole input (PreToolUse).
hookSpecificOutput.additionalContext Text added to the model’s context.
continue: false With stopReason: ends the turn and shows the reason. Honored only for UserPromptSubmit.

Other fields are ignored, and a field an event doesn’t use (a rewritten input from Stop, say) has no effect there. What the model or you see depends on the event:

  • PreToolUse blocked: the tool call fails and the model reads A PreToolUse hook blocked this call: <reason>.
  • PostToolUse feedback: added after the tool’s output as PostToolUse hook feedback: <reason>, with any context.
  • UserPromptSubmit blocked: your message is not sent to the model and the reply reads A UserPromptSubmit hook blocked this message: <reason>. While any UserPromptSubmit hook exists, a message you type while the model is working waits for the end of the turn instead of joining it, so the hook can see it.
  • SessionStart and UserPromptSubmit context joins your message as a note only the model sees.
  • Stop blocked: the reason is given to the model as Stop hook feedback: <reason> and it works on. This repeats at most three times a turn.

When several hooks match an event they run in parallel and their answers are combined: blocks are joined, deny beats ask beats allow, the first updatedInput and first stopReason win, and added context is joined (at most 10,000 characters). A rewritten input that no longer fits the tool’s schema is refused with “A hook changed the input of Bash into something invalid: …”.

For each tool call, in this order:

  1. The permission engine decides first: deny rules, plan mode’s refusal, ask rules, allow rules and the mode. A deny rule (or plan mode’s refusal) ends it there; no hook can allow what a deny rule blocks, and the hooks don’t run.
  2. PreToolUse hooks run. A block ends the call with the hook’s reason.
  3. If a hook rewrote the input, the rules judge the new input too, so a deny rule still catches it.
  4. A hook’s allow skips the prompt the mode would have raised, and Auto mode’s review. It does not skip an ask rule or the warning for a dangerous command, which still go to Auto’s reviewer or to you, one call at a time.
  5. A hook’s ask forces the prompt (“A PreToolUse hook asks for your approval.”) and skips Auto’s review.
  6. With no hook opinion, the engine’s decision stands: allowed, asked, or reviewed.

Hooks themselves run outside the permission system: they are commands you wrote, and nothing reviews them.

The examples use jq and a POSIX shell; on Windows, hooks run in PowerShell and need to be written for it. Put the scripts in .atelier/hooks/ of the project.

Never push (PreToolUse on Bash). Exit code 2 and a message on standard error:

.atelier/hooks/no-push.sh
#!/bin/sh
if jq -e '.tool_input.command | test("git push")' >/dev/null; then
echo "Pushing is done by a person. Ask them to push." >&2
exit 2
fi

The model sees A PreToolUse hook blocked this call: Pushing is done by a person. Ask them to push. The test is a text match, so it catches the usual spelling and not every way of writing a push. For a rule that has to hold, add a deny rule such as Bash(git push *) under Settings › Admin › Code › Deny rules: rules also look inside git -C dir push, sudo and xargs, and no hook can allow what a deny rule blocks.

Let plain read-only git run unasked (PreToolUse on Bash). JSON on standard output. The pattern rejects anything with shell syntax in it, because a hook’s allow is as safe as its test:

.atelier/hooks/safe-git.sh
#!/bin/sh
if jq -e '.tool_input.command | test("^git (status|diff|log)( [A-Za-z0-9_./@~^-]+)*$")' >/dev/null; then
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"read-only git"}}'
fi

Format what the model writes (PostToolUse on Edit|Write).

.atelier/hooks/format.sh
#!/bin/sh
file=$(jq -r '.tool_input.file_path')
case "$file" in
*.ts|*.tsx|*.js|*.json|*.md) npx --no-install prettier --write "$file" >/dev/null 2>&1 ;;
esac
exit 0

Keep a key out of the model (UserPromptSubmit). Your message is stopped before the model or the provider sees it:

.atelier/hooks/no-keys.sh
#!/bin/sh
if jq -e '.prompt | test("sk-[A-Za-z0-9]{20,}")' >/dev/null; then
echo "That looks like an API key. Remove it and send the message again." >&2
exit 2
fi

Do not stop with failing tests (Stop). stop_hook_active keeps the hook from insisting forever:

.atelier/hooks/check-tests.sh
#!/bin/sh
if jq -e '.stop_hook_active' >/dev/null; then exit 0; fi
if ! npm test --silent >/dev/null 2>&1; then
echo "The tests fail. Run them, fix the failures, then finish." >&2
exit 2
fi

Tell the model where things stand (SessionStart). Plain output becomes context; no script is needed:

{ "type": "command", "command": "git log --oneline -5" }

All of them wired together in .atelier/settings.json:

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.atelier/hooks/no-push.sh\"", "timeout": 10 },
{ "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.atelier/hooks/safe-git.sh\"", "timeout": 10 }
]
}
],
"PostToolUse": [
{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.atelier/hooks/format.sh\"", "timeout": 60 }] }
],
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.atelier/hooks/no-keys.sh\"" }] }
],
"Stop": [
{ "hooks": [{ "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.atelier/hooks/check-tests.sh\"", "timeout": 300 }] }
],
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "git log --oneline -5" }] }
]
}
}

A hook is a program you or a project’s author chose to run, as you, with your files and network, unreviewed. A project’s .atelier/settings.json or .claude/settings.json can contain hooks, and they run as soon as a session works in that folder. The Trust this workspace? question is the only gate; it is asked when you add a folder on this computer, on an SSH host or a codespace. The backend keeps the answer: the hooks of a folder you haven’t trusted don’t run, whichever client added it. Read the settings files of a downloaded project before you open it. Turning Claude Code compatibility off (Settings › Admin › Code › Compatibility) makes Atelier ignore the .claude settings files, but not .atelier/settings.json. Hooks from plugins and from the admin’s Hooks row run on the backend’s own machine for everyone’s sessions there. See Security and Permissions.

A plugin is a folder that bundles any of these, usually with a .claude-plugin/plugin.json manifest (Atelier works without one, with the default folder names):

Part Where What it becomes
Skills skills/<name>/SKILL.md /plugin:name and the model’s skill list as plugin:name
Commands commands/*.md /plugin:command
Sub-agents agents/*.md The Agent tool’s type plugin:agent
Hooks hooks/hooks.json (or inline in the manifest) Hooks, as above; ${CLAUDE_PLUGIN_ROOT} in a command becomes the plugin’s folder

A plugin cannot bring connectors: MCP servers in a plugin are not read (add them under Connectors). See Customize for the file formats.

team-tools/
├── .claude-plugin/plugin.json
├── skills/changelog/SKILL.md
├── commands/ship.md
├── agents/reviewer.md
└── hooks/hooks.json

plugin.json needs little:

{
"name": "team-tools",
"description": "Our review and release routines",
"version": "1.0.0"
}

and hooks/hooks.json has the same shape as the hooks object above, wrapped in "hooks":

{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/format.sh\"", "timeout": 30 }] }
]
}
}

${CLAUDE_PLUGIN_ROOT} is replaced with the plugin’s folder before the command runs, as plain text, so put it in quotes.

skills, commands and agents in the manifest can name other folders than the defaults (one path or a list); hooks can name another file or hold the hooks object inline. A plugin’s names are prefixed with the plugin’s name so they can’t collide with yours: the skill changelog of team-tools is team-tools:changelog, and /team-tools:ship runs its ship.md command.

Admins manage plugins in Settings › Admin › Plugins or on Customize › Plugins.

  1. In Add from a marketplace, enter the marketplace’s GitHub repository (owner/repo or a github.com URL) and choose Browse. Marketplaces you installed from before appear as Added before: buttons.
  2. The page lists the plugins in it with their versions and descriptions. Choose Install on one. Atelier downloads the repository at its current commit and copies the plugin into its own folder (plugins/cache in the config folder).
  3. The plugin appears under Installed plugins, on. Its skills, commands and agents are available to sessions at once.

A marketplace is a GitHub repository with .claude-plugin/marketplace.json:

{
"name": "acme-tools",
"plugins": [
{ "name": "team-tools", "description": "Our review and release routines", "version": "1.0.0", "source": "./plugins/team-tools" },
{ "name": "lint-helper", "source": { "source": "github", "repo": "acme/lint-helper", "ref": "v2" } }
]
}

A plugin’s source is either a path inside the marketplace repository or a GitHub repository (with optional ref and path). Marketplace and plugin names are one plain word each (letters, digits, ., _, +, -, up to 64 characters). Plugins from other kinds of source are listed with “Plugins from “{kind}” sources can’t be installed yet.” Only public GitHub repositories work.

Message Meaning
Use owner/repo or a github.com URL for the marketplace. The text isn’t a GitHub repository.
That repository has no valid .claude-plugin/marketplace.json. Missing or malformed.
owner/repo wasn't found (or is private). Public repositories only.
acme-tools has no plugin named “x”. The plugin was removed from the marketplace.
team-tools's source points outside its marketplace. A relative source that climbs out of the repository.
  • Enable {name} turns a plugin on or off for everyone; off takes what it brings out of every session. The state is kept in the global settings as enabledPlugins, keyed plugin@marketplace.
  • Uninstall {name} deletes a plugin Atelier installed.
  • There is no update button: an installed plugin shows Installed in its marketplace. To take a newer version, uninstall it and install it again.
  • Settings › Admin › Developer › Reload connectors and extensions reads skills, commands, agents and plugins again.

On the desktop app, plugins installed with Claude Code (~/.claude/plugins/installed_plugins.json) are used too, while Claude Code compatibility is on. They carry a Claude Code badge and can only be switched on and off; turning one off in Atelier never touches Claude Code’s own settings. If the same plugin id is installed in both, Atelier’s copy is used.

Everyone can see the installed plugins and what they bring (skills, commands and agents; Customize › Plugins is read-only for non-admins). A plugin’s hooks run but are not listed in the interface: open the plugin’s folder to read them.

Control Where Effect
Hooks Settings › Admin › Code › Automation The system hooks, in Claude Code’s JSON format.
Claude Code compatibility Settings › Admin › Code › Compatibility Reads .claude settings, plugins installed by Claude Code, CLAUDE.md and more; see Claude Code compatibility.
Installed plugins, Add from a marketplace Settings › Admin › Plugins Install, enable, disable and uninstall plugins.
Connectors Settings › Admin › Connectors See Connectors.
Allow, ask and deny rules Settings › Admin › Code A deny rule always wins over a hook; see Permissions.