README
¶
Thane
An autonomous AI agent that learns, remembers, and acts.
Your home already generates thousands of data points every hour — temperature sensors, motion detectors, door states, power draws. Thane is an AI agent that actually understands them. It knows an open garage door for two hours is unusual, that someone in the kitchen at 2am doesn't want bright lights, and that the dryer finishing three hours ago but still drawing power is worth mentioning. It learns your home, your preferences, and your routines through conversation — and it remembers.
Everything runs on your hardware, behind your firewall. Thane works with any model runner that speaks a standard inference API — local or cloud, your choice. Written in Go. Single binary first, with an optional container image. No Python, no accounts to create.
What Makes Thane Different
Autonomous, not subjected. Home Assistant's Assist can only see entities you pre-select. Thane has full API access — it discovers devices, understands context, and acts on its own.
Memory that persists. Tell it once that you like the lights dim after 10pm and it just knows. Facts, preferences, routines — all learned through natural conversation and remembered across restarts.
Private by architecture. Every conversation, every fact, every contact lives in SQLite on your machine. Cloud models are available but nothing requires them. Privacy is structural, not a policy promise.
Smart about cost. The frontier model thinks; a small free local model does the work. Delegation keeps 90%+ of tool calls at zero API cost.
Single binary. go build and you're done. One command: thane.
Quick Start
git clone https://github.com/nugget/thane-ai-agent.git
cd thane-ai-agent
just build && just init
# Edit ~/Thane/config.yaml with your HA token, Ollama URL, and MQTT broker
just serve
Point Home Assistant's Ollama integration at http://thane-host:11434, select model thane:latest, and start talking.
Your First Thane — Complete onboarding guide with hardware, models, and deployment.
Releases
Tagged releases publish locally prepared archives on GitHub plus a multi-arch
container image on ghcr.io/nugget/thane-ai-agent. The intended release path
is to build, sign, notarize, and upload the macOS and Linux archives from a
local release workstation via just, while GitHub Actions publishes the tagged
container image and its provenance attestation.
Documentation
Understand It
- Philosophy — Why Thane exists and why Home Assistant is foundational
- Architecture — System design and component overview
- Trust Architecture — Safety through structure, not prompts
Run It
- Getting Started — Build, configure, run
- Home Assistant — HA integration setup
- Configuration — Config guide by concern
- Deployment — macOS and Linux service installation
Extend It
- Delegation & MCP — Orchestrator/delegate pattern and MCP tool servers
- Tools Reference — All 80+ native tools
- Full Documentation — Guided tour of all docs
Name
Thane — A Scottish term for a landholder who managed an estate on behalf of the crown. Your home automation estate deserves a capable steward. (Project History)
Contributing
Contributions welcome. See CONTRIBUTING.md.
License
Apache 2.0 — aligned with Home Assistant.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
openclaw-import
command
Command openclaw-import migrates OpenClaw session data into Thane's conversation archive.
|
Command openclaw-import migrates OpenClaw session data into Thane's conversation archive. |
|
thane
command
Thane is an autonomous Home Assistant agent.
|
Thane is an autonomous Home Assistant agent. |
|
internal
|
|
|
agent
Package agent implements the core agent loop.
|
Package agent implements the core agent loop. |
|
app
Package app contains the application-level wiring for the Thane server.
|
Package app contains the application-level wiring for the Thane server. |
|
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. |
|
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. |
|
carddav
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. |
|
channels/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. |
|
channels/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. |
|
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/config package.
|
Command gencfg generates examples/config.example.yaml from the internal/config package. |
|
connwatch
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). |
|
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. |
|
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. |
|
delegate
Package delegate implements the thane_delegate meta-tool for split-model execution.
|
Package delegate implements the thane_delegate meta-tool for split-model execution. |
|
events
Package events provides a publish/subscribe event bus for operational observability.
|
Package events provides a publish/subscribe event bus for operational observability. |
|
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. |
|
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. |
|
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. |
|
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. |
|
llm
Package llm provides LLM client implementations.
|
Package llm provides LLM client implementations. |
|
logging
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. |
|
loop
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. |
|
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. |
|
memory
Package memory provides conversation memory storage and session archiving.
|
Package memory provides conversation memory storage and session archiving. |
|
metacognitive
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. |
|
models
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. |
|
models/providers
Package providers implements concrete model runner integrations.
|
Package providers implements concrete model runner integrations. |
|
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. |
|
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. |
|
platform
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. |
|
prompts
Package prompts contains all LLM prompt templates used internally by Thane.
|
Package prompts contains all LLM prompt templates used internally by Thane. |
|
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. |
|
router
Package router handles intelligent model selection.
|
Package router handles intelligent model selection. |
|
scheduler
Package scheduler handles future task scheduling and execution.
|
Package scheduler handles future task scheduling and execution. |
|
search
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. |
|
server/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. |
|
talents
Package talents loads and manages behavioral guidance documents.
|
Package talents loads and manages behavioral guidance documents. |
|
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. |
|
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. |
|
tools
Package tools defines the tools available to the agent.
|
Package tools defines the tools available to 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. |
|
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. |
Click to show internal directories.
Click to hide internal directories.