README
¶
internal/
Thane's internal packages, organized by architectural role.
How the agent thinks
| Package | Purpose |
|---|---|
agent/ |
Core loop: assembles context, plans via LLM, executes tools, returns responses |
llm/ |
LLM provider abstraction (Anthropic, Ollama) and streaming |
router/ |
Model selection — picks the best model for each request based on quality, cost, and hints |
prompts/ |
System prompt templates for all agent modes (main, delegate, compaction, extraction) |
talents/ |
Capability tag system — markdown-based behavior guidance that scopes tool access |
delegate/ |
Delegate task execution — isolated sub-agent runs with their own tool sets |
metacognitive/ |
Autonomous self-reflection loop that monitors state and adjusts its own attention cycle |
tools/ |
Tool registry and all tool handler implementations |
What the agent knows
| Package | Purpose |
|---|---|
memory/ |
Conversation storage, compaction, archiving, episodic memory, and session summarization |
knowledge/ |
Structured entity facts, semantic search via embeddings, and document ingestion |
contacts/ |
Contact directory, trust zones, presence tracking, and relationship metadata |
awareness/ |
System prompt context providers — current conditions, HA state window, entity watchlist |
How the agent communicates
| Package | Purpose |
|---|---|
channels/email/ |
Email integration (IMAP polling, SMTP sending, trust-based filtering) |
channels/signal/ |
Signal messenger bridge (receives messages, routes to agent, sends replies) |
channels/mqtt/ |
MQTT for Home Assistant device discovery and sensor state publishing |
server/api/ |
REST API — OpenAI-compatible and Ollama-compatible endpoints |
server/web/ |
Built-in web dashboard and chat UI |
carddav/ |
CardDAV server for native contact app sync (macOS Contacts.app, iOS, Thunderbird) |
notifications/ |
Provider-agnostic notification routing, actionable HITL callbacks, timeout escalation |
Domain integrations
| Package | Purpose |
|---|---|
homeassistant/ |
Home Assistant REST + WebSocket client |
unifi/ |
UniFi network client (device tracking, AP associations) |
forge/ |
GitHub and Forgejo integration (issues, PRs, repo management) |
mcp/ |
Model Context Protocol client and tool bridge |
media/ |
Media transcript extraction, RSS/Atom feed polling, and content summarization |
search/ |
Web search providers (Brave, SearXNG) and page content extraction |
Platform
| Package | Purpose |
|---|---|
config/ |
Configuration loading, validation, and defaults |
database/ |
Shared SQLite helpers (WAL mode, busy timeout, schema migration) |
scheduler/ |
Task scheduling (time-based and condition-based via anticipations) |
opstate/ |
Operational state key-value store with TTLs |
events/ |
In-process publish/subscribe event bus |
checkpoint/ |
State snapshots for crash recovery |
usage/ |
LLM token usage and cost tracking |
httpkit/ |
Shared HTTP client construction (User-Agent, timeouts) |
connwatch/ |
Service health monitoring with exponential backoff |
buildinfo/ |
Build metadata injected via ldflags |
paths/ |
Named path prefix resolution (e.g., kb:file.md) |
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agent implements the core agent loop.
|
Package agent implements the core agent loop. |
|
Package conditions generates the "Current Conditions" section of the system prompt.
|
Package conditions generates the "Current Conditions" section of the system prompt. |
|
Package buildinfo holds version and build metadata stamped at compile time via ldflags.
|
Package buildinfo holds version and build metadata stamped at compile time via ldflags. |
|
Package carddav implements a CardDAV server backed by the contacts store.
|
Package carddav implements a CardDAV server backed by the contacts store. |
|
channels
|
|
|
email
Package email provides native IMAP and SMTP email for the Thane agent.
|
Package email provides native IMAP and SMTP email for the Thane agent. |
|
mqtt
Package mqtt publishes Home Assistant MQTT discovery messages, periodic sensor state updates, and subscribes to configured topics for ambient awareness.
|
Package mqtt publishes Home Assistant MQTT discovery messages, periodic sensor state updates, and subscribes to configured topics for ambient awareness. |
|
signal
Package signal provides a native Go integration with signal-cli's JSON-RPC daemon mode for sending and receiving Signal messages.
|
Package signal provides a native Go integration with signal-cli's JSON-RPC daemon mode for sending and receiving Signal messages. |
|
Package checkpoint provides state snapshotting and restoration for Thane.
|
Package checkpoint provides state snapshotting and restoration for Thane. |
|
Package config handles loading, defaulting, and validating Thane's YAML configuration.
|
Package config handles loading, defaulting, and validating Thane's YAML configuration. |
|
Package connwatch provides service-level health monitoring with exponential backoff for external dependencies (Home Assistant, Ollama, etc).
|
Package connwatch provides service-level health monitoring with exponential backoff for external dependencies (Home Assistant, Ollama, etc). |
|
Package person tracks presence state for configured household members and provides context injection into the agent's system prompt.
|
Package person tracks presence state for configured household members and provides context injection into the agent's system prompt. |
|
Package database provides shared SQLite helpers for schema migration and connection management.
|
Package database provides shared SQLite helpers for schema migration and connection management. |
|
Package delegate implements the thane_delegate meta-tool for split-model execution.
|
Package delegate implements the thane_delegate meta-tool for split-model execution. |
|
Package events provides a publish/subscribe event bus for operational observability.
|
Package events provides a publish/subscribe event bus for operational observability. |
|
Package forge provides a pluggable code forge interface for issue, pull request, and code review management.
|
Package forge provides a pluggable code forge interface for issue, pull request, and code review management. |
|
Package homeassistant provides a client for the Home Assistant API.
|
Package homeassistant provides a client for the Home Assistant API. |
|
Package httpkit provides shared HTTP client construction and utilities for all outbound HTTP calls in Thane.
|
Package httpkit provides shared HTTP client construction and utilities for all outbound HTTP calls in Thane. |
|
Package facts provides context injection for the agent loop.
|
Package facts provides context injection for the agent loop. |
|
Package llm provides LLM client implementations.
|
Package llm provides LLM client implementations. |
|
Package mcp implements MCP (Model Context Protocol) client support, allowing Thane to connect to external MCP servers and expose their tools to the agent loop and delegates.
|
Package mcp implements MCP (Model Context Protocol) client support, allowing Thane to connect to external MCP servers and expose their tools to the agent loop and delegates. |
|
Package media provides media transcript retrieval via yt-dlp.
|
Package media provides media transcript retrieval via yt-dlp. |
|
Package episodic provides context injection of episodic memory into the agent's system prompt.
|
Package episodic provides context injection of episodic memory into the agent's system prompt. |
|
Package metacognitive implements a perpetual self-regulating attention loop that reads persistent state, reasons via LLM, and adapts its own sleep cycle.
|
Package metacognitive implements a perpetual self-regulating attention loop that reads persistent state, reasons via LLM, and adapts its own sleep cycle. |
|
Package notifications provides provider-agnostic notification delivery with routing, callback tracking, and timeout management.
|
Package notifications provides provider-agnostic notification delivery with routing, callback tracking, and timeout management. |
|
Package opstate provides a namespaced key-value store for persistent operational state.
|
Package opstate provides a namespaced key-value store for persistent operational state. |
|
Package paths provides a shared prefix resolver for named directory paths.
|
Package paths provides a shared prefix resolver for named directory paths. |
|
Package prompts contains all LLM prompt templates used internally by Thane.
|
Package prompts contains all LLM prompt templates used internally by Thane. |
|
Package router handles intelligent model selection.
|
Package router handles intelligent model selection. |
|
Package anticipation provides storage and matching for agent anticipations.
|
Package anticipation provides storage and matching for agent anticipations. |
|
Package fetch provides web page fetching and content extraction.
|
Package fetch provides web page fetching and content extraction. |
|
server
|
|
|
api
Package api implements the Ollama-compatible HTTP API endpoints.
|
Package api implements the Ollama-compatible HTTP API endpoints. |
|
web
Package web provides the web dashboard and chat interface for Thane.
|
Package web provides the web dashboard and chat interface for Thane. |
|
Package talents loads and manages behavioral guidance documents.
|
Package talents loads and manages behavioral guidance documents. |
|
Package tools provides the tool registry and execution framework.
|
Package tools provides the tool registry and execution framework. |
|
Package unifi provides a client for the UniFi Network controller API and a provider interface for room-level presence detection via wireless AP client associations.
|
Package unifi provides a client for the UniFi Network controller API and a provider interface for room-level presence detection via wireless AP client associations. |
|
Package usage provides persistent token usage and cost tracking for LLM interactions.
|
Package usage provides persistent token usage and cost tracking for LLM interactions. |
Click to show internal directories.
Click to hide internal directories.