Agent HQ Install
Open source Local first Version 0.9.x

One agent. Every channel. Your machine.

Agent HQ (HQ for short) puts one AI agent on Discord, Telegram, a web app and your terminal. It keeps your data in a markdown vault on your own disk and supervises the coding agents you already use. One Rust binary of about 58 MB. No cloud backend.

curl -fsSL https://agent-hq.online/install.sh | bash
Install guide How it works View on GitHub

Supervises the coding and personal agents you already use

  • Claude Code
  • Codex
  • Cursor
  • OpenCode
  • Pi
  • Copilot CLI
  • Kimi
  • Qwen
  • Antigravity
  • Hermes Agent
  • OpenClaw
  • Discord
  • Telegram
  • Web app
  • Terminal
  • MCP server
  • Markdown vault
  • Signed releases
  • Sub-agents

How it fits together

Four ways in, one agent, one vault

Every channel reaches the same agent loop, and the agent reads and writes the same vault. That is the whole idea. The architecture page goes through each part.

  1. Ask from anywhere

    Discord, Telegram, the web app and your terminal share one conversation history and one memory. Start a thread on your phone and finish it at your desk.

  2. One agent does the work

    Sub-agents run single, parallel, race or graph. Long turns detach and report back when they finish.

  3. Everything lands in your vault

    Notes, memory, skills and threads are plain markdown on your disk, plus one SQLite database for search.

Flat isometric illustration: four doorways shaped like a speech bubble, a paper plane, a browser window and a terminal, all opening onto one shared room with a round table.

What it does

What HQ is built around

One agent on every channel

Discord, Telegram, a web app that installs as a PWA, and your terminal share one conversation history and one memory. Start a thread on your phone and finish it at your desk.

A vault you can read

Notes, memory, skills and threads are plain markdown files on your disk, plus one SQLite database for full-text search and embeddings. Nothing is locked inside a service.

Coding agents under supervision

Start, watch, steer and resume Claude Code, Codex, OpenCode and others inside the built-in host, on this machine or a paired one. Personal agents such as Hermes and OpenClaw run there too, sandboxed and kept to research, review and monitoring. HQ tells you when one blocks. It never answers a trust prompt for you.

Tasks and sub-agents

Spaces, initiatives, tasks and comments are built in, with list, board and timeline views. Sub-agents run single, parallel, race or graph. Long turns detach and report back, and /watch schedules recurring ones.

Web search with nothing to set up

web_search queries Google, DuckDuckGo, Brave, Mojeek and engines for news, science, images and code, all inside the hq process. No key, no Docker. Blocked engines are suspended and remembered, and a server on a blocked address can ask a peer HQ.

An MCP server for your tools

Two tools, hq_discover and hq_call, open the whole registry to Claude Code, Cursor, VS Code, Copilot and other MCP clients. Remote MCP servers can be bridged in the other direction.

Safe by default

Agent shell commands run in a sandbox with an environment allowlist. Untrusted content taints a session and cuts off secrets and outbound network. Servers update from signed releases and roll back on a failed health check.

See it

The web app, on your own server

The HQ home screen: a vault search box, recent project notes as cards with tags, and a list of in-progress tasks.
The home screen: search, recent notes and in-progress tasks in one place. Demo data.
The HQ Sessions page: a list of three supervised sessions (opencode, and two claude-code) with host and status, and the selected session's terminal output below its header.
The Sessions page: each supervised session with its host and state, and the selected one's terminal. The agents here are scripted stand-ins on a demo instance.
The tasks board with cards in To do, In progress, Blocked, Ready for review and Complete columns.
The tasks board: spaces, initiatives and tasks as a list, board or timeline. Demo data.
The vault explorer listing notebook folders beside a markdown note about webhook retries with a text code block.
The vault browser: plain markdown notes on your own disk, searchable. Demo data.
A short recording of the Sessions page: the terminal output of one session keeps growing as new lines arrive, then switches to a second session.
Watching a session: the pane refreshes every three seconds, and you can switch between sessions. Scripted stand-in agents on a demo instance, about 11 seconds.
From nothing to a working install: the install script, hq install and hq doctor (about 25 seconds, waiting time cut).

Where it runs

Run it where it suits you

