# h4fizwasabie/theoses2 architecture

> Architecture diagram of the GitHub repository h4fizwasabie/theoses2, 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/h4fizwasabie/theoses2
- Repository: https://github.com/h4fizwasabie/theoses2

## Overview

Theoses2 is a self-hosted personal assistant and coding agent: users send work from the terminal, Telegram, or a private dashboard; the shared coding-agent runtime maintains bounded session context, invokes tools and models, and returns results through the originating channel. Its principal stages are channel input, session/context management, model and tool execution, persistence, and channel output. The README documents these product branches; sampled source confirms portions of CLI handling, session storage, dashboard behavior, and provider/auth infrastructure, but not every runtime connection.

Main entry points: [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/agent-session.ts) (Agent session), [`packages/coding-agent/src/main.ts`](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/main.ts) (Terminal CLI), [`packages/telegram/src/inbound.ts`](https://github.com/h4fizwasabie/theoses2/blob/main/packages/telegram/src/inbound.ts) (Telegram channel), [`packages/ai/src/providers/all.ts`](https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/providers/all.ts) (Provider adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["User channels"]
  node_terminal["Terminal CLI<br/>[main.ts]"]
  node_telegram["Telegram channel<br/>[inbound.ts]"]
  node_dashboard["Browser dashboard<br/>[app.js]"]
  node_dashboard_backend["Dashboard service<br/>[index.ts]"]
  node_tui["Terminal interface"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_session["Agent session<br/>[agent-session.ts]"]
  node_agent_loop["Agent loop<br/>[agent-loop.ts]"]
  node_tools["Workspace tools<br/>[index.ts]"]
  node_extensions["Extensions and skills<br/>[index.ts]"]
end

subgraph group_models["Model access"]
  node_model_runtime["Model runtime<br/>[model-runtime.ts]"]
  node_ai_api["Provider API<br/>[index.ts]"]
  node_providers["Provider adapters<br/>[all.ts]"]
  node_auth["Provider authentication<br/>[resolve.ts]"]
  node_model_services{{"Model services"}}
end

subgraph group_continuity["Session and memory"]
  node_session_manager["Session manager<br/>[session-manager.ts]"]
  node_session_files[("JSONL sessions")]
  node_memory["Durable memory<br/>[memory-store.ts]"]
  node_working_notes["Working notes<br/>[working-note.ts]"]
end

subgraph group_transports["Optional transport"]
  node_protocol_client["Remote client<br/>[client.ts]"]
  node_protocol_server["Session server<br/>[server.ts]"]
  node_protocol["Framed CBOR protocol<br/>[index.ts]"]
end

node_owner(("Owner"))
node_telegram_service{{"Telegram service"}}
node_filesystem[("Project workspace")]

node_owner -->|"enters request"| node_terminal
node_owner -->|"sends message"| node_telegram
node_owner -->|"sends message"| node_dashboard
node_terminal -->|"creates session"| node_agent_session
node_telegram -->|"creates session"| node_agent_session
node_dashboard -->|"calls service"| node_dashboard_backend
node_dashboard_backend -->|"creates session"| node_agent_session
node_agent_session -->|"runs turns"| node_agent_loop
node_agent_session -->|"manages history"| node_session_manager
node_agent_session -->|"resolves model"| node_model_runtime
node_agent_loop -->|"dispatches tools"| node_tools
node_tools -->|"reads and writes"| node_filesystem
node_agent_session -->|"uses notes"| node_working_notes
node_agent_session -->|"queries memory"| node_memory
node_session_manager -->|"persists JSONL"| node_session_files
node_model_runtime -->|"calls API"| node_ai_api
node_ai_api -->|"dispatches provider"| node_providers
node_providers -->|"requests inference"| node_model_services
node_auth -->|"supplies credentials"| node_providers
node_telegram -->|"uses Bot API"| node_telegram_service
node_terminal -->|"renders interactive mode"| node_tui
node_protocol_client -.->|"encodes frames"| node_protocol
node_protocol_server -.->|"decodes frames"| node_protocol
node_protocol_server -.->|"serves sessions"| node_agent_session

click node_terminal "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/main.ts"
click node_telegram "https://github.com/h4fizwasabie/theoses2/blob/main/packages/telegram/src/inbound.ts"
click node_dashboard "https://github.com/h4fizwasabie/theoses2/blob/main/packages/dashboard/src/public/app.js"
click node_dashboard_backend "https://github.com/h4fizwasabie/theoses2/blob/main/packages/dashboard/src/index.ts"
click node_agent_session "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/agent-session.ts"
click node_agent_loop "https://github.com/h4fizwasabie/theoses2/blob/main/packages/agent/src/agent-loop.ts"
click node_tools "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/tools/index.ts"
click node_extensions "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/extensions/index.ts"
click node_tui "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts"
click node_session_manager "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/session-manager.ts"
click node_memory "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/memory-store.ts"
click node_working_notes "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/tools/working-note.ts"
click node_model_runtime "https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/model-runtime.ts"
click node_ai_api "https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/index.ts"
click node_providers "https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/providers/all.ts"
click node_auth "https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/auth/resolve.ts"
click node_protocol_client "https://github.com/h4fizwasabie/theoses2/blob/main/packages/client/src/client.ts"
click node_protocol_server "https://github.com/h4fizwasabie/theoses2/blob/main/packages/server/src/server.ts"
click node_protocol "https://github.com/h4fizwasabie/theoses2/blob/main/packages/protocol/src/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_terminal,node_telegram,node_dashboard,node_dashboard_backend,node_tui toneBlue
class node_agent_session,node_agent_loop,node_tools,node_extensions,node_filesystem toneAmber
class node_model_runtime,node_ai_api,node_providers,node_auth,node_model_services toneMint
class node_session_manager,node_session_files,node_memory,node_working_notes toneRose
class node_protocol_client,node_protocol_server,node_protocol,node_owner,node_telegram_service toneIndigo
```

## Components

### User channels

- [Terminal CLI](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/main.ts): `packages/coding-agent/src/main.ts`
- [Telegram channel](https://github.com/h4fizwasabie/theoses2/blob/main/packages/telegram/src/inbound.ts): `packages/telegram/src/inbound.ts`
- [Browser dashboard](https://github.com/h4fizwasabie/theoses2/blob/main/packages/dashboard/src/public/app.js): `packages/dashboard/src/public/app.js`
- [Dashboard service](https://github.com/h4fizwasabie/theoses2/blob/main/packages/dashboard/src/index.ts): `packages/dashboard/src/index.ts`
- [Terminal interface](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts): `packages/coding-agent/src/modes/interactive/interactive-mode.ts`

### Agent runtime

- [Agent session](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/agent-session.ts): `packages/coding-agent/src/core/agent-session.ts`
- [Agent loop](https://github.com/h4fizwasabie/theoses2/blob/main/packages/agent/src/agent-loop.ts): `packages/agent/src/agent-loop.ts`
- [Workspace tools](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/tools/index.ts): `packages/coding-agent/src/core/tools/index.ts`
- [Extensions and skills](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/extensions/index.ts): `packages/coding-agent/src/core/extensions/index.ts`

### Model access

- [Model runtime](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/model-runtime.ts): `packages/coding-agent/src/core/model-runtime.ts`
- [Provider API](https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/index.ts): `packages/ai/src/index.ts`
- [Provider adapters](https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/providers/all.ts): `packages/ai/src/providers/all.ts`
- [Provider authentication](https://github.com/h4fizwasabie/theoses2/blob/main/packages/ai/src/auth/resolve.ts): `packages/ai/src/auth/resolve.ts`
- **Model services**

### Session and memory

- [Session manager](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/session-manager.ts): `packages/coding-agent/src/core/session-manager.ts`
- **JSONL sessions**
- [Durable memory](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/memory-store.ts): `packages/coding-agent/src/core/memory-store.ts`
- [Working notes](https://github.com/h4fizwasabie/theoses2/blob/main/packages/coding-agent/src/core/tools/working-note.ts): `packages/coding-agent/src/core/tools/working-note.ts`

### Optional transport

- [Remote client](https://github.com/h4fizwasabie/theoses2/blob/main/packages/client/src/client.ts): `packages/client/src/client.ts`
- [Session server](https://github.com/h4fizwasabie/theoses2/blob/main/packages/server/src/server.ts): `packages/server/src/server.ts`
- [Framed CBOR protocol](https://github.com/h4fizwasabie/theoses2/blob/main/packages/protocol/src/index.ts): `packages/protocol/src/index.ts`

### Other components

- **Owner**
- **Telegram service**
- **Project workspace**

## Connections

- Owner → Terminal CLI: enters request
- Owner → Telegram channel: sends message
- Owner → Browser dashboard: sends message
- Terminal CLI → Agent session: creates session
- Telegram channel → Agent session: creates session
- Browser dashboard → Dashboard service: calls service
- Dashboard service → Agent session: creates session
- Agent session → Agent loop: runs turns
- Agent session → Session manager: manages history
- Agent session → Model runtime: resolves model
- Agent loop → Workspace tools: dispatches tools
- Workspace tools → Project workspace: reads and writes
- Agent session → Working notes: uses notes
- Agent session → Durable memory: queries memory
- Session manager → JSONL sessions: persists JSONL
- Model runtime → Provider API: calls API
- Provider API → Provider adapters: dispatches provider
- Provider adapters → Model services: requests inference
- Provider authentication → Provider adapters: supplies credentials
- Telegram channel → Telegram service: uses Bot API
- Terminal CLI → Terminal interface: renders interactive mode
- Remote client → Framed CBOR protocol: encodes frames
- Session server → Framed CBOR protocol: decodes frames
- Session server → Agent session: serves sessions