Skip to content

prs hook

Low-level hook handler invoked by AI tool hook systems. Not intended for direct use — configure it via prs hooks install.

Synopsis

prs hook <action> [options]

Description

prs hook is the binary entry point called by AI tool hook runners. It reads a JSON payload from stdin, acts on it, writes any messages to stderr, and exits with a code the tool interprets as pass or block.

There are two actions:

ActionTriggered byPurpose
pre-editTool is about to write a fileBlock writes to PromptScript-generated files
post-editTool has written a fileTrigger prs compile when a .prs file is saved

Actions

pre-edit

Terminal window
prs hook pre-edit

Reads a JSON object from stdin describing the file the tool is about to edit. Checks whether that file contains a PromptScript generation marker. If it does, writes an explanatory message to stderr and exits 2. Otherwise exits 0.

Stdin JSON format

The exact field names vary by tool. prs hook pre-edit understands all of the following:

ToolStdin field carrying the file path
Claude, Factory, Copilottool_input.file_path
CursorfilePath
Windsurffile_path
Clinefile
Gemini CLI write/edit toolsarguments.file_path

Unrecognised or missing path fields are treated as “no path” and the hook exits 0 (allow).

Marker detection

The hook reads the first 50 lines and recognizes <!-- PromptScript, # promptscript-generated:, or > Auto-generated by PromptScript. Files without one of these markers are passed through.

Example stdin (Claude Code)

{
"tool_name": "Edit",
"tool_input": {
"file_path": "CLAUDE.md",
"old_string": "...",
"new_string": "..."
}
}

Example stderr on block

CLAUDE.md is generated by PromptScript. Edit .promptscript/project.prs instead,
then run `prs compile` (or let the post-edit hook do it automatically).

post-edit

Terminal window
prs hook post-edit

Reads a JSON object from stdin describing the file that was just written. If the file has a .prs extension, runs prs compile and forwards compiler output to the tool. Compilation errors are reported on stderr rather than intentionally blocking the edit event.

Stdin JSON format

Same field mapping as pre-edit above.

Example stdin (Cursor)

{
"filePath": ".promptscript/project.prs"
}

Behaviour for non-.prs files

If the edited file is not a .prs file, the hook exits 0 immediately without running the compiler.

Exit Codes

CodeMeaningEffect on tool
0Pass / successTool proceeds normally
1Internal errorTool may log a warning; edit is allowed
2BlockTool cancels the edit and shows stderr to the user

Exit code 2 is only used by pre-edit. post-edit always exits 0.

Examples

Terminal window
# Simulate a pre-edit check (Claude Code payload)
echo '{"tool_name":"Edit","tool_input":{"file_path":"CLAUDE.md"}}' | prs hook pre-edit
echo $? # 2 if CLAUDE.md is generated, 0 otherwise
# Simulate a post-edit trigger
echo '{"path":".promptscript/project.prs"}' | prs hook post-edit
echo $? # always 0

See Also