HQ is one binary and a folder of markdown, so it goes wherever you have a machine that stays on. Pick a host now and move later: the vault is the same everywhere.

  • Your laptop or desktop

    macOS (Apple Silicon and Intel) or Linux

    One command installs a signed binary and the web app. On a Mac, hq service install keeps the daemon running and starts it at login.

    curl -fsSL https://agent-hq.online/install.sh | bash

  • A server

    Any Linux VPS, or a Hetzner server from a short form

    Always on, updates itself from signed releases every ten minutes and rolls back when a health check fails. Reach it privately over Tailscale.

    Server options

  • Docker

    One container, amd64 and arm64

    The image runs HQ with its web app and prints a sign-in link on first start. The vault lives in a volume.

    docker run -d -p 127.0.0.1:5678:5678 -v hq-data:/data ghcr.io/calvinmagezi/hq

  • Windows

    Full HQ in WSL2, or HQ Lite with no admin rights

    The PowerShell installer asks which one you want. Lite keeps your notes, tasks and web app, and never makes a network call it does not list.

    irm https://agent-hq.online/install.ps1 | iex

  • An Android phone

    Preview

    Developer preview

    A phone in a drawer can be the always-on host: the daemon, both chat relays and the web app run on it, with a data saver for metered plans. Coding agents still run on a laptop or server, and the phone supervises them.

    See the phone app

Android app ยท developer preview

HQ on your phone, not just pointed at it

The Android app runs HQ itself as a foreground service: chat, tasks, notes, an inbox of things that need your OK, and the coding agents working on your other machines. Pair a laptop with a QR code, and connect Claude from the phone.

  • Phone screen: a chat where HQ answers a question, then lists the steps it is taking: checked your tasks, read a note, writing the steps. Chat
  • Phone screen: the Today tab of Tasks, with tasks waiting on you, one ready to check, and work in progress. Tasks
  • Phone screen: the Inbox, where a coding agent asks to edit one file and HQ offers Allow once or Not now. Inbox
  • Phone screen: a coding agent on a Mac mini building an app, with what it has done so far and a field to tell it something. Helpers
  • Phone screen: a note from the vault open for reading, with Ask HQ, Make a task and Pin actions. Notes
  • Phone screen: Keep running, which checks the Android battery and permission settings that let HQ stay on. Keep running

Screens from the design preview of the native app. The app in the repo today wraps the same web app, and these screens are where it is going.

Works today

  • Full HQ on a phone with the mobile profile: daemon, Telegram and Discord relays, web app, sub-agents
  • A data saver for people who pay for every megabyte
  • Pairing other devices with a QR code, and recovery when the network changes
  • Keys held in the Android Keystore, and a Connect Claude screen

Not there yet

  • No published app: you build the APK yourself and install it with adb
  • Not yet shown that a sleeping, unplugged phone always answers in time, so keep it on a charger
  • No agent shell on the phone: Android has no sandbox HQ can use, so that tool is refused
Build the Android app How the mobile edition differs

Local first

Your data is a folder you can open

Notes, memory, skills and threads are plain markdown files on your disk, plus one SQLite database for full-text search and embeddings. Nothing is locked inside a service.

Markdown vault SQLite and FTS5 No cloud backend
Flat isometric illustration: a laptop on a desk whose screen spills a stack of document cubes that grow into a small block city.
  • .vault/
  • Notebooks/
  • skills/
  • _mailboxes/
  • _data/
  • vault.db

Install

One command to install

A signed binary for Linux and for Macs on Apple Silicon or Intel, plus the web app. Then scaffold a vault, add one model key, and let doctor send your model a real test request.

  1. 01Installcurl -fsSL https://agent-hq.online/install.sh | bash
  2. 02Vault, config and a model keyhq install && hq env
  3. 03Check it answershq doctor
All install options

Version 0.9.x

HQ is early

Expect rough edges and changes between releases. Defaults have tightened since 0.9.0: the bash sandbox is now required by default, and chat relays no longer adopt the first sender as owner.

It talks to Discord and Telegram, not Slack or WhatsApp. Signed release binaries are built for Linux (x86_64 and ARM) and for Macs on Apple Silicon and Intel. The Android app is a developer preview you build yourself. The changelog lists every upgrade note.