pi.hitl Documentation¶

pi.hitl is a CEL-based permission sandbox for the pi coding agent.

New here?¶

If you're setting up pi.hitl for the first time, start with the Getting Started tutorial. It walks you through installation, creating your first .pi/permissions.yaml, and testing the sandbox step by step — no prior knowledge required.

Tutorials¶

Tutorials are learning-oriented step-by-step guides for first-time users.

Getting Started — Step-by-step first-time setup

How-to Guides¶

How-to guides are problem-oriented recipes for specific situations.

Allow harmless tools without approval — Blanket-allow safe tools so they don't trigger confirmation dialogs
Handle MCP-CLI calls through bash — Write rules for mcp-cli running through the bash tool

Reference¶

Reference docs are information-oriented descriptions of the system's nuts and bolts.

YAML configuration schema — Top-level keys, rule objects, config locations, merge semantics, and nested rules
CEL variables and functions — Context variables (tool, args, cwd, path, command) and custom CEL functions
/permissions CLI commands — Command descriptions, arguments, side effects, and state persistence details

Explanation¶

Explanation docs are understanding-oriented discussions of design rationale and architecture.

Architecture and design rationale — How pi.hitl works and why it was designed this way