# mrcoolbay/trame architecture

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

- Interactive diagram: https://gitdiagram.com/mrcoolbay/trame
- Repository: https://github.com/mrcoolbay/trame

## Overview

Trame coordinates coding agents sharing one project directory: agent file reads and writes are observed, writes are admitted through a per-project registry, and stale-read verdicts can become notices before the agent’s prompt. Out-of-band filesystem changes are noticed after the fact. The README documents an observing daemon, append-only journal, shared display state, and TUI/GUI interfaces; VCS support and multi-project supervision are not yet implemented. Several subsystem links below rely on README descriptions because their wiring source was not sampled.

Main entry points: [`crates/trame-daemon/src/session.rs`](https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/session.rs) (Project daemon), [`crates/trame-registry/src/actor.rs`](https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/actor.rs) (Registry actor), [`crates/trame-view/src/state.rs`](https://github.com/mrcoolbay/trame/blob/main/crates/trame-view/src/state.rs) (Display state), [`crates/trame-agent/src/acp.rs`](https://github.com/mrcoolbay/trame/blob/main/crates/trame-agent/src/acp.rs) (ACP adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Coordination core"]
  node_project_domain["Project and session model<br/>[session.rs]"]
  node_prompt["Prompt and notices<br/>[prompt.rs]"]
  node_verdict["Admission verdicts<br/>[verdict.rs]"]
  node_registry_actor["Registry actor<br/>[actor.rs]"]
  node_registry_state["Admission state<br/>[state.rs]"]
  node_registry_messages["Registry messages<br/>[msg.rs]"]
end

subgraph group_runtime["Project runtime"]
  node_daemon["Project daemon<br/>[session.rs]"]
  node_watcher["Filesystem watcher<br/>[watcher.rs]"]
  node_observe["Observation handling<br/>[observe.rs]"]
end

subgraph group_persistence["Audit storage"]
  node_journal_actor["Journal actor<br/>[actor.rs]"]
  node_journal_store[("SQLite journal<br/>[store.rs]")]
end

subgraph group_interfaces["User interfaces"]
  node_view_state["Display state<br/>[state.rs]"]
  node_tui["Terminal interface<br/>[ui.rs]"]
  node_gui["Desktop interface<br/>[view.rs]"]
end

subgraph group_integrations["External integrations"]
  node_acp["ACP adapter<br/>[acp.rs]"]
  node_agent_events["Agent events<br/>[event.rs]"]
  node_hook["CLI hook bridge<br/>[bash.rs]"]
  node_vcs["VCS boundary<br/>[lib.rs]"]
end

node_user(("User"))
node_agent(("Coding agent"))
node_shell(("Shell / tools"))
node_gitbutler["GitButler CLI"]

node_agent -->|"requests file tools"| node_acp
node_acp -->|"emits requests"| node_agent_events
node_acp -->|"routes writes"| node_registry_actor
node_registry_actor -->|"dispatches messages"| node_registry_state
node_registry_actor -->|"handles messages"| node_registry_messages
node_registry_state -->|"produces verdicts"| node_verdict
node_registry_actor -->|"journals activity"| node_journal_actor
node_journal_actor -->|"writes records"| node_journal_store
node_watcher -->|"reports changes"| node_observe
node_observe -->|"reports external writes"| node_registry_actor
node_daemon -->|"starts watcher"| node_watcher
node_daemon -->|"places notices"| node_prompt
node_registry_actor -.->|"returns verdicts"| node_daemon
node_shell -->|"changes noticed after"| node_watcher
node_user -->|"invokes hooks"| node_hook
node_hook -->|"uses project socket"| node_daemon
node_daemon -->|"supplies observations"| node_view_state
node_view_state -->|"feeds display"| node_tui
node_view_state -->|"feeds display"| node_gui
node_user -->|"observes coordination"| node_tui
node_user -->|"observes coordination"| node_gui
node_daemon -->|"tracks project sessions"| node_project_domain
node_daemon -.->|"VCS integration planned"| node_vcs
node_gitbutler -.->|"invoked externally"| node_vcs

click node_acp "https://github.com/mrcoolbay/trame/blob/main/crates/trame-agent/src/acp.rs"
click node_agent_events "https://github.com/mrcoolbay/trame/blob/main/crates/trame-agent/src/event.rs"
click node_project_domain "https://github.com/mrcoolbay/trame/blob/main/crates/trame-core/src/session.rs"
click node_prompt "https://github.com/mrcoolbay/trame/blob/main/crates/trame-core/src/prompt.rs"
click node_verdict "https://github.com/mrcoolbay/trame/blob/main/crates/trame-core/src/verdict.rs"
click node_registry_actor "https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/actor.rs"
click node_registry_state "https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/state.rs"
click node_registry_messages "https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/msg.rs"
click node_daemon "https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/session.rs"
click node_watcher "https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/watcher.rs"
click node_observe "https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/observe.rs"
click node_hook "https://github.com/mrcoolbay/trame/blob/main/crates/trame-hook/src/bash.rs"
click node_journal_actor "https://github.com/mrcoolbay/trame/blob/main/crates/trame-journal/src/actor.rs"
click node_journal_store "https://github.com/mrcoolbay/trame/blob/main/crates/trame-journal/src/store.rs"
click node_view_state "https://github.com/mrcoolbay/trame/blob/main/crates/trame-view/src/state.rs"
click node_tui "https://github.com/mrcoolbay/trame/blob/main/apps/trame-tui/src/ui.rs"
click node_gui "https://github.com/mrcoolbay/trame/blob/main/apps/trame-gui/src/view.rs"
click node_vcs "https://github.com/mrcoolbay/trame/blob/main/crates/trame-vcs/src/lib.rs"

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_project_domain,node_prompt,node_verdict,node_registry_actor,node_registry_state,node_registry_messages,node_user toneBlue
class node_daemon,node_watcher,node_observe toneAmber
class node_journal_actor,node_journal_store toneMint
class node_view_state,node_tui,node_gui toneRose
class node_acp,node_agent_events,node_hook,node_vcs,node_agent,node_shell,node_gitbutler toneIndigo
```

## Components

### Coordination core

- [Project and session model](https://github.com/mrcoolbay/trame/blob/main/crates/trame-core/src/session.rs): `crates/trame-core/src/session.rs`
- [Prompt and notices](https://github.com/mrcoolbay/trame/blob/main/crates/trame-core/src/prompt.rs): `crates/trame-core/src/prompt.rs`
- [Admission verdicts](https://github.com/mrcoolbay/trame/blob/main/crates/trame-core/src/verdict.rs): `crates/trame-core/src/verdict.rs`
- [Registry actor](https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/actor.rs): `crates/trame-registry/src/actor.rs`
- [Admission state](https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/state.rs): `crates/trame-registry/src/state.rs`
- [Registry messages](https://github.com/mrcoolbay/trame/blob/main/crates/trame-registry/src/msg.rs): `crates/trame-registry/src/msg.rs`

### Project runtime

- [Project daemon](https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/session.rs): `crates/trame-daemon/src/session.rs`
- [Filesystem watcher](https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/watcher.rs): `crates/trame-daemon/src/watcher.rs`
- [Observation handling](https://github.com/mrcoolbay/trame/blob/main/crates/trame-daemon/src/observe.rs): `crates/trame-daemon/src/observe.rs`

### Audit storage

- [Journal actor](https://github.com/mrcoolbay/trame/blob/main/crates/trame-journal/src/actor.rs): `crates/trame-journal/src/actor.rs`
- [SQLite journal](https://github.com/mrcoolbay/trame/blob/main/crates/trame-journal/src/store.rs): `crates/trame-journal/src/store.rs`

### User interfaces

- [Display state](https://github.com/mrcoolbay/trame/blob/main/crates/trame-view/src/state.rs): `crates/trame-view/src/state.rs`
- [Terminal interface](https://github.com/mrcoolbay/trame/blob/main/apps/trame-tui/src/ui.rs): `apps/trame-tui/src/ui.rs`
- [Desktop interface](https://github.com/mrcoolbay/trame/blob/main/apps/trame-gui/src/view.rs): `apps/trame-gui/src/view.rs`

### External integrations

- [ACP adapter](https://github.com/mrcoolbay/trame/blob/main/crates/trame-agent/src/acp.rs): `crates/trame-agent/src/acp.rs`
- [Agent events](https://github.com/mrcoolbay/trame/blob/main/crates/trame-agent/src/event.rs): `crates/trame-agent/src/event.rs`
- [CLI hook bridge](https://github.com/mrcoolbay/trame/blob/main/crates/trame-hook/src/bash.rs): `crates/trame-hook/src/bash.rs`
- [VCS boundary](https://github.com/mrcoolbay/trame/blob/main/crates/trame-vcs/src/lib.rs): `crates/trame-vcs/src/lib.rs`

### Other components

- **User**
- **Coding agent**
- **Shell / tools**
- **GitButler CLI**

## Connections

- Coding agent → ACP adapter: requests file tools (evidence: `README.md`)
- ACP adapter → Agent events: emits requests (evidence: `crates/trame-agent/src/acp.rs`)
- ACP adapter → Registry actor: routes writes (evidence: `README.md`)
- Registry actor → Admission state: dispatches messages (evidence: `crates/trame-registry/src/actor.rs`)
- Registry actor → Registry messages: handles messages (evidence: `crates/trame-registry/src/actor.rs`)
- Admission state → Admission verdicts: produces verdicts (evidence: `README.md`)
- Registry actor → Journal actor: journals activity (evidence: `README.md`)
- Journal actor → SQLite journal: writes records (evidence: `crates/trame-journal/src/actor.rs`)
- Filesystem watcher → Observation handling: reports changes (evidence: `README.md`)
- Observation handling → Registry actor: reports external writes (evidence: `README.md`)
- Project daemon → Filesystem watcher: starts watcher
- Project daemon → Prompt and notices: places notices (evidence: `README.md`)
- Registry actor → Project daemon: returns verdicts
- Shell / tools → Filesystem watcher: changes noticed after (evidence: `README.md`)
- User → CLI hook bridge: invokes hooks (evidence: `README.md`)
- CLI hook bridge → Project daemon: uses project socket (evidence: `README.md`)
- Project daemon → Display state: supplies observations (evidence: `README.md`)
- Display state → Terminal interface: feeds display (evidence: `README.md`)
- Display state → Desktop interface: feeds display (evidence: `README.md`)
- User → Terminal interface: observes coordination (evidence: `README.md`)
- User → Desktop interface: observes coordination (evidence: `README.md`)
- Project daemon → Project and session model: tracks project sessions (evidence: `README.md`)
- Project daemon → VCS boundary: VCS integration planned (evidence: `README.md`)
- GitButler CLI → VCS boundary: invoked externally (evidence: `README.md`)
