How h4fizwasabie/theoses2 works
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: agent-session.ts Agent session · main.ts Terminal CLI · inbound.ts Telegram channel · all.ts Provider adapters
Components 24
User channels
- Terminal CLI
packages/coding-agent/src/main.ts - Telegram channel
packages/telegram/src/inbound.ts - Browser dashboard
packages/dashboard/src/public/app.js - Dashboard service
packages/dashboard/src/index.ts - Terminal interface
packages/coding-agent/src/modes/interactive/interactive-mode.ts
Agent runtime
- Agent session
packages/coding-agent/src/core/agent-session.ts - Agent loop
packages/agent/src/agent-loop.ts - Workspace tools
packages/coding-agent/src/core/tools/index.ts - Extensions and skills
packages/coding-agent/src/core/extensions/index.ts
Model access
- Model runtime
packages/coding-agent/src/core/model-runtime.ts - Provider API
packages/ai/src/index.ts - Provider adapters
packages/ai/src/providers/all.ts - Provider authentication
packages/ai/src/auth/resolve.ts - Model services
Session and memory
- Session manager
packages/coding-agent/src/core/session-manager.ts - JSONL sessions
- Durable memory
packages/coding-agent/src/core/memory-store.ts - Working notes
packages/coding-agent/src/core/tools/working-note.ts
Optional transport
- Remote client
packages/client/src/client.ts - Session server
packages/server/src/server.ts - Framed CBOR protocol
packages/protocol/src/index.ts
Other components
- Owner
- Telegram service
- Project workspace
Connections 24
- 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