README
¶
internal/
Thane's internal packages are organized by architectural role. The directory layout is meant to answer the first question future humans and agents ask: "what kind of thing am I looking at?"
Placement Rules
app/is the composition root. It may wire broad subsystems together.server/is the local API/UI surface.tools/owns tool runtime primitives: registry, context plumbing, provider interfaces, common errors, and shared tool helpers.- Domain-specific tool behavior belongs with the domain package whenever
practical. Do not add new domain tool families to
tools/by default. Existing domain tool families still live intools/and should migrate incrementally when there is a focused reason to move them. - Packages should generally import inward toward platform/model/state primitives, not sideways through unrelated domains.
Runtime
Execution machinery for agent runs and child work.
| Package | Purpose |
|---|---|
runtime/agent/ |
Core agent loop: context assembly, model calls, tool execution, responses |
runtime/loop/ |
Durable loop runtime, loop definitions, launch/request bridge |
runtime/delegate/ |
Delegate task execution and child-loop handoff |
runtime/iterate/ |
Model/tool iteration engine |
runtime/metacognitive/ |
Autonomous self-reflection loop |
Model Interface
How Thane talks to models and shapes model-facing context.
| Package | Purpose |
|---|---|
model/llm/ |
LLM client contracts, messages, streaming, tool-call parsing |
model/fleet/ |
Model fleet catalog, provider clients, registry, runtime inventory |
model/router/ |
Model selection and routing profiles |
model/prompts/ |
Prompt templates and runtime contracts |
model/talents/ |
Markdown behavioral guidance loaded by capability tags |
model/toolcatalog/ |
Capability tag catalog and model-facing tool summaries |
model/promptfmt/ |
Shared prompt-formatting helpers |
State
Durable knowledge, persisted projections, and assembled situational context the agent reasons over.
| Package | Purpose |
|---|---|
state/memory/ |
Conversations, archives, compaction, episodic memory |
state/contacts/ |
Contact directory, trust zones, CardDAV-facing records |
state/documents/ |
Managed document roots, queries, mutation helpers |
state/knowledge/ |
Structured facts, embeddings, semantic search |
state/awareness/ |
Agent-facing situational context: current conditions, HA state windows, watchlists |
state/attachments/ |
Attachment storage and metadata |
Channels
Entrypoints and communication surfaces that can wake, converse, notify, or carry human/event interaction.
channels/messages/ is the in-process envelope and bus substrate shared
by channel adapters and runtime loop signaling. It lives here because it
defines message-channel contracts, even though it is not an external
adapter like Signal or email.
| Package | Purpose |
|---|---|
channels/messaging/signal/ |
Signal request/reply bridge and provider-specific messaging tools |
channels/email/ |
Email polling, reading, sending, trust filtering |
channels/mqtt/ |
MQTT event/wake subscriptions and HA discovery publishing |
channels/messages/ |
In-process message envelopes and buses |
channels/notifications/ |
Notification routing, actionable callbacks, timeout escalation |
Integrations
External systems exposed as capabilities or provider-backed tool surfaces.
| Package | Purpose |
|---|---|
integrations/homeassistant/ |
Home Assistant REST/WebSocket client and state projections |
integrations/unifi/ |
UniFi network client and device tracking |
integrations/forge/ |
GitHub/Forgejo integration for issues, PRs, repos |
integrations/media/ |
Feeds, transcripts, media vault, summarization |
integrations/search/ |
Web search providers and page extraction |
integrations/mcp/ |
Model Context Protocol client and tool bridge |
integrations/companion/ |
Native companion app WebSocket endpoint |
Platform
Cross-cutting process, storage, scheduling, and operational substrate.
| Package | Purpose |
|---|---|
platform/config/ |
Configuration loading, validation, defaults, generated example config |
platform/database/ |
Shared SQLite helpers and timestamp parsing |
platform/logging/ |
Structured logging, request archival, queryable log index |
platform/events/ |
In-process publish/subscribe event bus |
platform/opstate/ |
Operational state key-value store with TTLs |
platform/paths/ |
Named path prefix resolution, such as kb:file.md |
platform/httpkit/ |
Shared HTTP client construction and response helpers |
platform/scheduler/ |
Time-based task scheduling |
platform/usage/ |
LLM token usage and cost accounting |
platform/telemetry/ |
Runtime telemetry collection |
platform/checkpoint/ |
State snapshots for crash recovery |
platform/buildinfo/ |
Build metadata injected via ldflags |
platform/provenance/ |
Tool-call and content provenance helpers |
API And Composition
| Package | Purpose |
|---|---|
app/ |
Wires configuration, stores, providers, tools, loops, and servers |
server/api/ |
OpenAI-compatible, Ollama-compatible, and admin HTTP APIs |
server/web/ |
Built-in web dashboard and chat UI |
server/carddav/ |
CardDAV server for native contact app sync |
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app contains the application-level wiring for the Thane server.
|
Package app contains the application-level wiring for the Thane server. |
|
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. |
|
messages
Package messages defines the shared envelope and delivery substrate for inter-component communication inside Thane.
|
Package messages defines the shared envelope and delivery substrate for inter-component communication inside Thane. |
|
messaging/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. |
|
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. |
|
notifications
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 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). |
|
integrations
|
|
|
companion
Package companion implements the WebSocket endpoint for native companion app connections (e.g.
|
Package companion implements the WebSocket endpoint for native companion app connections (e.g. |
|
forge
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. |
|
homeassistant
Package homeassistant provides a client for the Home Assistant API.
|
Package homeassistant provides a client for the Home Assistant API. |
|
homeassistant/contextfmt
Package contextfmt renders Home Assistant entity states into compact, model-facing context.
|
Package contextfmt renders Home Assistant entity states into compact, model-facing context. |
|
mcp
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. |
|
media
Package media provides media transcript retrieval via yt-dlp.
|
Package media provides media transcript retrieval via yt-dlp. |
|
search
Package search provides a pluggable web search interface for the agent.
|
Package search provides a pluggable web search interface for the agent. |
|
unifi
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. |
|
model
|
|
|
fleet
Package fleet provides the normalized model catalog, live registry, and runtime client wiring.
|
Package fleet provides the normalized model catalog, live registry, and runtime client wiring. |
|
fleet/providers
Package providers implements concrete model runner integrations.
|
Package providers implements concrete model runner integrations. |
|
llm
Package llm provides LLM client implementations.
|
Package llm provides LLM client implementations. |
|
promptfmt
Package promptfmt provides presentation-layer helpers used to render values into prompt and context strings: relative timestamps, ID truncation for display, thousands-grouped numbers, and compact JSON.
|
Package promptfmt provides presentation-layer helpers used to render values into prompt and context strings: relative timestamps, ID truncation for display, thousands-grouped numbers, and compact JSON. |
|
prompts
Package prompts contains all LLM prompt templates used internally by Thane.
|
Package prompts contains all LLM prompt templates used internally by Thane. |
|
router
Package router handles intelligent model selection.
|
Package router handles intelligent model selection. |
|
talents
Package talents loads and manages behavioral guidance documents.
|
Package talents loads and manages behavioral guidance documents. |
|
toolcatalog
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. |
|
platform
|
|
|
buildinfo
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. |
|
checkpoint
Package checkpoint provides state snapshotting and restoration for Thane.
|
Package checkpoint provides state snapshotting and restoration for Thane. |
|
config
Package config handles loading, defaulting, and validating Thane's YAML configuration.
|
Package config handles loading, defaulting, and validating Thane's YAML configuration. |
|
config/gen/gencfg
command
Command gencfg generates examples/config.example.yaml from the internal/platform/config package.
|
Command gencfg generates examples/config.example.yaml from the internal/platform/config package. |
|
database
Package database provides shared SQLite helpers for schema migration and connection management.
|
Package database provides shared SQLite helpers for schema migration and connection management. |
|
events
Package events provides a publish/subscribe event bus for operational observability.
|
Package events provides a publish/subscribe event bus for operational observability. |
|
httpkit
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. |
|
identity
Package identity bootstraps Thane instance identity material.
|
Package identity bootstraps Thane instance identity material. |
|
logging
Package logging provides dataset-partitioned JSONL log retention, context-propagated structured logging, and a queryable SQLite index for Thane.
|
Package logging provides dataset-partitioned JSONL log retention, context-propagated structured logging, and a queryable SQLite index for Thane. |
|
opstate
Package opstate provides a namespaced key-value store for persistent operational state.
|
Package opstate provides a namespaced key-value store for persistent operational state. |
|
paths
Package paths provides a shared prefix resolver for named directory paths.
|
Package paths provides a shared prefix resolver for named directory paths. |
|
provenance
Package provenance provides a git-backed file store with SSH signature enforcement.
|
Package provenance provides a git-backed file store with SSH signature enforcement. |
|
scheduler
Package scheduler handles future task scheduling and execution.
|
Package scheduler handles future task scheduling and execution. |
|
telemetry
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. |
|
usage
Package usage provides persistent token usage and cost tracking for LLM interactions.
|
Package usage provides persistent token usage and cost tracking for LLM interactions. |
|
runtime
|
|
|
agent
Package agent implements the core agent loop.
|
Package agent implements the core agent loop. |
|
agentctx
Package agentctx defines per-Run context types shared by the agent loop and the providers it pulls context from.
|
Package agentctx defines per-Run context types shared by the agent loop and the providers it pulls context from. |
|
delegate
Package delegate implements the thane_now and thane_assign delegation tools for split-model execution.
|
Package delegate implements the thane_now and thane_assign delegation tools for split-model execution. |
|
ego
Package ego implements the self-reflection loop that maintains core/ego.md.
|
Package ego implements the self-reflection loop that maintains core/ego.md. |
|
iterate
Package iterate provides a shared model iteration engine for agentic LLM workflows.
|
Package iterate provides a shared model iteration engine for agentic LLM workflows. |
|
loop
Package loop implements persistent goroutine-based delegate loops — lightweight autonomous observers that run continuously alongside the main agent, with direct completion delivery or ordinary tool use for any durable artifacts they need to maintain.
|
Package loop implements persistent goroutine-based delegate loops — lightweight autonomous observers that run continuously alongside the main agent, with direct completion delivery or ordinary tool use for any durable artifacts they need to maintain. |
|
metacognitive
Package metacognitive implements a perpetual self-regulating attention loop that receives persistent state, reasons via LLM, and adapts its own sleep cycle.
|
Package metacognitive implements a perpetual self-regulating attention loop that receives persistent state, reasons via LLM, and adapts its own sleep cycle. |
|
server
|
|
|
api
Package api implements the OpenAI-compatible HTTP API.
|
Package api implements the OpenAI-compatible HTTP API. |
|
carddav
Package carddav implements a CardDAV server backed by the contacts store.
|
Package carddav implements a CardDAV server backed by the contacts store. |
|
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. |
|
state
|
|
|
attachments
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. |
|
awareness
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. |
|
contacts
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. |
|
documents
Package documents indexes managed local markdown roots for model-facing rediscovery, browse, search, and section retrieval.
|
Package documents indexes managed local markdown roots for model-facing rediscovery, browse, search, and section retrieval. |
|
knowledge
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. |
|
memory
Package memory provides conversation memory storage and session archiving.
|
Package memory provides conversation memory storage and session archiving. |
|
Package tools defines the tools available to the agent.
|
Package tools defines the tools available to the agent. |
Click to show internal directories.
Click to hide internal directories.