# overview Claude Code agent governance & multi-agent bus

❯pre bus start && pre init ~/your-project --mode supervised

Govern every Claude Code tool call.
Orchestrate agents across machines on one control plane.

pre is a PreToolUse / Stop hook governance layer plus a Master / Node / Driver message bus for orchestrating multiple Claude Code agents — local and remote — under a single CEO-style control plane. Layered decisions (blacklist · whitelist · cache · LLM governor), an observer-only Stop hook, budget caps for freerun, and a zero-framework browser GUI.

Get started → Star on GitHub Browser GUI

❯ git clone https://github.com/pre-ceo/pre.git && bash pre/scripts/install.sh

Python 3.11+ · stdlib-only core MIT license Zero framework GUI Red-green-deficient-friendly palette

# architecture control-plane.txt

Claude Code Agent
  │
  ├─ Tool call ─→ PreToolUse Hook  (0–8s)
  │    1. Blacklist        → ASK/DENY  (rm -rf, sudo, force-push, …)
  │    2. Supply-chain     → Governor, no cache (npm, node -e, ssh, …)
  │    3. Whitelist        → ALLOW    (git, ls, find, read in cwd, …)
  │    4. Cache            → reuse last governor verdict
  │    5. Governor (LLM)   → reads global rules + project rules
  │
  ├─ Stop ─→ Stop Hook  (passive observer)
  │    • record stop log
  │    • process pre/findings/{LEVEL}-{title}.md
  │    • freerun/autonomous: block + tell agent to read pre/next.md
  │    • supervised: passthrough
  │
  └─ Bus access
       Agent ──MCP stdio──▶ pre_mcp subprocess ──loopback HTTP──▶ Master
                            (4 tools: send_message / fetch_inbox /
                                       read_pane / cycle_state)

       Master (HTTP + WS) ◀──▶ Node(s) ◀──▶ Driver(s) ◀──▶ Agent process(es)
       Browser GUI (pre_ui) ◀── HTTP only ──▶ Master

# features 6 capabilities

01 / pretooluse

Layered tool-call governance [hook]

Every tool call flows through a 5-stage decision pipeline: blacklist → supply-chain → whitelist → cache → LLM governor. Dangerous patterns like rm -rf, force-push, curl | sh, supply-chain installs and inline node -e / python -c are surfaced as ASK in supervised mode and DENY in unattended modes.

每次工具调用都过 5 级决策: 黑名单 → 供应链 → 白名单 → 缓存 → LLM governor. 危险模式 (rm -rf / force push / curl | sh / 供应链安装 / 内联 node -e python -c 等) 在 supervised 下抬升为 ASK, 无人值守下自动 DENY.

02 / stop hook

Observer-only stop hook [passive]

Zero-latency Stop: records log, scans pre/findings/{LEVEL}-*.md the agent wrote, routes them through notification channels (severity-aware), and — in unattended modes — blocks once and points the agent at pre/next.md.

Stop 零延迟: 只记录日志, 扫描 agent 写的 pre/findings/{LEVEL}-*.md, 按 severity 投递通知 channel; 无人值守模式下 block 一次, 指引 agent 读 pre/next.md.

03 / multi-agent bus

Master / Node / Driver [bus]

One master (HTTP REST + WebSocket on loopback) talks to one or more nodes — each potentially on a different machine over an SSH tunnel. Each node hosts pluggable drivers that own the actual agent processes; the included driver wraps claude CLI sessions running in tmux.

单 master (loopback HTTP REST + WebSocket) 接一或多 node, node 可经 SSH tunnel 跨机器接入. 每 node 挂可插拔 driver 控制实际 agent 进程, 内置 driver 包装 tmux 中的 claude CLI 会话.

04 / freerun safety

Budget caps & kill switch [safety]

Freerun isn't fire-and-forget: per-day caps on tokens, cost, runtime and LLM calls; event-driven loops only (no polling sleep); an allowlist that absorbs repeated patterns instead of dying on every ASK; and a kill switch that converts every freerun back to half-supervised in one call.

05 / mcp

Agent ↔ bus over MCP [mcp]

Agents reach the bus through a pre_mcp stdio subprocess — it enforces caller-identity prefix checks, cross-node read-pane denial, 60/min sliding-window rate limits, and structured audit logs before forwarding to master. Four tools: send_message · fetch_inbox · read_pane · cycle_state.

Agent 通过 stdio 的 pre_mcp 子进程接总线 — 沿途做 caller-id 前缀校验, 跨 node read_pane 拒绝, 60/min sliding window 限频, 每次调用独立 audit jsonl. 四个工具: send_message · fetch_inbox · read_pane · cycle_state.

06 / findings

Agent-driven notifications [notify]

Agents write pre/findings/CRITICAL-*.md / WARNING-*.md / INFO-*.md when something deserves a human. Stop hook renders a report, tags the git tree (finding/{level}/{ts}), routes through configured channels and moves the file to processed/.

Agent 写 pre/findings/CRITICAL-*.md / WARNING-*.md / INFO-*.md 时, Stop hook 自动生成报告, 打 git tag (finding/{level}/{ts}), 按配置 channel 投递, 然后 move 到 processed/.

# loop-modes modes.tbl

Three loop modes for every degree of autonomy.

Switch a single agent's mode at runtime through the operator API (or the GUI). Modes change what PreToolUse does on dangerous verdicts and whether Stop blocks back to pre/next.md.

通过 operator API (或 GUI) 实时切换单个 agent 的模式. 模式决定 PreToolUse 遇到危险时是 ASK 还是 DENY, 以及 Stop 是否 block 回到 pre/next.md 自驱.

