Agent-HQ (HQ for short) puts one AI agent on every channel you use (Discord, Telegram, a web UI that installs as a PWA, the terminal) and keeps all your data in a markdown vault on your filesystem. Coding agents such as Claude Code, Codex CLI or OpenCode run as supervised harness sessions inside its built-in host (hq host), and so can personal agents such as Hermes and OpenClaw, sandboxed and kept away from code (guide).
No cloud backend. No vendor lock-in. One binary of about 58 MB.
Features
- One agent, every channel. Discord, Telegram, the web UI and
hq chat share one conversation history and one memory, so you can switch platforms mid-thread.
- Markdown vault. Notes, memory, skills and threads are plain files plus a single SQLite database (FTS5 search and embeddings). Nothing is locked inside a service. Notes edited outside HQ (an editor, git, an agent's shell) are picked up within seconds, and every version records who wrote it. See docs/architecture/vault-events.md.
- Coding-agent sessions. Start, watch, steer and resume Claude Code, Codex, OpenCode and others in the built-in host, on this machine or a paired one (macOS, Linux, and Windows through WSL2).
- Sub-agents. Single, parallel, race and graph execution modes over an in-process agent service.
- Native tasks. Spaces, initiatives, tasks and comments, as MCP tools and a list, board and timeline UI.
- Long-running work. Turns that outlive the chat ack window detach and report back;
/watch schedules durable recurring turns.
- MCP server. A 2-tool gateway (
hq_discover, hq_call) exposes the full tool registry to Claude Code, Cursor, VS Code, Copilot and other MCP clients.
- Safety by default. Bash runs in a sandbox with an environment allowlist, untrusted content is tainted, and
/mcp refuses requests without a key.
- Signed self-updates. Servers pull minisign-verified releases and roll back on a failed health check.
- Web search out of the box.
web_search queries Google, DuckDuckGo, Brave, Mojeek and category engines (news, science, images, code) in-process, with no key and no Docker, then merges and ranks the results. Blocked engines are suspended and remembered across restarts, a server can borrow a better network from a peer HQ, and a SearxNG instance or a Brave API key are optional upgrades. See docs/WEB_SEARCH.md.
- Optional integrations. Google Workspace through the
gws CLI, remote MCP servers, local models through Ollama. None are required.
How It Works
You (PWA / Discord / Telegram / Terminal)
|
+-- HQ web app (PWA) --> Tailscale-secured, installable on any device
+-- Discord Relay --> the HQ agent; !cancel to interrupt
+-- Telegram Relay --> the HQ agent, photos, documents; !cancel to interrupt
+-- Terminal Chat --> Streaming REPL
|
v
hq-web (Axum WS + REST, port 5678)
|
v
.vault/ <-- single source of truth
|
+-- _system/ SOUL - MEMORY - CRON-SCHEDULE
+-- _threads/ cross-platform conversation history
+-- _logs/ task logs
+-- _data/ vault.db (SQLite, WAL mode)
+-- Notebooks/ your notes, memories, projects
The vault is the center. Every agent reads from it and writes back to it. Switching platforms mid-conversation does not lose context.
Quick Start
Not a developer? Give AGENTS-SETUP.md to your AI coding agent and ask it to set HQ up for you.
Quickest: deploy on Hetzner with one form
A private, always-on HQ on your own Hetzner Cloud server, about ten minutes from start to chatting.
It costs Hetzner's hourly price for the server, roughly 6.50 a month for a 4 GB machine, and it is
reachable only from your own Tailscale network.
You need a Hetzner account with a payment method, a free Tailscale account with MagicDNS and HTTPS
certificates turned on, an SSH key (ssh-keygen -t ed25519 makes one) and a model API key such as OpenRouter.
- Make a token. In the Hetzner Cloud console create a
project, then Security, API tokens, Generate. Choose Read & Write and copy it once.
- Fill in the form at https://deploy.agent-hq.online: paste the token, then pick a name, a
location, a size with at least 4 GB of memory, your SSH public key and your own IP address.
Click Create server.
- Wait 3 to 5 minutes after Hetzner shows the server as running. It installs HQ by itself.
- Join your tailnet. Run
ssh root@<server-ip> hq-join, open the Tailscale login link it prints
and sign in. It then prints your HQ link.
- Open HQ. Open that link on a device on your tailnet, paste your model key on the first
screen (what it does), and send a message. Treat the link like a password: it signs you in as admin.
- Close public SSH with the button on the form page once HQ opens. When you are done with the
server, the same page deletes it together with its firewall and key.
The form never sees the admin token (the server generates it) and nothing secret goes into the
server's setup data. Troubleshooting, the security model and the hcloud command-line route:
docs/HETZNER.md.
Prerequisites
- Rust 1.89 or newer (2024 edition):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- At least one LLM API key: OpenRouter, Anthropic, or Google AI
Install from Source
git clone https://github.com/CalvinMagezi/hq.git
cd hq
cargo build --release -p hq-cli
install -m 755 target/release/hq ~/.local/bin/hq # any directory on your PATH works
On macOS, scripts/install-hq.sh wraps the same build with code signing and a
launchd service; it is macOS only and not needed on Linux.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
