# ossyrian/tau architecture

> Architecture diagram of the GitHub repository ossyrian/tau, 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/ossyrian/tau
- Repository: https://github.com/ossyrian/tau
- Video tour (about a minute): https://gitdiagram.com/ossyrian/tau/video

## Overview

Tau is a Docker sandbox for the Pi coding agent. The main workflow is: a user starts a container through the host CLI, opens a Pi session, and the agent works in mounted workspaces; results persist in host-mounted state or are handed back through the share dropbox. Tau also provides workspace and session management, agent extensions and skills, subagents, and a gated GitHub shipping path. The README documents capabilities beyond the sampled source, so those links are shown only where the documented ownership is clear.

Main entry points: [`pi-config/agent`](https://github.com/ossyrian/tau/tree/main/pi-config/agent) (Pi session), [`tau`](https://github.com/ossyrian/tau/blob/main/tau) (Tau CLI), [`Dockerfile`](https://github.com/ossyrian/tau/blob/main/Dockerfile) (Docker container), [`pi-config/agent/extensions/subagent-sessions`](https://github.com/ossyrian/tau/tree/main/pi-config/agent/extensions/subagent-sessions) (Subagent sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host orchestration"]
  node_cli["Tau CLI"]
  node_shell["Shell wrappers<br/>[tau.bash]"]
  node_docker["Docker container"]
  node_hoststate[("Persistent host state")]
end

subgraph group_runtime["Agent runtime"]
  node_pi["Pi session"]
  node_runtimecontext["Runtime awareness<br/>[tau-awareness.ts]"]
  node_agenttools["Agent extensions"]
  node_skills["Tau skills"]
  node_subagents["Subagent sessions"]
  node_subagentstate[("Subagent registry<br/>[registry.ts]")]
  node_tmux["tmux sessions<br/>[tmux.ts]"]
end

subgraph group_work["Workspace and delivery"]
  node_workspaces[("Project workspaces")]
  node_workspaceview["Workspace tools<br/>[index.ts]"]
  node_sharetools["Share tools<br/>[index.ts]"]
  node_sharedrop[("Share dropbox")]
  node_todos["Todo planning<br/>[todos.ts]"]
end

subgraph group_shipping["Git shipping"]
  node_gitguard["Git guard<br/>[git-guard.ts]"]
  node_treehouse["Treehouse worktrees"]
  node_nomistakes["No-mistakes gate"]
end

node_user(("User"))
node_github["GitHub"]
node_aws["AWS services"]

node_user -->|"runs commands"| node_cli
node_user -.->|"sources wrapper"| node_shell
node_shell -->|"forwards commands"| node_cli
node_cli -->|"manages container"| node_docker
node_cli -->|"mounts and manages"| node_hoststate
node_docker -->|"runs"| node_pi
node_hoststate -->|"persists mounted data"| node_pi
node_pi -->|"loads extension"| node_runtimecontext
node_runtimecontext -->|"adds prompt context"| node_pi
node_pi -->|"loads extensions"| node_agenttools
node_pi -->|"loads skills"| node_skills
node_pi -->|"registers controls"| node_subagents
node_subagents -->|"creates and manages"| node_tmux
node_subagents -->|"reads and updates"| node_subagentstate
node_cli -->|"manages workspaces"| node_workspaces
node_pi -->|"invokes tools"| node_workspaceview
node_workspaceview -->|"lists and resolves"| node_workspaces
node_pi -->|"plans work"| node_todos
node_pi -->|"invokes tools"| node_sharetools
node_sharetools -->|"copies and lists files"| node_sharedrop
node_sharedrop -->|"bind-mounts to host"| node_hoststate
node_pi -->|"checks bash commands"| node_gitguard
node_pi -.->|"uses worktrees"| node_treehouse
node_pi -->|"drives gated runs"| node_nomistakes
node_nomistakes -->|"pushes and opens PRs"| node_github
node_docker -.->|"injects scoped credentials"| node_aws

click node_cli "https://github.com/ossyrian/tau/blob/main/tau"
click node_shell "https://github.com/ossyrian/tau/blob/main/tau.bash"
click node_docker "https://github.com/ossyrian/tau/blob/main/Dockerfile"
click node_pi "https://github.com/ossyrian/tau/tree/main/pi-config/agent"
click node_runtimecontext "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/tau-awareness.ts"
click node_agenttools "https://github.com/ossyrian/tau/tree/main/pi-config/agent/extensions"
click node_skills "https://github.com/ossyrian/tau/tree/main/pi-config/agent/skills"
click node_subagents "https://github.com/ossyrian/tau/tree/main/pi-config/agent/extensions/subagent-sessions"
click node_subagentstate "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/subagent-sessions/registry.ts"
click node_tmux "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/subagent-sessions/tmux.ts"
click node_workspaces "https://github.com/ossyrian/tau/tree/main/workspace"
click node_workspaceview "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/workspace-tools/index.ts"
click node_sharetools "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/share-tools/index.ts"
click node_todos "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/todos.ts"
click node_gitguard "https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/git-guard.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_shell,node_docker,node_hoststate,node_user toneBlue
class node_pi,node_runtimecontext,node_agenttools,node_skills,node_subagents,node_subagentstate,node_tmux toneAmber
class node_workspaces,node_workspaceview,node_sharetools,node_sharedrop,node_todos toneMint
class node_gitguard,node_treehouse,node_nomistakes toneRose
class node_github,node_aws toneIndigo
```

## Components

### Host orchestration

- [Tau CLI](https://github.com/ossyrian/tau/blob/main/tau): `tau`
- [Shell wrappers](https://github.com/ossyrian/tau/blob/main/tau.bash): `tau.bash`
- [Docker container](https://github.com/ossyrian/tau/blob/main/Dockerfile): `Dockerfile`
- **Persistent host state**

### Agent runtime

- [Pi session](https://github.com/ossyrian/tau/tree/main/pi-config/agent): `pi-config/agent`
- [Runtime awareness](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/tau-awareness.ts): `pi-config/agent/extensions/tau-awareness.ts`
- [Agent extensions](https://github.com/ossyrian/tau/tree/main/pi-config/agent/extensions): `pi-config/agent/extensions`
- [Tau skills](https://github.com/ossyrian/tau/tree/main/pi-config/agent/skills): `pi-config/agent/skills`
- [Subagent sessions](https://github.com/ossyrian/tau/tree/main/pi-config/agent/extensions/subagent-sessions): `pi-config/agent/extensions/subagent-sessions`
- [Subagent registry](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/subagent-sessions/registry.ts): `pi-config/agent/extensions/subagent-sessions/registry.ts`
- [tmux sessions](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/subagent-sessions/tmux.ts): `pi-config/agent/extensions/subagent-sessions/tmux.ts`

### Workspace and delivery

- [Project workspaces](https://github.com/ossyrian/tau/tree/main/workspace): `workspace`
- [Workspace tools](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/workspace-tools/index.ts): `pi-config/agent/extensions/workspace-tools/index.ts`
- [Share tools](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/share-tools/index.ts): `pi-config/agent/extensions/share-tools/index.ts`
- **Share dropbox**
- [Todo planning](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/todos.ts): `pi-config/agent/extensions/todos.ts`

### Git shipping

- [Git guard](https://github.com/ossyrian/tau/blob/main/pi-config/agent/extensions/git-guard.ts): `pi-config/agent/extensions/git-guard.ts`
- **Treehouse worktrees**
- **No-mistakes gate**

### Other components

- **User**
- **GitHub**
- **AWS services**

## Connections

- User → Tau CLI: runs commands
- User → Shell wrappers: sources wrapper
- Shell wrappers → Tau CLI: forwards commands
- Tau CLI → Docker container: manages container
- Tau CLI → Persistent host state: mounts and manages
- Docker container → Pi session: runs
- Persistent host state → Pi session: persists mounted data
- Pi session → Runtime awareness: loads extension
- Runtime awareness → Pi session: adds prompt context
- Pi session → Agent extensions: loads extensions
- Pi session → Tau skills: loads skills
- Pi session → Subagent sessions: registers controls
- Subagent sessions → tmux sessions: creates and manages
- Subagent sessions → Subagent registry: reads and updates
- Tau CLI → Project workspaces: manages workspaces
- Pi session → Workspace tools: invokes tools
- Workspace tools → Project workspaces: lists and resolves
- Pi session → Todo planning: plans work
- Pi session → Share tools: invokes tools
- Share tools → Share dropbox: copies and lists files
- Share dropbox → Persistent host state: bind-mounts to host
- Pi session → Git guard: checks bash commands
- Pi session → Treehouse worktrees: uses worktrees
- Pi session → No-mistakes gate: drives gated runs
- No-mistakes gate → GitHub: pushes and opens PRs
- Docker container → AWS services: injects scoped credentials