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).
Where hooks come from
Section titled “Where hooks come from”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.
Events
Section titled “Events”| 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.
What a hook receives
Section titled “What a hook receives”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.
What a hook answers
Section titled “What a hook answers”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:
PreToolUseblocked: the tool call fails and the model readsA PreToolUse hook blocked this call: <reason>.PostToolUsefeedback: added after the tool’s output asPostToolUse hook feedback: <reason>, with any context.UserPromptSubmitblocked: your message is not sent to the model and the reply readsA UserPromptSubmit hook blocked this message: <reason>. While anyUserPromptSubmithook 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.SessionStartandUserPromptSubmitcontext joins your message as a note only the model sees.Stopblocked: the reason is given to the model asStop 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: …”.
Hooks and the permission rules
Section titled “Hooks and the permission rules”For each tool call, in this order:
- 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.
PreToolUsehooks run. A block ends the call with the hook’s reason.- If a hook rewrote the input, the rules judge the new input too, so a deny rule still catches it.
- 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.
- A hook’s ask forces the prompt (“A PreToolUse hook asks for your approval.”) and skips Auto’s review.
- 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.
Worked examples
Section titled “Worked examples”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:
#!/bin/shif jq -e '.tool_input.command | test("git push")' >/dev/null; then echo "Pushing is done by a person. Ask them to push." >&2 exit 2fiThe 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:
#!/bin/shif 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"}}'fiFormat what the model writes (PostToolUse on Edit|Write).
#!/bin/shfile=$(jq -r '.tool_input.file_path')case "$file" in *.ts|*.tsx|*.js|*.json|*.md) npx --no-install prettier --write "$file" >/dev/null 2>&1 ;;esacexit 0Keep a key out of the model (UserPromptSubmit). Your message is stopped before the model or the provider sees it:
#!/bin/shif 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 2fiDo not stop with failing tests (Stop). stop_hook_active keeps the hook from insisting forever:
#!/bin/shif jq -e '.stop_hook_active' >/dev/null; then exit 0; fiif ! npm test --silent >/dev/null 2>&1; then echo "The tests fail. Run them, fix the failures, then finish." >&2 exit 2fiTell 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" }] } ] }}Where Atelier differs from Claude Code
Section titled “Where Atelier differs from Claude Code”Safety
Section titled “Safety”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.
Plugins
Section titled “Plugins”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.jsonplugin.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.
Install a plugin
Section titled “Install a plugin”Admins manage plugins in Settings › Admin › Plugins or on Customize › Plugins.
- In Add from a marketplace, enter the marketplace’s GitHub repository (
owner/repoor agithub.comURL) and choose Browse. Marketplaces you installed from before appear as Added before: buttons. - 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/cachein the config folder). - 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. |
Turn on, off, remove, update
Section titled “Turn on, off, remove, update”- 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, keyedplugin@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.
Admin controls
Section titled “Admin controls”| 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. |