Docs
Getting started
Joule Atelier ships three things you install locally: a CLI, a hook bridge, and a set of MCP servers your agent talks to. This page is the five-minute path from a fresh shell to a guarded tool call.
Install the CLI
# requires Node 22 LTS
bunx --no-install @jouleatelier/cli init
init walks you through:
- Creating
~/.jouleatelier/config.json(idempotent — safe to re-run). - Detecting Claude Code and Codex installs and offering to wire their hooks.
- Optionally signing into Joule Atelier cloud for sync.
Skip step 3 if you only want local enforcement. Everything below works offline.
Run doctor
jouleatelier doctor
The doctor checks your Node version, keychain access, MCP server availability, hook bridge ping latency, and provider-specific hook installs. Anything red is a one-line remediation.
MCP servers
Three MCP servers ship with the CLI today:
@jouleatelier/mcp-tasks— task tracking with explicit state machine, dependency graph, and audit trail.@jouleatelier/mcp-memories— long-lived memory with FTS5 search and optional vector retrieval (BYOK embeddings).@jouleatelier/mcp-guardrails— policy enforcement for tool allowlists, path denylists, regex-based input/output filters.
Each server runs as a stdio child process spawned by your agent. There is no network listener; nothing runs as a daemon by default.
Hooks
Hooks bind your agent to the guardrail engine before tools run. We ship two adapters:
- Claude Code —
PreToolUse,PostToolUse,Stop,UserPromptSubmit. - Codex —
PreToolUseandPostToolUsefor theBashtool only, per Codex’s current hook surface.
Install or reinstall hooks with:
jouleatelier install-hooks
The install is idempotent and merges with any existing hook entries. A
--dry-run flag prints the diff without writing.
Gate a tool call
Once hooks are installed, every bash, read, or write your agent issues
flows through the bridge. Block on a path:
jouleatelier config set guardrails.path_denylist '["~/.ssh/**", "/etc/**"]'
Watch it work:
$ claude "redact ~/.ssh/id_rsa"
✋ blocked by path_denylist (~/.ssh/**)
audit_id: aud_01HABCDE — see jouleatelier audit show
That’s it. You now have hard guardrails on every agent-driven tool call, synced (optionally) to your team in the cloud.