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:

Action	Triggered by	Purpose
`pre-edit`	Tool is about to write a file	Block writes to PromptScript-generated files
`post-edit`	Tool has written a file	Trigger `prs compile` when a `.prs` file is saved

Actions¶

pre-edit¶

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:

Tool	Stdin field carrying the file path
Claude, Factory, Copilot	`tool_input.file_path`
Cursor	`filePath`
Windsurf	`file_path`
Cline	`file`
Gemini CLI write/edit tools	`arguments.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¶

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¶

Code	Meaning	Effect on tool
0	Pass / success	Tool proceeds normally
1	Internal error	Tool may log a warning; edit is allowed
2	Block	Tool cancels the edit and shows stderr to the user

Note

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

Examples¶

# 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