Mode模式	PreToolUse dangerPreToolUse 危险	Stop behaviorStop 行为	Needs pre/next.md需 pre/next.md
[supervised]	ASK user询问用户	passthrough透传	—
[autonomous]	DENY	block + read `pre/next.md`block + 读 `pre/next.md`	yes是
[freerun]	DENY	block + read `pre/next.md`block + 读 `pre/next.md`	yes是

fail-safe matrix

Situation场景	Behavior行为
PreToolUse exceptionPreToolUse 异常	ask
Stop hook exceptionStop hook 异常	passthrough (never blocks永不阻塞)
Governor parse failureGovernor 解析失败	ask
ask under autonomous / freerunautonomous / freerun 下需要 ask	deny (no human无人确认)

# quick-start install.sh — bash

Quick start — three steps, idempotent.

Python 3.11+. The hooks, master, node and scripts are stdlib-only; the optional pre_mcp subpackage needs the mcp SDK.

需 Python 3.11+. hook / master / node / scripts 仅标准库; 可选的 pre_mcp 子包需要 mcp SDK.

1

Clone & bootstrap (creates pre_rule/, clones pre_ui/, installs shims)

克隆与 bootstrap (创建 pre_rule/, clone pre_ui/, 装 shim)

❯ export PRE_DIR=$HOME/your-path/pre
❯ git clone https://github.com/pre-ceo/pre.git "$PRE_DIR"
❯ cd "$PRE_DIR"
❯ bash scripts/install.sh
❯ uv add mcp                       # optional: install MCP SDK

2

Start master + local node (tmux-supervised)

❯ pre bus start

3

Wire your project to the hooks

❯ pre init /path/to/your-project --mode supervised
# creates ./pre/{agent_config.json, rules.md, next.md, findings/}
# merges PreToolUse + Stop hooks into ./.claude/settings.json

After that, every tool call from Claude Code in that project flows through the PreToolUse pipeline. The agent can also call MCP tools mcp__pre__send_message / fetch_inbox / read_pane / cycle_state to interact with the bus.

装好后该项目里 Claude Code 的所有工具调用都走 PreToolUse 决策链; agent 自己也可以调 MCP 工具 mcp__pre__send_message / fetch_inbox / read_pane / cycle_state 跟总线交互.

# findings findings/ — drop, get notified

Agents flag what humans should see.

Drop a markdown file in pre/findings/ and the Stop hook renders a report, tags the git tree, and routes through configured notification channels — severity decides the channel.

agent 把 markdown 丢进 pre/findings/, Stop hook 自动生成报告, 打 git tag, 按严重度走 channel 通知.

[INFO]

❯ echo "details…" > pre/findings/INFO-coverage-up.md

[WARNING]

❯ echo "details…" > pre/findings/WARNING-perf-regression.md

[CRITICAL]

❯ echo "details…" > pre/findings/CRITICAL-something-broke.md

# browser-gui pre_ui — CEO operator console

CEO-style operator console — zero framework.

pre_ui is plain HTML + CSS + vanilla JS, served by a ~150-LOC stdlib reverse-proxy that puts the master and the static assets on the same origin — no CORS, no preflight. Polling-based, strict CSP, Bearer token in sessionStorage only.

pre_ui 是纯 HTML + CSS + vanilla JS, 配一个 ~150 行的 stdlib self-proxy 把 master 和静态资源放在同 origin, 完全免 CORS / preflight. 轮询模式, 严格 CSP, Bearer token 仅放 sessionStorage.

./assets/gui-preview.png Replace this placeholder once the screenshot is generated.
See assets/IMAGE_PROMPTS.md for the GPT prompt. 截图生成后替换此占位.
GPT 提示词见 assets/IMAGE_PROMPTS.md.

# three-repos repo-trio.tbl

The deployment has three pieces.

pre_rule/ stays on your machine and is never pushed upstream by pre; you can git init it and sync it to a private remote yourself for multi-host setup.

pre_rule/ 留在本机, pre 不会替你 push; 多机 sync 自己 git init 后推私库.

Repo仓	Role角色	Source来源	Personal data含个人数据
pre	code + control plane代码与控制平面	github.com/pre-ceo/pre	no否
pre_rule/	your rules + local runtime state用户规则与运行时状态	created by `install.sh` from `pre/templates/pre_rule/`install.sh 从 `templates/pre_rule/` 创建	yes (local; never pushed)是 (本机, 不入上游)
pre_ui	browser GUI浏览器 GUI	github.com/pre-ceo/pre_ui	no否

Govern every Claude Code tool call.
Orchestrate agents across machines on one control plane.

让 Claude Code 的每次工具调用都受控.
编排跨机 agent, 汇入同一个控制平面.

Three loop modes for every degree of autonomy.

三档 loop 模式, 覆盖各级自主度.

Quick start — three steps, idempotent.

快速开始 — 三步, 幂等可重跑.

Agents flag what humans should see.

让 agent 主动标出需要人看的事.

CEO-style operator console — zero framework.

CEO 视角的运维控制台 — 零框架.

The deployment has three pieces.

完整部署有三件套.

Govern every Claude Code tool call. Orchestrate agents across machines on one control plane.

让 Claude Code 的每次工具调用都受控. 编排跨机 agent, 汇入同一个控制平面.

Three loop modes for every degree of autonomy.

三档 loop 模式, 覆盖各级自主度.

Quick start — three steps, idempotent.

快速开始 — 三步, 幂等可重跑.

Agents flag what humans should see.

让 agent 主动标出需要人看的事.

CEO-style operator console — zero framework.

CEO 视角的运维控制台 — 零框架.

The deployment has three pieces.

完整部署有三件套.

Govern every Claude Code tool call.
Orchestrate agents across machines on one control plane.

让 Claude Code 的每次工具调用都受控.
编排跨机 agent, 汇入同一个控制平面.