Skip to content
Habakkuk

Overview

Habakkuk is a durable personal AI agent in one Go binary: many chat channels, tools, memory, skills, schedules and a job queue that survives kill -9.

On this page

A durable personal AI agent in one Go binary. Habakkuk talks to you over the CLI, Telegram, Slack, WhatsApp (as a linked device or as a WhatsApp agent), Discord, Signal, Matrix, email, SMS, Microsoft Teams, Google Chat, iMessage, LINE, Mattermost, IRC, ntfy, the WhatsApp Business Cloud API, Messenger, Instagram, Feishu/Lark, DingTalk, WeCom, Zulip, Rocket.Chat, Nextcloud Talk, Twitch chat and a small web chat, uses tools, and survives crashes: every turn is a job with a lease, so a kill -9 at any moment loses nothing and a restart picks up where it stopped.

Why Habakkuk#

  • One binary. One static binary, no CGO and no runtime to install.
  • Crash-proof by design. Every turn is a leased job; a dead process's work is reclaimed on restart and interrupted tool calls are repaired, never blindly repeated.
  • Storage that stays small. Hot control.db, cold transcripts.db and content-addressed blobs, with retention on by default.
  • Channels that stay connected. Every adapter runs under a supervisor with a heartbeat watchdog; a stuck socket is torn down and reconnected, not left hanging.
  • Never answers twice. Redelivered messages are dropped, replies are delivered once, and a long reply resumes at the first unsent chunk after a crash.
  • Strict config. Unknown keys are errors, not silent typos.

How it stays up#

  • Durable turns. A message becomes a turn job. Workers claim jobs with a lease and heartbeat while running. Every transcript write checks the lease, so a worker that lost its job can never write.
  • Fast crash recovery. Leases record host and PID; on start, Habakkuk reclaims jobs whose owner process is dead instead of waiting for expiry.
  • Transcript repair. A tool call whose result was never recorded gets an "interrupted, check state first" result, so side effects are not blindly repeated.
  • Model resilience. Errors are classified; transient ones retry with jittered backoff, rate limits rotate keys with cooldowns, and errors another model can fix fall back down the chain.
  • Cache-stable prompts. The system prompt is frozen per session, tools are sorted, the time goes in the user turn, and transcripts are append-only.

Where to go next#

Getting started

  • Installation: the install script, release archives, go install and the container image.
  • Quick start: set up a provider, chat, and the everyday commands.
  • Configuration: config.yaml, keys in .env, and where everything lives.

Guides

Reference

Contributing

Edit this page on GitHub