# Habakkuk

> Habakkuk is an open-source personal AI agent in one Go binary. Message it on WhatsApp, Telegram, Slack and more: it remembers, uses real tools, runs a team of agents, and never loses work to a crash.

Every page below is Markdown. The full docs in one file: https://www.habakkuk.ai/llms-full.txt. Source code: https://github.com/habakkuk-ai/habakkuk.

## Docs

- [Habakkuk docs](https://www.habakkuk.ai/docs/index.md): Install Habakkuk, connect it to your chat apps, and run agents that remember, use tools and work on a schedule.

## Get started

- [Get started](https://www.habakkuk.ai/docs/get-started.md): What Habakkuk is, how it stays up, and where to go first for what you want to do.
- [Quickstart](https://www.habakkuk.ai/docs/get-started/quickstart.md): Install Habakkuk, run the setup wizard, get your first reply in about a minute, and learn the everyday commands.
- [Installation](https://www.habakkuk.ai/docs/get-started/installation.md): Install Habakkuk with the install script for your OS, a release archive, go install or the container image.
- [Updating](https://www.habakkuk.ai/docs/get-started/updating.md): Move to a new release with habakkuk update, follow the beta channel, roll back, and how config and database changes are handled.
- [Configuration](https://www.habakkuk.ai/docs/get-started/configuration.md): How config.yaml is laid out, where keys go, what lives in $HABAKKUK_HOME, and which changes need a restart.
- [Use cases](https://www.habakkuk.ai/docs/get-started/use-cases.md): Eight concrete setups, from a personal assistant on WhatsApp to a team of agents run from Slack, each with the config and commands it takes.
- [Move from another agent](https://www.habakkuk.ai/docs/get-started/migrate.md): Bring your agents, memory, skills, schedules, MCP servers, channels and keys over from another agent with habakkuk migrate.

## Channels

- [Channels](https://www.habakkuk.ai/docs/channels.md): Every chat app Habakkuk can talk on, how each one connects, how much setup it takes, and which one to start with.
- [Access, groups and delivery](https://www.habakkuk.ai/docs/channels/settings.md): Who may talk to the bot, pairing codes, group rules, webhook channels, the settings every channel takes, how delivery works, and what each platform supports.
- [WhatsApp](https://www.habakkuk.ai/docs/channels/whatsapp.md): The three ways to reach Habakkuk on WhatsApp, compared: a WhatsApp agent from Settings > Agents, a linked device on your number, and the Business Cloud API.
- [Telegram](https://www.habakkuk.ai/docs/channels/telegram.md): Connect a Telegram bot in two minutes: long polling with no public URL, groups and forum topics, approval buttons, reactions, polls and voice notes.
- [Slack](https://www.habakkuk.ai/docs/channels/slack.md): Connect a Slack app over Socket Mode: one connection for every workspace, mentions and threads, files, reactions and approval buttons, with no public URL.
- [Discord](https://www.habakkuk.ai/docs/channels/discord.md): Connect a Discord bot over the Gateway: the Message Content intent, invite permissions, servers and threads, buttons, reactions and polls.
- [Signal](https://www.habakkuk.ai/docs/channels/signal.md): Connect a Signal number through a signal-cli daemon: register or link the number, keep the daemon on loopback, and approve people by phone number.
- [Matrix](https://www.habakkuk.ai/docs/channels/matrix.md): Connect a Matrix account with an access token: invites from allowed users, direct chats, rooms and threads; end-to-end encryption is not supported yet.
- [Email](https://www.habakkuk.ai/docs/channels/email.md): Give Habakkuk a mailbox: IMAP with IDLE or polling, SMTP replies that keep the thread, sender checks, and why email sessions start tainted.
- [SMS](https://www.habakkuk.ai/docs/channels/sms.md): Text Habakkuk over SMS and MMS through a Twilio number: the webhook, signature checks, messaging services and media limits.
- [Microsoft Teams](https://www.habakkuk.ai/docs/channels/microsoft-teams.md): Connect a Teams bot through the Bot Framework: the bot registration, the messaging endpoint, single-tenant bots, and how files are sent.
- [Google Chat](https://www.habakkuk.ai/docs/channels/google-chat.md): Connect a Google Chat app with an HTTP endpoint: the Chat API configuration, the authentication audience, and the service account used for replies.
- [iMessage](https://www.habakkuk.ai/docs/channels/imessage.md): Reach Habakkuk over iMessage through a BlueBubbles server on a Mac: the webhook secret, the Private API for typing and replies, and group chats.
- [Web chat](https://www.habakkuk.ai/docs/channels/web-chat.md): The chat page Habakkuk serves itself, and the same chat over a JSON API with Server-Sent Events, for your own clients.
- [More platforms](https://www.habakkuk.ai/docs/channels/more-platforms.md): Set up LINE, Mattermost, IRC, ntfy, Messenger, Instagram, Feishu and Lark, DingTalk, WeCom, Zulip, Rocket.Chat, Nextcloud Talk and Twitch chat.

## Agents

- [Agents](https://www.habakkuk.ai/docs/agents.md): What an agent is in Habakkuk, and where to read about identity, teams, memory, skills, schedules, the board, approvals, sessions and retros.
- [Agents and identity](https://www.habakkuk.ai/docs/agents/agents.md): Define agents, give them a personality and standing instructions, use personas, and how the first-chat welcome lets the user name the agent.
- [Multi-agent teams](https://www.habakkuk.ai/docs/agents/multi-agent.md): Run several agents in one Habakkuk: route conversations to them, switch agents in a chat, delegate to sub-agents, give each a home chat, and talk to agents elsewhere over A2A.
- [Memory](https://www.habakkuk.ai/docs/agents/memory.md): Long-term memory as Markdown notes, the user profile, untrusted notes, semantic search, background review, and a history of every change you can undo.
- [Skills](https://www.habakkuk.ai/docs/agents/skills.md): Skills are SKILL.md folders an agent loads before a task it covers: where they live, how to run and write them, installing outside skills, and the curator.
- [Schedules](https://www.habakkuk.ai/docs/agents/schedules.md): Scheduled prompts and scripts: cron expressions, intervals and one-off times, at most one run per slot, script schedules that skip the model, and where results go.
- [Task board](https://www.habakkuk.ai/docs/agents/board.md): The task board agents use to hand each other work that outlives a conversation: cards, dependencies, dispatch, results back to the creator, and the rules.
- [Permissions and approvals](https://www.habakkuk.ai/docs/agents/approvals.md): Permission modes, how approvals work in chats and the terminal, the approval reviewer model, hooks that can block a tool call, and the guards that always apply.
- [Sessions and chat commands](https://www.habakkuk.ai/docs/agents/sessions.md): How conversations map to sessions: idle timeouts, titles, compaction, fork and rewind, standing goals, export and search, and the chat commands that steer a turn.
- [Retros](https://www.habakkuk.ai/docs/agents/retros.md): Retrospectives: an agent looks back over its own work, finds what went wrong and why from Habakkuk's records, proposes changes, applies the safe ones, and checks next time whether they helped.

## Models

- [Models](https://www.habakkuk.ai/docs/models.md): How Habakkuk talks to model providers, the directory of built-in presets, and where to read about routing, subscriptions, spending limits and speech.
- [Providers](https://www.habakkuk.ai/docs/models/providers.md): Provider types and presets, custom OpenAI-compatible APIs, local model servers, AWS Bedrock, key rotation, fallbacks, and switching models in a chat.
- [Routing](https://www.habakkuk.ai/docs/models/routing.md): Give an agent a fast_model and Habakkuk picks a model for every message: a cheap one for quick messages and chores, a strong one for real work.
- [Decision model](https://www.habakkuk.ai/docs/models/decision-model.md): Use a fast decision model (TypeSafe's Jev) for Habakkuk's own small choices: which model a message needs, whether a tool call is routine, and whether a chat is worth remembering.
- [Subscription logins](https://www.habakkuk.ai/docs/models/subscriptions.md): Use a ChatGPT or GitHub Copilot plan instead of an API key: device-code sign-in, where tokens are kept, and why there is no Claude plan login.
- [Usage and limits](https://www.habakkuk.ai/docs/models/usage-and-limits.md): Tokens and cost by model, agent and session, adding prices, and hard daily, monthly and per-turn spending caps for the install and each agent.
- [Speech](https://www.habakkuk.ai/docs/models/speech.md): Configure speech-to-text for voice notes and habakkuk talk, and text-to-speech for the speak tool and spoken replies.

## Tools

- [Tools](https://www.habakkuk.ai/docs/tools.md): The toolsets an agent can use, which one to reach for, and where each is explained: files and shell, browser, computer use, voice, meetings, media, MCP, plugins and integrations.
- [Files and shell](https://www.habakkuk.ai/docs/tools/files-and-shell.md): The core workspace tools: file reads and edits, exec, apply_patch, search, background processes, Docker and SSH sandboxes, and workspace checkpoints with rollback.
- [Browser](https://www.habakkuk.ai/docs/tools/browser.md): Let agents drive a real web browser: a headless Chrome Habakkuk starts, or your own signed-in Chrome; the tools, URL rules, installing a browser on a server, and safety.
- [Computer use](https://www.habakkuk.ai/docs/tools/computer-use.md): Let agents see a desktop through screenshots and drive it with the mouse and keyboard: the Linux, macOS and private virtual desktop backends, and the safety rules.
- [Voice](https://www.habakkuk.ai/docs/tools/voice.md): Talk to Habakkuk out loud: Live mode in the dashboard, habakkuk talk on a laptop or Raspberry Pi, voice notes in chats, and spoken replies.
- [Meetings](https://www.habakkuk.ai/docs/tools/meetings.md): Let an agent attend Google Meet, Zoom and Microsoft Teams calls as a named guest, read the live captions, and send notes with decisions and action items.
- [Media and web search](https://www.habakkuk.ai/docs/tools/media.md): Read images and documents, generate images and video, and search the web: hosted search on Anthropic models, or the web_search tool with Brave, Tavily, Exa, SearXNG or DuckDuckGo.
- [MCP](https://www.habakkuk.ai/docs/tools/mcp.md): Give agents tools from any Model Context Protocol server (stdio or Streamable HTTP, with OAuth sign-in), add servers from the built-in catalog, and serve Habakkuk itself over MCP.
- [Plugins and outside skills](https://www.habakkuk.ai/docs/tools/plugins.md): Install skills and plugins from GitHub, URLs, local paths and registries: the lock file, the security scan, updates and restores, and the plugin manifest.
- [Integrations](https://www.habakkuk.ai/docs/tools/integrations.md): Connect Habakkuk to other programs: Home Assistant, signed webhooks, Agent2Agent, the OpenAI-compatible API, code editors over ACP, and device nodes.

## Interfaces

- [Interfaces](https://www.habakkuk.ai/docs/interfaces.md): The ways to use Habakkuk besides chat apps: the terminal UI, one-shot commands, the web dashboard, the desktop app, voice, editors and APIs.
- [CLI and TUI](https://www.habakkuk.ai/docs/interfaces/cli-and-tui.md): Chat with an agent in the full-screen terminal UI, its keys and commands, approvals at the keyboard, plain line-by-line chat, and one-shot runs from scripts.
- [Dashboard](https://www.habakkuk.ai/docs/interfaces/dashboard.md): The http section turns on a control dashboard at /app/: chat, sessions, board, schedules, memory, skills, usage, approvals and config, plus the other endpoints the same server offers.
- [Desktop app](https://www.habakkuk.ai/docs/interfaces/desktop-app.md): Habakkuk Desktop: a native window around the dashboard with a tray icon, notifications, quick ask, start at login and a connection manager.
- [Remote CLI](https://www.habakkuk.ai/docs/interfaces/remote-cli.md): Run hk on your laptop against the Habakkuk on your server: save the server as a remote, then hk -r NAME runs any command there over ssh, or status and chat over HTTPS.

## Deploy

- [Deploy](https://www.habakkuk.ai/docs/deploy.md): Keep habakkuk serve running on a server or a home machine: service managers and containers, remote access, security, backups and updates, and monitoring.
- [Run it on a server](https://www.habakkuk.ai/docs/deploy/server.md): Keep habakkuk serve running under systemd, launchd or Docker: the setup service command, unit files, container volumes, ports and keys.
- [Remote access](https://www.habakkuk.ai/docs/deploy/remote-access.md): Reach the dashboard and receive webhook channels from outside: keep the listener on loopback, set a token, and put a reverse proxy, tunnel or Tailscale in front.
- [Security](https://www.habakkuk.ai/docs/deploy/security.md): What Habakkuk lets an agent do by default: approvals for chat-driven and tainted turns, guests, vetted skills, private files, no surprise network calls, a locked-down local server, the audit and secret managers.
- [Backups and updates](https://www.habakkuk.ai/docs/deploy/backups-and-updates.md): Back up and restore $HABAKKUK_HOME while Habakkuk runs, move to another machine, update and roll back, and how retention keeps storage small.
- [Observability](https://www.habakkuk.ai/docs/deploy/observability.md): See what Habakkuk is doing: status, channel health, doctor, the health endpoint, the log, Prometheus metrics and OpenTelemetry traces.

## Reference

- [Reference](https://www.habakkuk.ai/docs/reference.md): Complete lists: every CLI command and chat command, every config.yaml section, the HTTP API, and how Habakkuk is built.
- [CLI](https://www.habakkuk.ai/docs/reference/cli.md): Every habakkuk command and its flags, and every slash command available in a chat.
- [Configuration](https://www.habakkuk.ai/docs/reference/configuration.md): Every section of config.yaml, the settings for providers, agents and channels, and where each one is explained.
- [HTTP API](https://www.habakkuk.ai/docs/reference/api.md): The JSON API under /api/ that the dashboard is built on: chat, sessions, board, schedules, memory, skills, usage, approvals, nodes and config.
- [Architecture](https://www.habakkuk.ai/docs/reference/architecture.md): How Habakkuk is built: layers, durable jobs, storage, models, permissions, channels, HTTP, memory, skills and operations.

## Help

- [Help](https://www.habakkuk.ai/docs/help.md): Answers to common questions, and fixes for common errors.
- [FAQ](https://www.habakkuk.ai/docs/help/faq.md): Common questions about Habakkuk: models, cost, data, privacy, Windows, local models, several users, and what happens on a crash.
- [Troubleshooting](https://www.habakkuk.ai/docs/help/troubleshooting.md): Common problems by symptom, with the exact message Habakkuk prints and how to fix it: config, keys, channels, approvals, budgets, updates and the HTTP server.

## Contributing

- [Contributing](https://www.habakkuk.ai/docs/contributing.md): Work on Habakkuk itself: the codebase map, the brand rules, the roadmap, and the contributing guide.
- [Codebase map](https://www.habakkuk.ai/docs/contributing/codebase.md): A map of cmd/ and internal/: what each package does, where to start reading, and how a message travels from a chat to the model and back.
- [Brand](https://www.habakkuk.ai/docs/contributing/brand.md): How to use the Habakkuk logo files, the colours (ink, cream and gold), and what the mark means.
- [Roadmap](https://www.habakkuk.ai/docs/contributing/roadmap.md): Release phases, what each one ships, and known gaps.

## Optional

- [Pricing](https://www.habakkuk.ai/pricing): self-host for free, Habakkuk Cloud (planned) and done-for-you setup