# aaronyaml/tabbie architecture

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

- Interactive diagram: https://gitdiagram.com/aaronyaml/tabbie
- Repository: https://github.com/aaronyaml/tabbie

## Overview

Tabbie is a local command centre for coding agents, integrated with the Hermes hub and WebUI. The main flow routes a user request through the command-centre plugin: chat stays with the hub, scoped jobs go to Claude Code, and larger or ambiguous work can be planned with Codex before execution. Separate branches support project organization, attachment handling, usage and limits, work tracking, and motion creation. Traces feed the Dreamer’s evidence-backed memory proposals. Relationships reflect the README and source-index references; some unsampled subsystem links are therefore omitted.

Main entry points: [`plugin/command-centre/__init__.py`](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/__init__.py) (Request handler), [`webui-extension/routes.js`](https://github.com/aaronyaml/tabbie/blob/main/webui-extension/routes.js) (WebUI extension), [`plugin/command-centre/providers.py`](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/providers.py) (Worker provider), [`plugin/command-centre/router.py`](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/router.py) (Request classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request routing"]
  node_entry["Request handler<br/>[__init__.py]"]
  node_router["Request classifier<br/>[router.py]"]
  node_attachments["Attachment ingestion<br/>[attachments.py]"]
end

subgraph group_workers["Agent execution"]
  node_planner["Planner provider<br/>[providers.py]"]
  node_executor["Worker provider<br/>[providers.py]"]
  node_claude["Claude Code"]
  node_codex["Codex"]
  node_hub["Hermes hub"]
end

subgraph group_memory["Learning and memory"]
  node_traces["Session traces<br/>[trace.py]"]
  node_dreamer["Dreamer<br/>[dreamer.py]"]
  node_proposals["Memory proposals<br/>[proposals.py]"]
  node_memory_store[("Versioned memory<br/>[store.py]")]
  node_retrieval["Memory retrieval<br/>[retrieve.py]"]
end

subgraph group_workspace["Projects and workspace"]
  node_projects[("Project registry<br/>[projects.py]")]
end

subgraph group_webui["WebUI capabilities"]
  node_webapp["Web app"]
  node_extension["WebUI extension<br/>[routes.js]"]
  node_insights["Usage insights<br/>[usage_insights.py]"]
  node_limits["Usage limits<br/>[__init__.py]"]
  node_workboard["Workboard<br/>[__init__.py]"]
  node_motion["Motion studio<br/>[motion.py]"]
end

node_user(("User"))

node_user -->|"sends request"| node_webapp
node_webapp -->|"uses extension"| node_extension
node_extension -->|"passes messages"| node_entry
node_entry -->|"classifies request"| node_router
node_entry -->|"ingests files"| node_attachments
node_entry -->|"dispatches planning"| node_planner
node_entry -->|"dispatches execution"| node_executor
node_entry -->|"keeps chat"| node_hub
node_router -->|"selects route"| node_planner
node_router -->|"selects route"| node_executor
node_planner -->|"plans work"| node_codex
node_planner -->|"approved plan"| node_executor
node_executor -->|"runs task"| node_claude
node_executor -->|"runs task"| node_codex
node_entry -->|"records run"| node_traces
node_traces -->|"supplies evidence"| node_dreamer
node_dreamer -->|"suggests lessons"| node_proposals
node_proposals -->|"persists approved changes"| node_memory_store
node_entry -->|"gets worker context"| node_retrieval
node_retrieval -->|"searches memories"| node_memory_store
node_entry -->|"uses project context"| node_projects
node_extension -->|"shows usage"| node_insights
node_extension -->|"shows limits"| node_limits
node_extension -->|"shows workboard"| node_workboard
node_extension -->|"offers motion tools"| node_motion

click node_extension "https://github.com/aaronyaml/tabbie/blob/main/webui-extension/routes.js"
click node_entry "https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/__init__.py"
click node_router "https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/router.py"
click node_attachments "https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/attachments.py"
click node_planner "https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/providers.py"
click node_executor "https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/providers.py"
click node_traces "https://github.com/aaronyaml/tabbie/blob/main/hmem/trace.py"
click node_dreamer "https://github.com/aaronyaml/tabbie/blob/main/hmem/dreamer.py"
click node_proposals "https://github.com/aaronyaml/tabbie/blob/main/hmem/proposals.py"
click node_memory_store "https://github.com/aaronyaml/tabbie/blob/main/hmem/store.py"
click node_retrieval "https://github.com/aaronyaml/tabbie/blob/main/hmem/retrieve.py"
click node_projects "https://github.com/aaronyaml/tabbie/blob/main/hmem/projects.py"
click node_insights "https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/usage_insights.py"
click node_limits "https://github.com/aaronyaml/tabbie/blob/main/plugin/limits/__init__.py"
click node_workboard "https://github.com/aaronyaml/tabbie/blob/main/plugin/workboard/__init__.py"
click node_motion "https://github.com/aaronyaml/tabbie/blob/main/hmem/motion.py"

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_entry,node_router,node_attachments,node_user toneBlue
class node_planner,node_executor,node_claude,node_codex,node_hub toneAmber
class node_traces,node_dreamer,node_proposals,node_memory_store,node_retrieval toneMint
class node_projects toneRose
class node_webapp,node_extension,node_insights,node_limits,node_workboard,node_motion toneIndigo
```

## Components

### Request routing

- [Request handler](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/__init__.py): `plugin/command-centre/__init__.py`
- [Request classifier](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/router.py): `plugin/command-centre/router.py`
- [Attachment ingestion](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/attachments.py): `plugin/command-centre/attachments.py`

### Agent execution

- [Planner provider](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/providers.py): `plugin/command-centre/providers.py`
- [Worker provider](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/providers.py): `plugin/command-centre/providers.py`
- **Claude Code**
- **Codex**
- **Hermes hub**

### Learning and memory

- [Session traces](https://github.com/aaronyaml/tabbie/blob/main/hmem/trace.py): `hmem/trace.py`
- [Dreamer](https://github.com/aaronyaml/tabbie/blob/main/hmem/dreamer.py): `hmem/dreamer.py`
- [Memory proposals](https://github.com/aaronyaml/tabbie/blob/main/hmem/proposals.py): `hmem/proposals.py`
- [Versioned memory](https://github.com/aaronyaml/tabbie/blob/main/hmem/store.py): `hmem/store.py`
- [Memory retrieval](https://github.com/aaronyaml/tabbie/blob/main/hmem/retrieve.py): `hmem/retrieve.py`

### Projects and workspace

- [Project registry](https://github.com/aaronyaml/tabbie/blob/main/hmem/projects.py): `hmem/projects.py`

### WebUI capabilities

- **Web app**
- [WebUI extension](https://github.com/aaronyaml/tabbie/blob/main/webui-extension/routes.js): `webui-extension/routes.js`
- [Usage insights](https://github.com/aaronyaml/tabbie/blob/main/plugin/command-centre/usage_insights.py): `plugin/command-centre/usage_insights.py`
- [Usage limits](https://github.com/aaronyaml/tabbie/blob/main/plugin/limits/__init__.py): `plugin/limits/__init__.py`
- [Workboard](https://github.com/aaronyaml/tabbie/blob/main/plugin/workboard/__init__.py): `plugin/workboard/__init__.py`
- [Motion studio](https://github.com/aaronyaml/tabbie/blob/main/hmem/motion.py): `hmem/motion.py`

### Other components

- **User**

## Connections

- User → Web app: sends request (evidence: `README.md`)
- Web app → WebUI extension: uses extension (evidence: `README.md`)
- WebUI extension → Request handler: passes messages (evidence: `README.md`)
- Request handler → Request classifier: classifies request (evidence: `plugin/command-centre/__init__.py`)
- Request handler → Attachment ingestion: ingests files (evidence: `plugin/command-centre/__init__.py`)
- Request handler → Planner provider: dispatches planning (evidence: `plugin/command-centre/__init__.py`)
- Request handler → Worker provider: dispatches execution (evidence: `plugin/command-centre/__init__.py`)
- Request handler → Hermes hub: keeps chat (evidence: `README.md`)
- Request classifier → Planner provider: selects route (evidence: `README.md`)
- Request classifier → Worker provider: selects route (evidence: `README.md`)
- Planner provider → Codex: plans work (evidence: `README.md`)
- Planner provider → Worker provider: approved plan (evidence: `README.md`)
- Worker provider → Claude Code: runs task (evidence: `README.md`)
- Worker provider → Codex: runs task (evidence: `README.md`)
- Request handler → Session traces: records run (evidence: `README.md`)
- Session traces → Dreamer: supplies evidence (evidence: `README.md`)
- Dreamer → Memory proposals: suggests lessons (evidence: `hmem/dreamer.py`)
- Memory proposals → Versioned memory: persists approved changes (evidence: `hmem/proposals.py`)
- Request handler → Memory retrieval: gets worker context (evidence: `README.md`)
- Memory retrieval → Versioned memory: searches memories (evidence: `hmem/retrieve.py`)
- Request handler → Project registry: uses project context (evidence: `plugin/command-centre/__init__.py`)
- WebUI extension → Usage insights: shows usage (evidence: `README.md`)
- WebUI extension → Usage limits: shows limits (evidence: `README.md`)
- WebUI extension → Workboard: shows workboard (evidence: `README.md`)
- WebUI extension → Motion studio: offers motion tools (evidence: `README.md`)