# ranthonybeckett/tau architecture

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

- Interactive diagram: https://gitdiagram.com/ranthonybeckett/tau
- Repository: https://github.com/ranthonybeckett/tau

## Overview

TAU is a local, voice-first computer and home-lab assistant. Its main workflow takes typed or spoken input through the assistant, consults a configured model and local context, then replies on the display and through speech; requests to change things are mediated by permissioned organs. Separate branches cover user-approved project work, machine/service discovery and monitoring, app connections, and searchable knowledge. The excerpts show key capability implementations, but not the runtime’s complete wiring, so uncertain links are omitted or marked unverified.

Main entry points: [`src/tau/assistant.py`](https://github.com/ranthonybeckett/tau/blob/main/src/tau/assistant.py) (Assistant runtime), [`src/tau/display/server.py`](https://github.com/ranthonybeckett/tau/blob/main/src/tau/display/server.py) (Local display), [`src/tau/organs/builtin.py`](https://github.com/ranthonybeckett/tau/blob/main/src/tau/organs/builtin.py) (Built-in actions), [`src/tau/knowledge/search.py`](https://github.com/ranthonybeckett/tau/blob/main/src/tau/knowledge/search.py) (Knowledge search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Conversation and display"]
  node_assistant["Assistant runtime<br/>[assistant.py]"]
  node_speech["Speech input<br/>[pipeline.py]"]
  node_audio["Audio I/O<br/>[audio.py]"]
  node_display["Local display<br/>[server.py]"]
  node_display_model["Display state<br/>[model.py]"]
  node_brain["Model client<br/>[brainclient.py]"]
  node_engines["Model discovery<br/>[detect.py]"]
end

subgraph group_capabilities["Permissioned capabilities"]
  node_organs["Permission gate<br/>[base.py]"]
  node_builtins["Built-in actions<br/>[builtin.py]"]
  node_senses["System readings<br/>[gpu.py]"]
  node_lanes["Model lanes<br/>[lanes.py]"]
end

subgraph group_work["Project work and connections"]
  node_work["Work jobs<br/>[work.py]"]
  node_apps["Worker discovery<br/>[workers.py]"]
  node_appconnect["App connections<br/>[appconnect.py]"]
  node_registry["Connection registry<br/>[registry.py]"]
end

subgraph group_awareness["Lab awareness"]
  node_discovery["Machine discovery<br/>[collect.py]"]
  node_labmap["Lab map<br/>[labmap.py]"]
  node_sensors["Host sensors<br/>[drives.py]"]
end

subgraph group_foundation["Configuration and knowledge"]
  node_profile["Profile settings<br/>[profile.py]"]
  node_settings["Live settings<br/>[settings.py]"]
  node_knowledge["Knowledge search<br/>[search.py]"]
  node_okf["OKF knowledge<br/>[okf.py]"]
  node_fts[("Full-text index<br/>[fts.py]")]
  node_actionlog["Action receipts<br/>[actionlog.py]"]
  node_paths["Local paths<br/>[paths.py]"]
end

node_user(("User"))

node_user -->|"types and clicks"| node_display
node_user -->|"speaks"| node_speech
node_speech -->|"captures audio"| node_audio
node_assistant -->|"uses hearing"| node_speech
node_display -.->|"submits text"| node_assistant
node_assistant -.->|"requests reply"| node_brain
node_assistant -.->|"speaks reply"| node_audio
node_assistant -.->|"publishes conversation"| node_display_model
node_display -->|"serves state"| node_display_model
node_assistant -.->|"dispatches actions"| node_organs
node_organs -->|"checks and runs"| node_builtins
node_builtins -->|"reads system state"| node_senses
node_builtins -->|"switches model"| node_lanes
node_assistant -.->|"routes work requests"| node_work
node_display -->|"submits jobs"| node_work
node_work -.->|"uses discovered workers"| node_apps
node_display -.->|"connects apps"| node_appconnect
node_apps -->|"registers finder"| node_registry
node_assistant -.->|"requests lab checks"| node_discovery
node_discovery -->|"updates map"| node_labmap
node_builtins -->|"answers lab queries"| node_labmap
node_labmap -->|"stores lab notes"| node_okf
node_builtins -->|"reads host state"| node_sensors
node_assistant -.->|"loads configuration"| node_profile
node_display -->|"views and changes"| node_settings
node_assistant -.->|"searches context"| node_knowledge
node_knowledge -->|"searches folders"| node_okf
node_knowledge -->|"searches index"| node_fts
node_organs -->|"records actions"| node_actionlog
node_profile -->|"resolves profile path"| node_paths
node_knowledge -->|"resolves brain folder"| node_paths
node_assistant -.->|"checks model endpoints"| node_engines
node_engines -->|"finds available models"| node_brain

click node_assistant "https://github.com/ranthonybeckett/tau/blob/main/src/tau/assistant.py"
click node_speech "https://github.com/ranthonybeckett/tau/blob/main/src/tau/ears/pipeline.py"
click node_audio "https://github.com/ranthonybeckett/tau/blob/main/src/tau/audio.py"
click node_display "https://github.com/ranthonybeckett/tau/blob/main/src/tau/display/server.py"
click node_display_model "https://github.com/ranthonybeckett/tau/blob/main/src/tau/display/model.py"
click node_brain "https://github.com/ranthonybeckett/tau/blob/main/src/tau/brainclient.py"
click node_engines "https://github.com/ranthonybeckett/tau/blob/main/src/tau/detect.py"
click node_organs "https://github.com/ranthonybeckett/tau/blob/main/src/tau/organs/base.py"
click node_builtins "https://github.com/ranthonybeckett/tau/blob/main/src/tau/organs/builtin.py"
click node_senses "https://github.com/ranthonybeckett/tau/blob/main/src/tau/senses/gpu.py"
click node_lanes "https://github.com/ranthonybeckett/tau/blob/main/src/tau/lanes.py"
click node_work "https://github.com/ranthonybeckett/tau/blob/main/src/tau/work.py"
click node_apps "https://github.com/ranthonybeckett/tau/blob/main/src/tau/connect/finders/workers.py"
click node_appconnect "https://github.com/ranthonybeckett/tau/blob/main/src/tau/appconnect.py"
click node_registry "https://github.com/ranthonybeckett/tau/blob/main/src/tau/connect/registry.py"
click node_discovery "https://github.com/ranthonybeckett/tau/blob/main/src/tau/discovery/collect.py"
click node_labmap "https://github.com/ranthonybeckett/tau/blob/main/src/tau/discovery/labmap.py"
click node_sensors "https://github.com/ranthonybeckett/tau/blob/main/src/tau/senses/drives.py"
click node_profile "https://github.com/ranthonybeckett/tau/blob/main/src/tau/profile.py"
click node_settings "https://github.com/ranthonybeckett/tau/blob/main/src/tau/settings.py"
click node_knowledge "https://github.com/ranthonybeckett/tau/blob/main/src/tau/knowledge/search.py"
click node_okf "https://github.com/ranthonybeckett/tau/blob/main/src/tau/okf.py"
click node_fts "https://github.com/ranthonybeckett/tau/blob/main/src/tau/knowledge/fts.py"
click node_actionlog "https://github.com/ranthonybeckett/tau/blob/main/src/tau/actionlog.py"
click node_paths "https://github.com/ranthonybeckett/tau/blob/main/src/tau/paths.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_assistant,node_speech,node_audio,node_display,node_display_model,node_brain,node_engines,node_user toneBlue
class node_organs,node_builtins,node_senses,node_lanes toneAmber
class node_work,node_apps,node_appconnect,node_registry toneMint
class node_discovery,node_labmap,node_sensors toneRose
class node_profile,node_settings,node_knowledge,node_okf,node_fts,node_actionlog,node_paths toneIndigo
```

## Components

### Conversation and display

- [Assistant runtime](https://github.com/ranthonybeckett/tau/blob/main/src/tau/assistant.py): `src/tau/assistant.py`
- [Speech input](https://github.com/ranthonybeckett/tau/blob/main/src/tau/ears/pipeline.py): `src/tau/ears/pipeline.py`
- [Audio I/O](https://github.com/ranthonybeckett/tau/blob/main/src/tau/audio.py): `src/tau/audio.py`
- [Local display](https://github.com/ranthonybeckett/tau/blob/main/src/tau/display/server.py): `src/tau/display/server.py`
- [Display state](https://github.com/ranthonybeckett/tau/blob/main/src/tau/display/model.py): `src/tau/display/model.py`
- [Model client](https://github.com/ranthonybeckett/tau/blob/main/src/tau/brainclient.py): `src/tau/brainclient.py`
- [Model discovery](https://github.com/ranthonybeckett/tau/blob/main/src/tau/detect.py): `src/tau/detect.py`

### Permissioned capabilities

- [Permission gate](https://github.com/ranthonybeckett/tau/blob/main/src/tau/organs/base.py): `src/tau/organs/base.py`
- [Built-in actions](https://github.com/ranthonybeckett/tau/blob/main/src/tau/organs/builtin.py): `src/tau/organs/builtin.py`
- [System readings](https://github.com/ranthonybeckett/tau/blob/main/src/tau/senses/gpu.py): `src/tau/senses/gpu.py`
- [Model lanes](https://github.com/ranthonybeckett/tau/blob/main/src/tau/lanes.py): `src/tau/lanes.py`

### Project work and connections

- [Work jobs](https://github.com/ranthonybeckett/tau/blob/main/src/tau/work.py): `src/tau/work.py`
- [Worker discovery](https://github.com/ranthonybeckett/tau/blob/main/src/tau/connect/finders/workers.py): `src/tau/connect/finders/workers.py`
- [App connections](https://github.com/ranthonybeckett/tau/blob/main/src/tau/appconnect.py): `src/tau/appconnect.py`
- [Connection registry](https://github.com/ranthonybeckett/tau/blob/main/src/tau/connect/registry.py): `src/tau/connect/registry.py`

### Lab awareness

- [Machine discovery](https://github.com/ranthonybeckett/tau/blob/main/src/tau/discovery/collect.py): `src/tau/discovery/collect.py`
- [Lab map](https://github.com/ranthonybeckett/tau/blob/main/src/tau/discovery/labmap.py): `src/tau/discovery/labmap.py`
- [Host sensors](https://github.com/ranthonybeckett/tau/blob/main/src/tau/senses/drives.py): `src/tau/senses/drives.py`

### Configuration and knowledge

- [Profile settings](https://github.com/ranthonybeckett/tau/blob/main/src/tau/profile.py): `src/tau/profile.py`
- [Live settings](https://github.com/ranthonybeckett/tau/blob/main/src/tau/settings.py): `src/tau/settings.py`
- [Knowledge search](https://github.com/ranthonybeckett/tau/blob/main/src/tau/knowledge/search.py): `src/tau/knowledge/search.py`
- [OKF knowledge](https://github.com/ranthonybeckett/tau/blob/main/src/tau/okf.py): `src/tau/okf.py`
- [Full-text index](https://github.com/ranthonybeckett/tau/blob/main/src/tau/knowledge/fts.py): `src/tau/knowledge/fts.py`
- [Action receipts](https://github.com/ranthonybeckett/tau/blob/main/src/tau/actionlog.py): `src/tau/actionlog.py`
- [Local paths](https://github.com/ranthonybeckett/tau/blob/main/src/tau/paths.py): `src/tau/paths.py`

### Other components

- **User**

## Connections

- User → Local display: types and clicks (evidence: `src/tau/display/server.py`)
- User → Speech input: speaks (evidence: `README.md`)
- Speech input → Audio I/O: captures audio (evidence: `src/tau/ears/pipeline.py`)
- Assistant runtime → Speech input: uses hearing (evidence: `src/tau/ears/pipeline.py`)
- Local display → Assistant runtime: submits text
- Assistant runtime → Model client: requests reply
- Assistant runtime → Audio I/O: speaks reply
- Assistant runtime → Display state: publishes conversation
- Local display → Display state: serves state (evidence: `src/tau/display/server.py`)
- Assistant runtime → Permission gate: dispatches actions
- Permission gate → Built-in actions: checks and runs (evidence: `src/tau/organs/base.py`)
- Built-in actions → System readings: reads system state (evidence: `src/tau/organs/builtin.py`)
- Built-in actions → Model lanes: switches model (evidence: `src/tau/organs/builtin.py`)
- Assistant runtime → Work jobs: routes work requests
- Local display → Work jobs: submits jobs (evidence: `src/tau/display/server.py`)
- Work jobs → Worker discovery: uses discovered workers
- Local display → App connections: connects apps
- Worker discovery → Connection registry: registers finder (evidence: `src/tau/connect/finders/workers.py`)
- Assistant runtime → Machine discovery: requests lab checks
- Machine discovery → Lab map: updates map (evidence: `src/tau/discovery/collect.py`)
- Built-in actions → Lab map: answers lab queries (evidence: `src/tau/organs/builtin.py`)
- Lab map → OKF knowledge: stores lab notes (evidence: `src/tau/discovery/labmap.py`)
- Built-in actions → Host sensors: reads host state (evidence: `src/tau/organs/builtin.py`)
- Assistant runtime → Profile settings: loads configuration
- Local display → Live settings: views and changes (evidence: `src/tau/display/server.py`)
- Assistant runtime → Knowledge search: searches context
- Knowledge search → OKF knowledge: searches folders (evidence: `src/tau/knowledge/search.py`)
- Knowledge search → Full-text index: searches index (evidence: `src/tau/knowledge/search.py`)
- Permission gate → Action receipts: records actions (evidence: `src/tau/organs/base.py`)
- Profile settings → Local paths: resolves profile path (evidence: `src/tau/profile.py`)
- Knowledge search → Local paths: resolves brain folder (evidence: `src/tau/knowledge/search.py`)
- Assistant runtime → Model discovery: checks model endpoints
- Model discovery → Model client: finds available models (evidence: `src/tau/detect.py`)
