Using Paqad with Claude Code

Claude Code is one of two tools where Paqad can stop certain edits before they happen and check the change when the AI finishes its turn. It does this through hooks: moments in Claude Code's work when it runs a program Paqad supplies, and respects that program's answer. Onboarding writes CLAUDE.md for the instructions and .claude/settings.json for the hooks.

What Paqad can enforce in Claude Code

Claude Code has the highest level of Paqad enforcement: blocks and checks. When the hooks are in place and Paqad is switched on:

• An edit made with the Edit, Write or NotebookEdit tool is refused until the AI has loaded the Paqad framework in this session.
• Edits are refused while a decision is waiting for your answer.
• For feature work, a source-code edit is refused until the earlier stages (such as planning and specification) are recorded and the relevant rules have been loaded.
• When the AI finishes its turn, a verification script checks the change. If a check fails outright, Claude Code is told to keep working and fix it.

Each of these is a deterministic check: a script decides from files on disk, not the AI. Checks that need judgment are not re-run by the hook.

Files onboarding writes

File	What it is
CLAUDE.md	The entry file. It tells the AI to open .paqad/framework-path.txt and follow the installed framework, or to act as a normal assistant if Paqad is missing or off. If you already have a CLAUDE.md, your text is kept and Paqad's lines go in a marked block.
.claude/settings.json	Claude Code's own settings file, with Paqad's hooks added. Settings and hooks you already had are kept.
.claude/.gitignore	Tells git to ignore settings.json and settings.hooks.json, because the hook commands contain a path specific to your computer.
.claude/settings.hooks.json	A bookkeeping list of the hook files Paqad selected. Claude Code does not run it.
.claude/settings.mcp.json	The MCP servers Paqad suggests for your stack. It has no start commands, so it does not connect Claude Code to anything by itself.
.claude/cache.json, .claude/memory.json	Paqad bookkeeping. Not Claude Code settings.

Outside the project, the Paqad install also writes six stage helpers to ~/.claude/agents/: paqad-planning, paqad-specification, paqad-development, paqad-review, paqad-checks and paqad-documentation-sync. These are subagents, separate AI helpers that Claude Code can start for one stage of the work.

The hooks Paqad adds

Claude Code event	Paqad script	Can it stop work?
PreToolUse, matched to Edit|Write|NotebookEdit	agent-entry-gate.mjs	Yes. Refuses the edit until the framework is loaded.
PreToolUse	stage-writer.mjs	No. Records which stage the edit belongs to.
PreToolUse	decision-pause-gate.mjs	Yes. Refuses edits while a decision is open in .paqad/decisions/pending/.
PreToolUse	capability-gate.mjs pre-mutation	Yes. Refuses feature edits until earlier stages are recorded and rules are loaded. Scripted rule checks only refuse when rule_compliance is set to strict (the default is warn).
UserPromptSubmit	agent-entry-prompt-gate.mjs, ticket-intake-prompt.mjs	No, by default. Adds loading instructions and project context to your message.
SessionStart	agent-entry-session-start.mjs, silent-update.mjs	No. Resets the per-session load check and looks for a newer Paqad version.
Stop	stage-marker-parse.mjs, verification-completion.mjs, capability-gate.mjs completion	Yes, once per turn. On a hard failure the AI is told to continue and fix it.
SubagentStop, matched to ^paqad-	stage-agent-completion.mjs	No. Records a row when a Paqad stage helper finishes.

Every hook is run as node "<your home>/.paqad-ai/current/hooks/<file>", so it works the same on Windows, macOS and Linux as long as node is available.

Setting it up

1. Run paqad-ai onboard --providers claude-code in your project, or tick Claude Code when onboarding asks.
2. Start a new Claude Code session in the project so it picks up the new settings.
3. Ask each teammate to run paqad-ai join once on their own machine. Because .claude/settings.json is ignored by git, the hooks do not arrive with a normal clone.
4. Run paqad-ai doctor to check the install. See paqad-ai doctor.

Two things Paqad changes by default

Automatic updates. At the start of each session, silent-update.mjs checks whether a newer paqad-ai exists. If so, it runs npm install -g paqad-ai@latest in the background, then paqad-ai update --silent. It never blocks the session. To turn this off, set auto_update=false in Paqad's config (for example .paqad/.config) or set the PAQAD_AUTO_UPDATE environment variable.

Commit attribution. With the default ai_attribution=strip policy, Paqad sets Claude Code's attribution setting so commits and pull requests do not get Claude's co-author line. Any attribution values you set yourself are kept.

Limits to know

• Only the Edit, Write and NotebookEdit tools are checked before they run. A file changed with a shell command is not stopped beforehand. The end-of-turn check reads the working tree, so it still sees that change afterwards.
• The end-of-turn check blocks at most once per turn. If the same problem remains, it lets the session end.
• The stage check is on by default (stages_mode is strict). A team can lower it to warn or off in its shared Paqad config; a single developer can only make it stricter, not weaker.
• If the hook scripts cannot run, for example because the install is missing, they let work continue.
• Paqad can be switched off with paqad-ai disable or PAQAD_DISABLED=1. Then no hook blocks anything, although a finished turn is logged as a disabled session.
• In JetBrains IDEs, only the Claude Code plugin (which runs the real claude command) fires these hooks. The Claude Agent inside JetBrains AI Assistant does not. See Junie and other JetBrains options.