# lennney/stop-that-shit architecture

> Architecture diagram of the GitHub repository lennney/stop-that-shit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lennney/stop-that-shit
- Repository: https://github.com/lennney/stop-that-shit

## Overview

Stop That Shit is a task-boundary Guard for AI coding agents. A user gives the host a mode and contract—such as read-only review or an allowed file/dependency scope—then the host adapter translates prompts and tool lifecycle events into control events. The controller checks actions against the contract and delegation state, returns an allow, stop, or observe response, and records runtime outcomes. Host adapters and classifiers cover Claude Code, Codex, Hermes, OpenCode, Pi, and Oh My Pi. The README documents these capabilities; source excerpts are partial, so links for unsampled adapters rely on the SOURCE INDEX.

Main entry points: [`src/controller.cjs`](https://github.com/lennney/stop-that-shit/blob/main/src/controller.cjs) (Event controller), [`src/adapters/codex-tool-classifier.cjs`](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/codex-tool-classifier.cjs) (Tool classifiers), [`src/adapters/claude-hooks.cjs`](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/claude-hooks.cjs) (Claude hooks), [`src/adapters/codex-hooks.cjs`](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/codex-hooks.cjs) (Codex hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host integrations"]
  node_claude["Claude hooks<br/>[claude-hooks.cjs]"]
  node_codex["Codex hooks<br/>[codex-hooks.cjs]"]
  node_hermes["Hermes hooks<br/>[hermes-hooks.cjs]"]
  node_opencode["OpenCode plugin<br/>[stop-that-shit.mjs]"]
  node_opencodehooks["OpenCode hooks<br/>[opencode-hooks.cjs]"]
  node_pi["Pi hooks<br/>[pi-hooks.cjs]"]
  node_omp["Oh My Pi hooks<br/>[omp-hooks.cjs]"]
  node_classifiers["Tool classifiers"]
end

subgraph group_policy["Policy and decisions"]
  node_contracts["Task contracts<br/>[contracts.cjs]"]
  node_decision["Policy decision<br/>[decision.cjs]"]
  node_delegation["Delegation ledger"]
  node_dependencies["Dependency intent"]
end

subgraph group_state["State and runtime records"]
  node_sessionstate[("Session state<br/>[state.cjs]")]
  node_audit["Runtime audit<br/>[runtime-audit.cjs]"]
  node_annotations["Runtime annotations"]
  node_storage[("JSONL storage")]
end

subgraph group_runtime["Guard runtime"]
  node_protocol["Control protocol"]
  node_controller["Event controller<br/>[controller.cjs]"]
end

node_user(("Agent user"))
node_hosts(("Agent hosts"))

node_user -->|"sets task"| node_hosts
node_hosts -->|"emits events"| node_claude
node_hosts -->|"emits events"| node_codex
node_hosts -->|"emits events"| node_hermes
node_hosts -->|"emits events"| node_opencode
node_hosts -->|"emits events"| node_pi
node_hosts -.->|"emits events"| node_omp
node_opencode -->|"routes events"| node_opencodehooks
node_claude -->|"classifies tools"| node_classifiers
node_codex -->|"classifies tools"| node_classifiers
node_hermes -->|"classifies tools"| node_classifiers
node_opencodehooks -->|"classifies tools"| node_classifiers
node_pi -->|"classifies tools"| node_classifiers
node_omp -->|"classifies tools"| node_classifiers
node_classifiers -->|"checks manifests"| node_dependencies
node_claude -->|"submits events"| node_controller
node_codex -->|"submits events"| node_controller
node_hermes -->|"submits events"| node_controller
node_opencodehooks -->|"submits events"| node_controller
node_pi -->|"submits events"| node_controller
node_omp -->|"submits events"| node_controller
node_controller -->|"validates events"| node_protocol
node_controller -->|"parses directives"| node_contracts
node_controller -->|"decides actions"| node_decision
node_controller -->|"tracks agents"| node_delegation
node_decision -->|"inspects budget"| node_delegation
node_controller -->|"reads and writes"| node_sessionstate
node_controller -->|"records decisions"| node_audit
node_controller -->|"records annotations"| node_annotations
node_audit -->|"persists events"| node_storage
node_annotations -->|"persists labels"| node_storage
node_sessionstate -->|"uses defaults"| node_contracts
node_controller -.->|"returns response"| node_hosts

click node_claude "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/claude-hooks.cjs"
click node_codex "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/codex-hooks.cjs"
click node_hermes "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/hermes-hooks.cjs"
click node_opencode "https://github.com/lennney/stop-that-shit/blob/main/opencode/stop-that-shit.mjs"
click node_opencodehooks "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/opencode-hooks.cjs"
click node_pi "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/pi-hooks.cjs"
click node_omp "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/omp-hooks.cjs"
click node_classifiers "https://github.com/lennney/stop-that-shit/blob/main/src/adapters/codex-tool-classifier.cjs"
click node_protocol "https://github.com/lennney/stop-that-shit/blob/main/src/control-protocol.cjs"
click node_controller "https://github.com/lennney/stop-that-shit/blob/main/src/controller.cjs"
click node_contracts "https://github.com/lennney/stop-that-shit/blob/main/src/contracts.cjs"
click node_decision "https://github.com/lennney/stop-that-shit/blob/main/src/decision.cjs"
click node_delegation "https://github.com/lennney/stop-that-shit/blob/main/src/delegation-state.cjs"
click node_dependencies "https://github.com/lennney/stop-that-shit/blob/main/src/manifest-dependencies.cjs"
click node_sessionstate "https://github.com/lennney/stop-that-shit/blob/main/src/state.cjs"
click node_audit "https://github.com/lennney/stop-that-shit/blob/main/src/runtime-audit.cjs"
click node_annotations "https://github.com/lennney/stop-that-shit/blob/main/src/runtime-annotations.cjs"
click node_storage "https://github.com/lennney/stop-that-shit/blob/main/src/runtime-storage.cjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude,node_codex,node_hermes,node_opencode,node_opencodehooks,node_pi,node_omp,node_classifiers,node_user toneBlue
class node_contracts,node_decision,node_delegation,node_dependencies toneAmber
class node_sessionstate,node_audit,node_annotations,node_storage toneMint
class node_protocol,node_controller toneRose
class node_hosts toneIndigo
```

## Components

### Host integrations

- [Claude hooks](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/claude-hooks.cjs): `src/adapters/claude-hooks.cjs`
- [Codex hooks](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/codex-hooks.cjs): `src/adapters/codex-hooks.cjs`
- [Hermes hooks](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/hermes-hooks.cjs): `src/adapters/hermes-hooks.cjs`
- [OpenCode plugin](https://github.com/lennney/stop-that-shit/blob/main/opencode/stop-that-shit.mjs): `opencode/stop-that-shit.mjs`
- [OpenCode hooks](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/opencode-hooks.cjs): `src/adapters/opencode-hooks.cjs`
- [Pi hooks](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/pi-hooks.cjs): `src/adapters/pi-hooks.cjs`
- [Oh My Pi hooks](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/omp-hooks.cjs): `src/adapters/omp-hooks.cjs`
- [Tool classifiers](https://github.com/lennney/stop-that-shit/blob/main/src/adapters/codex-tool-classifier.cjs): `src/adapters/codex-tool-classifier.cjs`

### Policy and decisions

- [Task contracts](https://github.com/lennney/stop-that-shit/blob/main/src/contracts.cjs): `src/contracts.cjs`
- [Policy decision](https://github.com/lennney/stop-that-shit/blob/main/src/decision.cjs): `src/decision.cjs`
- [Delegation ledger](https://github.com/lennney/stop-that-shit/blob/main/src/delegation-state.cjs): `src/delegation-state.cjs`
- [Dependency intent](https://github.com/lennney/stop-that-shit/blob/main/src/manifest-dependencies.cjs): `src/manifest-dependencies.cjs`

### State and runtime records

- [Session state](https://github.com/lennney/stop-that-shit/blob/main/src/state.cjs): `src/state.cjs`
- [Runtime audit](https://github.com/lennney/stop-that-shit/blob/main/src/runtime-audit.cjs): `src/runtime-audit.cjs`
- [Runtime annotations](https://github.com/lennney/stop-that-shit/blob/main/src/runtime-annotations.cjs): `src/runtime-annotations.cjs`
- [JSONL storage](https://github.com/lennney/stop-that-shit/blob/main/src/runtime-storage.cjs): `src/runtime-storage.cjs`

### Guard runtime

- [Control protocol](https://github.com/lennney/stop-that-shit/blob/main/src/control-protocol.cjs): `src/control-protocol.cjs`
- [Event controller](https://github.com/lennney/stop-that-shit/blob/main/src/controller.cjs): `src/controller.cjs`

### Other components

- **Agent user**
- **Agent hosts**

## Connections

- Agent user → Agent hosts: sets task (evidence: `README.md`)
- Agent hosts → Claude hooks: emits events (evidence: `README.md`)
- Agent hosts → Codex hooks: emits events (evidence: `README.md`)
- Agent hosts → Hermes hooks: emits events (evidence: `README.md`)
- Agent hosts → OpenCode plugin: emits events (evidence: `README.md`)
- Agent hosts → Pi hooks: emits events (evidence: `README.md`)
- Agent hosts → Oh My Pi hooks: emits events (evidence: `README.md`)
- OpenCode plugin → OpenCode hooks: routes events (evidence: `opencode/stop-that-shit.mjs`)
- Claude hooks → Tool classifiers: classifies tools (evidence: `src/adapters/claude-hooks.cjs`)
- Codex hooks → Tool classifiers: classifies tools (evidence: `src/adapters/codex-hooks.cjs`)
- Hermes hooks → Tool classifiers: classifies tools (evidence: `src/adapters/hermes-hooks.cjs`)
- OpenCode hooks → Tool classifiers: classifies tools (evidence: `src/adapters/opencode-hooks.cjs`)
- Pi hooks → Tool classifiers: classifies tools (evidence: `src/adapters/pi-hooks.cjs`)
- Oh My Pi hooks → Tool classifiers: classifies tools (evidence: `src/adapters/omp-hooks.cjs`)
- Tool classifiers → Dependency intent: checks manifests (evidence: `src/adapters/codex-tool-classifier.cjs`)
- Claude hooks → Event controller: submits events (evidence: `src/adapters/claude-hooks.cjs`)
- Codex hooks → Event controller: submits events (evidence: `src/adapters/codex-hooks.cjs`)
- Hermes hooks → Event controller: submits events (evidence: `src/adapters/hermes-hooks.cjs`)
- OpenCode hooks → Event controller: submits events (evidence: `src/adapters/opencode-hooks.cjs`)
- Pi hooks → Event controller: submits events (evidence: `src/adapters/pi-hooks.cjs`)
- Oh My Pi hooks → Event controller: submits events (evidence: `src/adapters/omp-hooks.cjs`)
- Event controller → Control protocol: validates events (evidence: `src/controller.cjs`)
- Event controller → Task contracts: parses directives (evidence: `src/controller.cjs`)
- Event controller → Policy decision: decides actions (evidence: `src/controller.cjs`)
- Event controller → Delegation ledger: tracks agents (evidence: `src/controller.cjs`)
- Policy decision → Delegation ledger: inspects budget (evidence: `src/decision.cjs`)
- Event controller → Session state: reads and writes (evidence: `src/controller.cjs`)
- Event controller → Runtime audit: records decisions (evidence: `src/controller.cjs`)
- Event controller → Runtime annotations: records annotations (evidence: `src/controller.cjs`)
- Runtime audit → JSONL storage: persists events (evidence: `src/runtime-audit.cjs`)
- Runtime annotations → JSONL storage: persists labels (evidence: `src/runtime-annotations.cjs`)
- Session state → Task contracts: uses defaults (evidence: `src/state.cjs`)
- Event controller → Agent hosts: returns response
