thane-ai-agent

module
v0.9.1-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2026 License: Apache-2.0

README

Thane

CI Go Reference Go Report Card Go Version License Release

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.

On macOS, we recommend the thane-agent-macos companion app for a native, integrated way to run Thane on a Mac.

Releases

Tagged releases publish locally prepared release artifacts on GitHub plus a multi-arch container image on ghcr.io/nugget/thane-ai-agent. The intended release path is to build, sign, notarize, staple, and upload the macOS installer product archives alongside the Linux tarballs from a local release workstation via just. Those macOS artifacts install thane into ~/Thane/bin, carry first-party installer metadata for inspection, avoid a machine-wide admin prompt, and can be stapled cleanly after notarization. GitHub Actions publishes the tagged container image and its provenance attestation. The preferred operator workflows are:

  • just release-github 0.9.0
  • just release-github 0.9.0 prerelease
  • just deploy-macos-pkg user@host

See Release Engineering for the full workflow and credential requirements.

Documentation

Understand It
Run It
Extend It

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.
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.
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 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.
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.
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.
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.
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.
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.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.