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/ |
Time-based task scheduling |
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 |
logging/ |
Self-managed log rotation, context-propagated structured logging, and queryable SQLite index |
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 app contains the application-level wiring for the Thane server.
|
Package app contains the application-level wiring for the Thane server. |
|
Package attachments provides a content-addressed attachment store backed by SHA-256 hashing and a SQLite metadata index.
|
Package attachments provides a content-addressed attachment store backed by SHA-256 hashing and a SQLite metadata index. |
|
Package awareness provides system prompt context providers that give the agent real-time environmental awareness — current conditions, state changes, and watched entities.
|
Package awareness provides system prompt context providers that give the agent real-time environmental awareness — current conditions, state changes, and watched entities. |
|
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. |
|
gen/gencfg
command
Command gencfg generates examples/config.example.yaml from the internal/config package.
|
Command gencfg generates examples/config.example.yaml from the internal/config package. |
|
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 contacts provides vCard-aligned structured storage for people, organizations, groups, and locations.
|
Package contacts provides vCard-aligned structured storage for people, organizations, groups, and locations. |
|
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 iterate provides a shared model iteration engine for agentic LLM workflows.
|
Package iterate provides a shared model iteration engine for agentic LLM workflows. |
|
Package knowledge provides long-term semantic memory — facts the agent learns through conversation and ingestion, stored with optional embeddings for natural-language recall.
|
Package knowledge provides long-term semantic memory — facts the agent learns through conversation and ingestion, stored with optional embeddings for natural-language recall. |
|
Package llm provides LLM client implementations.
|
Package llm provides LLM client implementations. |
|
Package logging provides self-managed log file rotation, context-propagated structured logging, and a queryable SQLite index for Thane.
|
Package logging provides self-managed log file rotation, context-propagated structured logging, and a queryable SQLite index for Thane. |
|
Package loop implements persistent goroutine-based delegate loops — lightweight autonomous observers that run continuously alongside the main agent, reporting via output targets without blocking conversation flow.
|
Package loop implements persistent goroutine-based delegate loops — lightweight autonomous observers that run continuously alongside the main agent, reporting via output targets without blocking conversation flow. |
|
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 memory provides conversation memory storage and session archiving.
|
Package memory provides conversation memory storage and session archiving. |
|
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 models provides the normalized model catalog, live registry, and runtime client wiring.
|
Package models provides the normalized model catalog, live registry, and runtime client wiring. |
|
providers
Package providers implements concrete model runner integrations.
|
Package providers implements concrete model runner integrations. |
|
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 platform implements the WebSocket endpoint for native platform provider connections (e.g.
|
Package platform implements the WebSocket endpoint for native platform provider connections (e.g. |
|
Package prompts contains all LLM prompt templates used internally by Thane.
|
Package prompts contains all LLM prompt templates used internally by Thane. |
|
Package provenance provides a git-backed file store with SSH signature enforcement.
|
Package provenance provides a git-backed file store with SSH signature enforcement. |
|
Package router handles intelligent model selection.
|
Package router handles intelligent model selection. |
|
Package scheduler handles future task scheduling and execution.
|
Package scheduler handles future task scheduling and execution. |
|
Package search provides a pluggable web search interface for the agent.
|
Package search provides a pluggable web search interface for the agent. |
|
server
|
|
|
api
Package api implements the OpenAI-compatible HTTP API.
|
Package api implements the OpenAI-compatible HTTP API. |
|
web
Package web implements the Cognition Engine dashboard served at the root of the Thane HTTP server.
|
Package web implements the Cognition Engine dashboard served at the root of the Thane HTTP server. |
|
Package talents loads and manages behavioral guidance documents.
|
Package talents loads and manages behavioral guidance documents. |
|
Package telemetry collects and publishes operational metrics via MQTT for Home Assistant sensor integration.
|
Package telemetry collects and publishes operational metrics via MQTT for Home Assistant sensor integration. |
|
Package toolcatalog provides compiled-in metadata for tools and capability tags, and renders capability surface descriptions for model-facing context and the web dashboard.
|
Package toolcatalog provides compiled-in metadata for tools and capability tags, and renders capability surface descriptions for model-facing context and the web dashboard. |
|
Package tools defines the tools available to the agent.
|
Package tools defines the tools available to the agent. |
|
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.