Core Concepts
Spaces
A Space is a shared workspace for a team. Everything in Themis is scoped to a space:
- API credentials (GitHub tokens, Linear keys, etc.)
- Feature toggles (Projects, Automations, Skills)
- Agent settings (model, temperature, identity)
- Conversations, tasks, and automations
Users belong to spaces with roles: owner, manager, or member. Spaces marked as default automatically include new users on sign-up.
Conversations
The primary interaction model. Users chat with Themis through the web UI, and the agent responds with tool-assisted answers, generated code, data analysis, or workflow actions.
Conversations support:
- Real-time token streaming via Turbo Streams
- File attachments and image analysis
- Forking (branching off to explore a different direction)
- Sharing via public links or to specific users
- Discussion comments (threaded annotations on shared conversations)
Inbox
The central hub at /inbox that aggregates all activity. Each tab has always-visible sub-filter chips:
| Tab | Sub-filters |
|---|---|
| Chats | Mine, Shared, API |
| Tasks | Doing, Todo, Done |
| Signals | Auto, Reviews, Mentions, Code |
| Saved | (no sub-filters) |
Full-text search is powered by PostgreSQL trigram matching.
Channels
Channels connect Themis to external services. Each channel is configured per-space with its own credentials:
| Channel | What It Does |
|---|---|
| GitHub | PR reviews, code generation, CI status, issue tracking |
| Linear | Issue management, bug reports, user stories |
| Sentry | Error alerts, issue triage |
| Metabase | Data queries, dashboard insights |
| Google Drive | File search, document access |
| Google Calendar | Events, availability, OOO + focus time |
| Gmail | Read, search, label, archive |
| Google Analytics | GA4 reports, realtime metrics, custom dimensions |
| Google Maps | Geocoding, places, directions, weather |
| Flight Search | Google Flights search (date + price) |
| Teams | Chat bot, group messaging |
| Telegram | Chat bot, voice messages |
Channels receive events via webhooks and dispatch them to agent workflows.
Two-Tier Agent
Themis uses a two-tier agent architecture for optimal speed and capability:
Tier 1 (Fast) — LightweightAgentService via RubyLLM. Single-turn responses for simple questions. If the question needs deeper reasoning or tool access, it escalates automatically.
Tier 2 (Full) — Claude Agent SDK with MCP servers, security hooks, and multi-turn conversations. Used for code reviews, data analysis, and complex workflows.
Escalation is seamless — the user sees a single conversation regardless of which tier handles it.
Automations
Recurring or event-driven agent tasks that run without user interaction:
- Scheduled: Cron-based (e.g., “every Monday at 9am”). Uses Fugit for cron parsing with IANA timezone support.
- Event-triggered: Responds to activities (e.g.,
github.pull_request.opened). Supports prefix matching and cooldown windows.
Results are delivered to the web inbox, Telegram, or Teams — configurable per automation.
Skills
Reusable domain knowledge that enriches agent capabilities. See Skills-First Architecture for details.
- File-based (
.claude/skills/) — Checked into the repo, auto-discovered by the SDK - DB-backed (
Skillmodel) — Created via UI or chat, scoped to space/personal - Portable (
lib/skills/) — Copied to target projects during code generation
Tasks
Cross-channel work items that unify activity from different services. A single task can aggregate a GitHub PR, a Linear issue, and a Sentry alert if they’re related.
TaskKeyResolver computes task keys, and TaskUnifier merges tasks that share references — for example, linking a GitHub branch to its originating Linear issue.