English | 程序中文文档

📖 pi-atelier 实战指南 — 从零教会你使用 pi-atelier 扩展生态，让 AI 编程助手从「会写代码」进化到「会管理项目」

pi-shepherd

源码仓库 | npm

Line count guard and behavior rules extension for pi-coding-agent — rule-driven hooks for tool calls, agent end, and session events.

What It Does

AI agents can go off the rails — generate too much code, forget to commit, ignore coding standards, or produce outputs that are too large. pi-shepherd acts as a guardrail system that monitors and enforces behavioral rules:

• Tool call interception — Inspect and modify tool calls before execution (e.g., enforce line limits)
• Tool result inspection — Check tool results after execution (e.g., flag overly large outputs)
• Agent end hooks — Enforce commit/message rules when the agent finishes
• Session lifecycle — Reset state between sessions

Installation

pi install git:github.com/catlain/pi-shepherd

How It Works

pi-shepherd uses a rules engine that evaluates configurable patterns against tool calls and results:

Tool Call → Rules Engine → Pass/Block/Modify
Tool Result → Rules Engine → Pass/Flag/Truncate
Agent End → Rules Engine → Enforce (commit, summarize, etc.)

Rules Format

Rules are defined in rules.json (or the shepherd section of settings):

[
  {
    "name": "block-grep-for-code-graph",
    "pattern": "^grep\\s+.*\\b[A-Z][a-zA-Z]+\\(",
    "type": "tool_call",
    "action": "block",
    "message": "Use code-graph search_symbols instead of grep for symbol names"
  },
  {
    "name": "warn-large-edit",
    "pattern": "edit",
    "type": "tool_result",
    "maxLines": 500,
    "action": "warn",
    "message": "Edit result is large, consider breaking into smaller changes"
  }
]

Rule Types

| Type | When Evaluated | Actions | |------|---------------|---------| | tool_call | Before tool execution | pass, block, modify | | tool_result | After tool execution | pass, warn, truncate | | agent_end | When agent finishes | enforce |

Built-in Rules

pi-shepherd ships with default rules for common anti-patterns:

• Redirect grep to code-graph for symbol searches
• Warn on overly large tool results
• Enforce git commit on agent end
• Block redundant file reads

Configuration

{
  "shepherd": {
    "enabled": true,
    "rulesDir": "~/.pi/agent/shepherd-rules"
  }
}

Use Cases

| Scenario | Rule Type | Action | |----------|-----------|--------| | Enforce coding standards | tool_call | Block tools that don't follow conventions | | Prevent context bloat | tool_result | Truncate large results | | Git discipline | agent_end | Force commit at session end | | Redirect to better tools | tool_call | Block grep, suggest code-graph | | Custom team rules | All types | Project-specific guardrails |

Best Practices

✅ Recommended

• Start with built-in rules, then add project-specific ones
• Use warn before block — give the agent a chance to learn
• Keep rule patterns simple and specific — regex is evaluated on every tool call
• Put project rules in .pi/shepherd-rules/ for version control

❌ Not Recommended

• Don't use overly broad patterns — they'll match too many calls and slow things down
• Don't create contradictory rules (block + allow the same pattern)
• Don't rely on shepherd for security — it's a guide, not a sandbox

Limitations

| Limitation | Detail | |------------|--------| | Regex only | Patterns use regex, not semantic understanding | | No async rules | Rules must evaluate synchronously | | Agent can bypass | Determined agents can ignore warnings | | No persistence | Rule state resets between sessions |

Architecture

pi-shepherd/
├── index.ts          # Entry: register hooks + rules engine
├── rules-engine.ts   # Pattern matching + action dispatch
├── rules/            # Built-in rule definitions
│   ├── grep.ts       # Redirect grep → code-graph
│   ├── line-limit.ts # Warn on large outputs
│   └── agent-end.ts  # Enforce git commit
├── types.ts          # Rule type definitions
└── package.json

Dependencies:

• @pi-atelier/shared-utils (bundled) — settings management
• @earendil-works/pi-coding-agent — ExtensionAPI (peer)

License

MIT