---
## β¨ Features
- **π Two-agent observer system** β Builder agent runs normally while a Verifier subagent observes and injects corrective feedback after each turn
- **π‘οΈ Read-only policy** β Automatically blocks `write`, `edit`, and `bash` tool calls when verification is active
- **π Feedback loop with cooldown** β Prevents feedback storms with configurable cooldown and escalation pause after 3 consecutive corrections
- **π‘ TCP loopback IPC** β Bidirectional JSONL communication between builder and verifier over 127.0.0.1
- **π Live status UI** β Footer status, ASCII widget, and spinner indicator showing verifier state
- **β‘ On-demand verification** β `verifier_prompt` tool for requesting immediate attention from the verifier
## π¦ Installation
**From npm:**
```bash
pi install npm:@the-forge-flow/pi-verifier
```
**From GitHub (tracks `main`):**
```bash
pi install git:github.com/MonsieurBarti/pi-verifier
```
Then reload PI with `/reload`.
## π Usage
```bash
/verify on # Enable verifier mode
/verify off # Disable verifier mode
/verify resume # Resume after escalation pause
```
When active, the verifier subagent observes every builder turn and injects feedback as a follow-up message if it detects issues. Say "LGTM" when the code is correct.
### On-demand verification
The builder can also request immediate verification via the `verifier_prompt` tool:
```
Use the verifier_prompt tool to double-check my recent refactor (reason: "check my refactor")
```
## ποΈ Architecture
```
βββββββββββββββ TCP loopback βββββββββββββββ
β Builder β ββββββ JSONL over ββββββΊ β Verifier β
β (pi) β 127.0.0.1:9876 β (subagent) β
βββββββββββββββ βββββββββββββββ
β β
βΌ βΌ
Session events Read-only
(turn_end, input) analysis
β β
βΌ βΌ
Feedback injection ββββββββββββββββ Correction notes
(followUp message)
```
### Components
| Module | Responsibility |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| `index.ts` | Extension entry point β wires all modules, registers commands/tools, manages lifecycle |
| `toggle-command.ts` | `/verify on\|off\|resume` command with state machine |
| `socket-server.ts` | TCP loopback server β broadcasts session events, buffers until verifier connects |
| `session-capture.ts` | Builder-side hooks (`session_start`, `turn_end`, `input`) β captures and forwards events |
| `verifier-spawn.ts` | Spawns verifier subagent process, monitors lifecycle |
| `verifier.ts` | Verifier daemon β TCP client, read-only `AgentSession`, analysis loop |
| `feedback-loop.ts` | Receives verifier feedback, injects as follow-up message with cooldown/loop detection |
| `escalation.ts` | Loop counter β pauses after 3 consecutive feedback injections, supports `/verify resume` |
| `read-only-policy.ts` | Builder-side tool interceptor β blocks `write`/`edit`/`bash` when verification is active |
| `verifier-prompt-tool.ts` | `verifier_prompt` custom tool for on-demand verification |
| `status-ui.ts` | Footer status, ASCII widget, spinner indicator |
| `prompt-loader.ts` | Markdown prompt loader with `{{variable}}` substitution |
| `types.ts` | Shared TypeScript types, SDK re-exports, and runtime type guards |
### IPC Protocol
Builder and verifier communicate over **TCP loopback** (127.0.0.1) using **JSON Lines**:
```json
{"timestamp": 1715523456789, "data": {"type": "turn_end", "event": {...}}}
{"timestamp": 1715523456790, "data": {"type": "feedback", "content": "Looks good to me"}}
```
| Type | Direction | Description |
| --------------- | ------------------ | ------------------------- |
| `session_start` | Builder β Verifier | Session initialized |
| `turn_end` | Builder β Verifier | Builder completed a turn |
| `input` | Builder β Verifier | User input received |
| `feedback` | Verifier β Builder | Analysis result to inject |
## βοΈ Configuration
| Setting | Default | Description |
| ------------------------- | --------- | --------------------------------------------- |
| Port | `9876` | TCP loopback port for builderβverifier IPC |
| Feedback cooldown | `5000ms` | Minimum ms between feedback injections |
| Max verification attempts | `3` | Consecutive feedbacks before escalation pause |
| Buffer TTL | `30000ms` | How long to retain buffered messages |
## π§ͺ Development
```bash
pnpm install
pnpm test # Run unit tests
pnpm test:coverage # Run with coverage report
pnpm run lint
pnpm run typecheck
pnpm run format:check
pnpm run build
```
## πͺΆ Status
v0.0.1
PI extension shipped with 13 modules, 16 test files (81 tests), and full test coverage above thresholds. The verifier subagent runs as an isolated Node.js process with read-only tool access, analyzing every builder turn via the PI coding agent SDK.
## π€ Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit with conventional commits (`git commit -m "feat: add something"`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request
## π License
MIT Β© [MonsieurBarti](https://github.com/MonsieurBarti)
---
