Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-steering-hooks/llms.txt

Use this file to discover all available pages before exploring further.

pi-steering is a deterministic guardrail layer that sits between your pi agent and the tools it invokes. You declare TypeScript rules that gate bash, write, and edit tool calls; the engine parses every command with a full bash AST, walks per-call tracker state, and returns a block verdict before pi executes.

Quickstart

Install pi-steering and write your first rule in under five minutes.

How It Works

Understand the AST-backed evaluation pipeline and per-ref cwd scoping.

Authoring Rules

Learn the full rule schema — patterns, when clauses, observers, and overrides.

Plugins

Explore built-in plugins and learn to author your own reusable rule packs.

Examples

Copy-paste rule packs for force-push, amend, draft PRs, and more.

API Reference

Full TypeScript API for defineConfig, definePredicate, and testing primitives.

​
Why pi-steering?

Most steering systems match rules against the raw command string — a simple substring check. That means echo 'git push --force' can accidentally trigger a force-push rule, and sh -c 'git push --force' silently bypasses it. pi-steering parses every command through a full bash AST and evaluates rules against extracted command refs — the actual commands that would run, not substrings of the input string.

AST-backed matching

Patterns match real command refs. echo 'git push --force' (basename: echo) never triggers a git rule.

Per-command cwd scoping

cd /tmp && git log evaluates git rules at /tmp, not at the launch directory.

Stateful observers

tool_result events write session entries. Later rules gate on when.happened — no more polling.

Plugin-first composition

Ship predicates, rules, observers, and trackers as versioned npm packages your team shares.

Compile-time safety

defineConfig generics typo-check rule names, plugin names, and event types at tsc time.

Hot config reload

Edit .pi/steering/index.ts and run /reload — no pi restart needed.

​
Get started in three steps

1

Install pi-steering

pi install pi-steering
Requires Node ≥ 22 and the pi coding agent.
2

Create your config

Add .pi/steering/index.ts at your project root:
.pi/steering/index.ts
import { defineConfig } from "pi-steering";

export default defineConfig({
  rules: [
    {
      name: "no-force-push",
      tool: "bash",
      field: "command",
      pattern: /^git\s+push.*--force(?!-)/,
      reason: "Force-push rewrites history. Use --force-with-lease if needed.",
    },
  ],
});
3

Restart pi and test

Restart pi. Any git push --force command is now blocked with your reason message — while echo 'git push --force' correctly passes through.
pi-steering ships with default rules (no-force-push, no-hard-reset, no-rm-rf-slash, no-long-running-commands) and the git plugin (no-main-commit, branch/upstream predicates) active out of the box. Your config is additive — you only need to declare what you want to change.

Build docs developers (and LLMs) love

Get started for freeTalk to us