bot-hq

The problem

One AI assistant is fast — but unaccountable.

It can confidently ship a plausible-looking bug, forget your project's conventions, or rewrite a file you didn't want touched. bot-hq is built around three ideas that fix that.

Work in phases, not a scroll

IPAV — Investigate, Plan, Apply, Verify. Every substantial task walks the four phases, and each phase leaves a short document behind. You read the agents' own account, not chat archaeology.

A document trail that outlives the chat

Session documents carry the task's working state; the Context Library carries what your project taught you across sessions; policies carry the rules — enforced by git hooks, not vibes.

A UI built to watch it all

Phase tabs, a live color-coded diff, a visible terminal, and a tray where questions and approvals park for you. Pushes and risky commands pause; everything else flows. You decide when work is done.

Composition is yours

Any roles. Any workflow. Enforced, not suggested.

A session runs the participants you pick — one, or several — each playing a role you own: its instructions, its capabilities, its model. A role's capabilities are enforced at the tool layer, so the boundary you draw is a real one, not a polite request.

e.g. · an executor

Does the work

Writes code, runs commands, makes commits. One classic composition pairs it with an adversarial reviewer — but a solo executor, a panel of specialists, or anything else you dream up is just another roster.

e.g. · a reviewer

Pushes back

Reads the work and challenges it. Strip its write capabilities and it literally cannot edit files — review only, no surprises. Run it on a different model for a genuine second opinion instead of an echo.

You · the conductor

Commands the session

Give the task, answer what the agents park for you, approve the steps that need a human, call it done. Whatever the roster, they don't run off on their own.

Roles are templates you keep — write the instructions once, tick the capabilities, pick a default model, and reuse them across every session. A fresh install starts with one neutral role and offers an executor/reviewer example pair you can take or skip.

How a session flows

IPAV — and you can watch it happen.

Every substantial task walks through four phases. Each one leaves behind a short write-up you can open — so you read the agents' own account instead of scrolling back through chat.

Investigate

Read the code, the docs, your project notes. Gather facts — nothing changes yet.

Plan

The approach and its tradeoffs are proposed — and challenged — before any code is written.

Apply

The work gets produced — the actual edits, commits, and commands, or whatever the task's deliverable is.

Verify

Check the result against the plan: run tests, read output, proof-read adversarially.

The session view has an I / P / A / V tab for each phase, holding that phase's session document. The Apply tab also renders a live, color-coded git diff of the work — so you can eyeball the real changes at a glance. IPAV isn't bureaucracy: it's how an AI change is stopped from shipping on momentum.

The part most AI tools are missing

The Context Library

A curated knowledge base your agents read before they start working — the things that aren't in the code, that a fresh assistant would never know.

Conventions — how this project does commits, tests, formatting, branching.
Gotchas — the trap that bit you last time, the flaky test, the file that looks dead but isn't.
Project memory — decisions you made and why, so they don't get re-litigated every session.

You curate it in a dedicated tab; agents read it on demand and only ever write back in one narrow, audited way. The knowledge base stays yours.

📄 conventions.md house style, gates

📄 notes.md gotchas, where-things-live

📄 decisions.md why we chose X

📄 policy.yaml enforced gates

Guardrails

Move fast — without shipping a regret.

bot-hq is the policy layer. Enforcement runs at two layers (the agents are told to check, and git hooks enforce it independently), so a guardrail holds even if an agent's attention drifts.

↑

Push approval

Pushes can pause for a one-click Approve / Reject, so nothing reaches your remote without you.

✓

Review sign-off

When the reviewer flags a real problem as blocking, the executor can't commit over it until it's resolved or explicitly rebutted.

⌘

Sensitive commands

Gate specific commands by keyword so they ask before running — and isolate each session in its own git worktree so parallel work never collides.

Get started

Run your first session.

Download the desktop app for your platform, or build it from source. You'll also need the claude-code CLI, which bot-hq drives under the hood.

⬇ Download a release Install notes

# …or build from source
git clone https://github.com/gregoryerrl/bot-hq.git
cd bot-hq
cp .env.example .env
(cd frontend && npm install && npm run build)
cargo run   # builds + opens the app
      