# karnstack/reins architecture

> Architecture diagram of the GitHub repository karnstack/reins, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karnstack/reins
- Repository: https://github.com/karnstack/reins

## Overview

reins lets a coding agent use CLI commands to inspect and control an already-running Chromium browser: the CLI contacts a local daemon, which bridges requests to the browser extension; the extension enforces site permissions and performs browser actions. The main loop is snapshot, act, and check, with tab management, screenshots, console/network inspection, and raw CDP also documented. The graph includes policy and audit as internal layers, plus the public site. Some extension and daemon wiring is inferred only from README descriptions, so uncertain internal calls are omitted.

Main entry points: [`packages/extension/src/lib/dispatch.ts`](https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/dispatch.ts) (Action dispatch), [`packages/cli/src/commands.ts`](https://github.com/karnstack/reins/blob/main/packages/cli/src/commands.ts) (Command mapping), [`packages/cli/src/daemon.ts`](https://github.com/karnstack/reins/blob/main/packages/cli/src/daemon.ts) (Daemon), [`packages/cli/src/serve.ts`](https://github.com/karnstack/reins/blob/main/packages/cli/src/serve.ts) (Bridge server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_daemon["CLI and daemon"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_commands["Command mapping<br/>[commands.ts]"]
  node_rpc["RPC client<br/>[rpc.ts]"]
  node_daemon["Daemon<br/>[daemon.ts]"]
  node_serve["Bridge server<br/>[serve.ts]"]
  node_audit["Audit log<br/>[audit.ts]"]
end

subgraph group_extension["Browser extension"]
  node_extension_bg["Background worker<br/>[background.ts]"]
  node_bridge_client["Bridge client<br/>[bridge-client.ts]"]
  node_dispatch["Action dispatch<br/>[dispatch.ts]"]
  node_cdp["CDP control<br/>[cdp.ts]"]
  node_tab_handler["Tab operations<br/>[tab-handler.ts]"]
  node_policy["Permission policy<br/>[policy.ts]"]
  node_popup["Policy controls<br/>[popup.ts]"]
end

subgraph group_protocol["Shared protocol"]
  node_protocol_frames["Bridge frames<br/>[bridge.ts]"]
  node_protocol_cdp["Command schemas<br/>[cdp.ts]"]
end

subgraph group_site["Public site"]
  node_web_routes["Site routes<br/>[index.tsx]"]
  node_changelog["Changelog<br/>[route.tsx]"]
  node_web_worker["Site delivery<br/>[index.ts]"]
end

node_agent(("Coding agent"))
node_browser(("Chromium browser"))

node_agent -->|"runs commands"| node_cli
node_cli -->|"maps arguments"| node_commands
node_commands -->|"sends method"| node_rpc
node_rpc -->|"RPC request"| node_daemon
node_daemon -->|"serves bridge"| node_serve
node_serve -->|"bridge messages"| node_extension_bg
node_extension_bg -->|"starts client"| node_bridge_client
node_bridge_client -->|"dispatches method"| node_dispatch
node_dispatch -->|"manages tabs"| node_tab_handler
node_dispatch -->|"controls pages"| node_cdp
node_dispatch -->|"checks access"| node_policy
node_popup -->|"edits policy"| node_policy
node_browser -->|"connects extension"| node_extension_bg
node_tab_handler -->|"uses tabs API"| node_browser
node_cdp -->|"uses debugger"| node_browser
node_daemon -->|"records commands"| node_audit
node_commands -->|"uses schemas"| node_protocol_cdp
node_serve -->|"uses frames"| node_protocol_frames
node_agent -->|"visits site"| node_web_routes
node_web_routes -->|"links releases"| node_changelog
node_web_worker -->|"serves site"| node_web_routes

click node_cli "https://github.com/karnstack/reins/blob/main/packages/cli/src/cli.ts"
click node_commands "https://github.com/karnstack/reins/blob/main/packages/cli/src/commands.ts"
click node_rpc "https://github.com/karnstack/reins/blob/main/packages/cli/src/rpc.ts"
click node_daemon "https://github.com/karnstack/reins/blob/main/packages/cli/src/daemon.ts"
click node_serve "https://github.com/karnstack/reins/blob/main/packages/cli/src/serve.ts"
click node_audit "https://github.com/karnstack/reins/blob/main/packages/cli/src/audit.ts"
click node_extension_bg "https://github.com/karnstack/reins/blob/main/packages/extension/src/background.ts"
click node_bridge_client "https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/bridge-client.ts"
click node_dispatch "https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/dispatch.ts"
click node_cdp "https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/cdp.ts"
click node_tab_handler "https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/tab-handler.ts"
click node_policy "https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/policy.ts"
click node_popup "https://github.com/karnstack/reins/blob/main/packages/extension/src/popup.ts"
click node_protocol_frames "https://github.com/karnstack/reins/blob/main/packages/protocol/src/bridge.ts"
click node_protocol_cdp "https://github.com/karnstack/reins/blob/main/packages/protocol/src/cdp.ts"
click node_web_routes "https://github.com/karnstack/reins/blob/main/packages/web/src/routes/index.tsx"
click node_changelog "https://github.com/karnstack/reins/blob/main/packages/web/src/routes/changelog/route.tsx"
click node_web_worker "https://github.com/karnstack/reins/blob/main/packages/web/worker/index.ts"

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_cli,node_commands,node_rpc,node_daemon,node_serve,node_audit,node_browser toneBlue
class node_extension_bg,node_bridge_client,node_dispatch,node_cdp,node_tab_handler,node_policy,node_popup toneAmber
class node_protocol_frames,node_protocol_cdp toneMint
class node_web_routes,node_changelog,node_web_worker toneRose
class node_agent toneIndigo
```

## Components

### CLI and daemon

- [CLI entry](https://github.com/karnstack/reins/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [Command mapping](https://github.com/karnstack/reins/blob/main/packages/cli/src/commands.ts): `packages/cli/src/commands.ts`
- [RPC client](https://github.com/karnstack/reins/blob/main/packages/cli/src/rpc.ts): `packages/cli/src/rpc.ts`
- [Daemon](https://github.com/karnstack/reins/blob/main/packages/cli/src/daemon.ts): `packages/cli/src/daemon.ts`
- [Bridge server](https://github.com/karnstack/reins/blob/main/packages/cli/src/serve.ts): `packages/cli/src/serve.ts`
- [Audit log](https://github.com/karnstack/reins/blob/main/packages/cli/src/audit.ts): `packages/cli/src/audit.ts`

### Browser extension

- [Background worker](https://github.com/karnstack/reins/blob/main/packages/extension/src/background.ts): `packages/extension/src/background.ts`
- [Bridge client](https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/bridge-client.ts): `packages/extension/src/lib/bridge-client.ts`
- [Action dispatch](https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/dispatch.ts): `packages/extension/src/lib/dispatch.ts`
- [CDP control](https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/cdp.ts): `packages/extension/src/lib/cdp.ts`
- [Tab operations](https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/tab-handler.ts): `packages/extension/src/lib/tab-handler.ts`
- [Permission policy](https://github.com/karnstack/reins/blob/main/packages/extension/src/lib/policy.ts): `packages/extension/src/lib/policy.ts`
- [Policy controls](https://github.com/karnstack/reins/blob/main/packages/extension/src/popup.ts): `packages/extension/src/popup.ts`

### Shared protocol

- [Bridge frames](https://github.com/karnstack/reins/blob/main/packages/protocol/src/bridge.ts): `packages/protocol/src/bridge.ts`
- [Command schemas](https://github.com/karnstack/reins/blob/main/packages/protocol/src/cdp.ts): `packages/protocol/src/cdp.ts`

### Public site

- [Site routes](https://github.com/karnstack/reins/blob/main/packages/web/src/routes/index.tsx): `packages/web/src/routes/index.tsx`
- [Changelog](https://github.com/karnstack/reins/blob/main/packages/web/src/routes/changelog/route.tsx): `packages/web/src/routes/changelog/route.tsx`
- [Site delivery](https://github.com/karnstack/reins/blob/main/packages/web/worker/index.ts): `packages/web/worker/index.ts`

### Other components

- **Coding agent**
- **Chromium browser**

## Connections

- Coding agent → CLI entry: runs commands
- CLI entry → Command mapping: maps arguments
- Command mapping → RPC client: sends method
- RPC client → Daemon: RPC request
- Daemon → Bridge server: serves bridge
- Bridge server → Background worker: bridge messages
- Background worker → Bridge client: starts client
- Bridge client → Action dispatch: dispatches method
- Action dispatch → Tab operations: manages tabs
- Action dispatch → CDP control: controls pages
- Action dispatch → Permission policy: checks access
- Policy controls → Permission policy: edits policy
- Chromium browser → Background worker: connects extension
- Tab operations → Chromium browser: uses tabs API
- CDP control → Chromium browser: uses debugger
- Daemon → Audit log: records commands
- Command mapping → Command schemas: uses schemas
- Bridge server → Bridge frames: uses frames
- Coding agent → Site routes: visits site
- Site routes → Changelog: links releases
- Site delivery → Site routes: serves site