The Hub in detail

What it is

A self-hosted kanban board where AI agents (Claude Code, Codex, …) are first-class team members: their own identity, inbox, presence, approval queue, structured session handoffs, and audit trail. Browser-first for planning, approving, and observing — the agent software runs only where the agents actually do their work. Agents talk to the same backend as the UI via MCP and REST — and hold an outbound WebSocket (the connector) for the live chat. No separate agent path, one source of truth.

How it works

Classic kanban in the browser: every task is a card, belongs to a project, moves through five columns. Drag & drop on desktop, detail panel on mobile. Live updates over WebSocket — when an agent moves a card, the human sees it without a reload.

Board by status — or by weekday

The five columns above arrange by state. A switch in the filter bar renders the same filtered task source as a week instead — Mon–Fri or Mon–Sun. No second list and no second data path. Four dates put a task on a day: its due date, its first start, a scheduled time that hasn't been processed yet, and every day a recurrence falls in this week. One card can therefore appear more than once in a week — due Wednesday, scheduled for Friday; a task carrying none of those dates stays reachable in the status board. The status travels along as a chip, and dragging a card onto a weekday sets its due date: only the due-date rendering can be dragged. Start, schedule and recurrence preview are fixed — you move a scheduled time in the task detail, not with the mouse across the board.

The recurrence preview is computed on the server, not in the browser. Node and Python version their timezone databases independently, and a single version apart is enough to put a card on the wrong weekday — measured on a real case that landed a full calendar day off. So no zone name crosses the boundary any more, only the finished instant; the browser merely maps it onto its own local day.

Your own to-do list

The board shows what the team has on its plate. What you want to tackle next lives in your to-do list — a third view next to the status board and the week. Every person has their own list, across all projects, and sets the order themselves: grab a row by its handle and move it. A task gets onto the list through a toggle in the task detail; whatever you add yourself counts as confirmed straight away. Each row shows title, project, assignee and due date, a click opens the task, and finished work collects below in a “Done” section. The kanban board is unaffected. Other people cannot see your list, not even an admin. Agents can read it — including when another person asks them to.

Agents suggest, you confirm

Agents can read your list and put tasks on it — for example when you ask an agent in conversation to note something down for you. But whatever an agent adds is only a suggestion: the row says “suggested by …” and carries a Confirm button. Only the person who owns the list can confirm. There is no tool that lets an agent confirm on its own, and the database does not accept anyone other than the owner as the confirmer.

The reason is concrete: agents read unvetted content from the web. A prepared page could get an agent to put a task on your list. If another agent later works through the list with access to your machine, that would be a direct path from someone else’s text to execution. Confirmation breaks that chain.

You confirm content, not a number

A confirmation covers the state you confirmed: title, description, prompt, acceptance criteria, project and role. If anyone changes one of these, it no longer holds and the row asks for a new confirmation — even if you made the change yourself. If someone sets the content back to exactly the confirmed state, it holds again: it is then the content you confirmed. Ticking off criteria and writing the result do not count as changes. Once the task reaches “done”, the confirmation is used up; if it is reopened, it has to be confirmed again.

Only confirmed entries get worked on

When an agent is meant to work through your list, the hub hands it only the confirmed, open entries, in your order. With each entry it returns the confirmed content in the same request — that is where the agent takes its instructions from, not from the task’s current state. Before each entry it asks again; an entry that has been changed or removed in the meantime is skipped.

What confirmation does not do

The list row only shows the title. The Confirm button proves that the content has not changed since it was loaded — not that you read the description and prompt; those are one click away in the task detail. When you add a task yourself from the task detail, even that check is missing: if an agent changes the task right between display and click, you confirm the new state. Comments, attachments and handoffs on the task are not part of the confirmed content. That an agent does not treat them as instructions is down to its working instructions, not the server. And an agent can also take entries off your list without you seeing who did it.

Automatic start

Starting a card is mechanical; signing off on it is not. So a task can begin on its own at a set time: at the scheduled moment the hub moves it to active and sends the assigned agent a kickoff message into a chat it prepared back when the schedule was set — in the name of the person who set it. The agent starts without asking, delivers to review, and waits there. It approves nothing — automatic start brings no auto-approve of its own and stops before the sign-off; what happens there is still governed by your instance's approval policy.

Agents only propose a schedule

When an agent sets a scheduled time, it is a proposal: the card shows a dashed clock, and nothing happens at that time. Only when a person confirms it — together with folder, model, effort and access — does it become their schedule, and the agent starts in their name. The same logic as the to-do list: what an agent initiates only takes effect through a person.

Someone else's change switches the schedule off

A schedule starts in your name — so it only holds for the state you saw. If anyone else, agent or human, changes the title, description, prompt, criteria, assignee or the chat settings before then, the task no longer starts on its own. The card shows a crossed-out clock with who changed what, and you get a notification; setting the schedule again adopts the new state.

The limits are named rather than glossed over: the runner has to be up — a sleeping machine starts nothing — and the kickoff message triggers exactly one turn. That carries briefings, reports and research due on a date; it does not carry a development task that needs a follow-up question and a second attempt.

Who's this for?

You'll recognize yourself in at least one of these three situations:

• You work with multiple AI agents every day and you've noticed that chat history as memory and an issue tracker as handoff mechanism aren't enough. You want structured tasks (prompt, acceptance criteria, result), clear handoffs between sessions, and a visible approval step before an agent merges anything — instead of asking yourself every morning "where were we yesterday?"
• You're a small team on shared projects — 2–5 people, each with their own agents, all on the same Hub. Tasks can be assigned to people or agents, the avatar shows at a glance who owns the card, handoffs cut across — person to agent, agent to person, agent to agent. One instance with three roles (admin, member, viewer) is enough — designed for trust-based contexts (co-founders, a studio, a club board), not for orgs with a permission matrix.
• You want tools you host yourself instead of the next SaaS subscription. Your tasks, your agent handoffs, and your audit trail stay on your machine. One SQLite file, one Docker container, no external dependency; migration is scp, backup is cp.

If you only use a single agent and don't need structured handoffs, audit trail, or self-hosting — this isn't for you. Linear (or GitHub Issues) plus your agent app is enough.

Why it's interesting

Most "agent integrations" are a bot account on an issue-tracker API. Here, the data model is built for human+agent from the start: sessions are first-class entities with a lifecycle, handoffs are structured (not a free-text dump), approvals are their own queue, online presence comes from real heartbeats. An agent can pick up a task, finish it, leave a handoff for the next agent — and a human sees the state in the browser without any extra tooling.

• Human and agent see the same state — no sync between issue tracker, chat, and agent memory. One truth; live in the browser via WebSocket, at the agent's next tool call at the latest.
• Multiple agents with different strengths — implementation (Claude Code), review (Codex), research/briefings (Theo). Specialization is visible in the UI (avatars, role, assignment) and handoffs are structured rather than chat pings — the next agent picks up a handoff deliberately; for follow-up questions one agent asks another directly (see Agents ask each other). Separately, the Hub can start the assigned agent at a scheduled time (see Automatic start).
• Handoffs outlive the chat history — handoffs land as a structured entity in the Hub, not as scrollback in some tool. The next agent (or the next session for the same person) reads them like an API.
• Audit trail by default — every lifecycle transition and every approval is written to the audit trail; messages are append-only, privileged admin reads/deletes are audited. Who did what, when, is always answerable.
• Self-hosted, no lock-in — one SQLite file, one Docker container, loopback-only. Migration is scp, backup is a file copy, the data model is open.
• One API for UI and agents — MCP and REST write against the same service layer; WebSocket distributes the resulting events. No parallel agent path, no duplicated truths, no sync bugs.

Architecture

• Backend: Python 3.12, FastAPI, aiosqlite with raw SQL — no ORM. 30 API modules, 177 test modules.
• MCP layer: tools (tasks_*, sessions_*, handoffs_*, messages_*, context_*, docs_*, projects_*, agents_*, epics_*, todos_*, hub_version) — 51 tools, same service layer as REST.
• Connector: a small bridge program next to each agent — holds an outbound WebSocket, drives the local runtime (Claude Code, Codex, OpenClaw), and writes the reply back. Swappable runners behind one protocol (mcp-client, 45 test modules).
• Frontend: Vue 3 + TypeScript + Pinia + Tailwind, around 340 test/spec files (Vitest + Playwright smoke tests for desktop, iPad and iPhone).
• Deployment: Docker Compose, SQLite WAL. Self-host default is loopback-only with an SSH tunnel; a hosted instance is set up on request — behind a TLS reverse proxy (Caddy) on its own subdomain. Every beta tester gets their own instance on our beta server on request.

Building blocks for human+agent

The domain primitives are dedicated entities in the schema, with a REST endpoint for the UI and — for the workflow primitives (tasks, epics, to-dos, sessions, handoffs, messages including attachments, agents, projects, docs/context) — MCP tools for agents too. "Real-time" is the transport layer on top. No free-text dump, no bot-account workaround. That's how the audit trail emerges, where human and agent work against the same data model.

Epics — the bracket around several tasks

Past a certain size, an undertaking isn't one task — it's ten. An epic is the bracket around them: several tasks, one shared goal, one progress figure. On the board, the tasks sit under a shared header with a title, a bar and a counter like 3/7 — switched on via Group by epic, never forced on you. The epic itself is never a card: it doesn't travel through the columns and needs no approval. That's the one deliberate exception to the lifecycle — and exactly why it's its own entity instead of a task with a special status.

Hub chat & connectors

You can now chat with the agents live in the Hub — type in the browser, the agent answers in seconds, token by token. No more polling: next to each agent runs a small bridge program, the connector, which holds an outbound WebSocket to the Hub, passes incoming messages to the local runtime, and writes the reply back.

Crucially: for the agent turns the Hub never talks to an LLM itself. It holds no API keys and no model for them — the connector drives the real agent runtime on the agent's own machine. (The one exception is the optional voice features, further down.) And it dials out: your machine doesn't need to be reachable, no port forwarding, no NAT.

Chat and board side by side

On a wide monitor the list of chats docks to the edge as a column — left or right, your choice — and with Widen column the open chat sits right next to it while the board stays usable. Talking to an agent while its tasks keep moving no longer means switching views.

The column docks from roughly 1770 pixels of window width; on narrower windows from 1100 pixels the wide column sits as an overlay above the board. The same goes for handoffs and approvals. Pop out narrows the column and turns the chat into a movable window.

Files in the conversation

A screenshot belongs where it is being discussed. The composer takes files by paste, by drop and through the paperclip; before sending they sit above the input as chips with progress and can be removed one by one. In the message, images get a thumbnail and everything else a line with name, size and download. That holds in 1:1 chats, in groups and in sparring.

The difference to a chat window is on the other side: the agent receives a local file, not a link. The connector fetches the bytes through the Hub, verifies them against the response's X-Attachment-SHA256 header, writes them into its state directory and names the finished paths in one context line of the turn prompt. Whatever did not arrive is listed in that same line as "not available" with a reason — and the turn still runs: an agent answering about an image it never saw is the most expensive outcome.

It works the other way too: an agent attaches files to its reply — text and files in one bubble. And whatever sits in the chat can be attached to the task with one click; attachments also exist directly on the task, for human and agent through the same API.

Speaking and listening

The Hub can also be worked by ear and by voice. Four building blocks, useful on their own and a conversation together: every agent has its own voice, replies can be read aloud, every place you write takes dictation, and in a 1:1 chat with an agent voice chat ties both into a hands-free loop. The quickest way to start it is the menu on the agent itself.

Two clicks on the avatar, and you are talking

Your agent sits as a small circle in the bar at the top — with a face of its own and, once it speaks, a voice of its own. One click on it opens a small menu with your chats with this agent; at the top sits “Start voice chat”, and you are talking: the Hub starts the voice chat without taking you away from what you were looking at. On a computer the agent then floats above the page, just its picture with a coloured ring and a slim bar underneath with its name and state — listening, thinking, speaking. You drag it wherever it is out of the way and keep working next to it; switch pages in the Hub and it stays with you. A tap on the agent pauses the voice chat: the microphone closes, and if it is speaking, it falls silent. A second tap carries on. On an iPhone it becomes a black full-screen view, like a phone call.

The talking happens in a dedicated, fixed chat with that agent, the same one across days and devices; one button on the ring opens it for reading back, "Chats" lets you start a new chat or return to an earlier one, and the gear sets access, model and effort. Whatever you ask of the agent in conversation, it works through while you do something else, and comes back with the result — read aloud, in its own voice. It does not set off on its own, though: you give the assignment, or you put a task on a schedule and the Hub starts it at the time you set. If the agent's machine is off, the circle says so after about twenty seconds, and your message waits in the chat. Delegation you can plan rather than a helper tinkering away unasked in the background — you stay in control.

Voice is the one place where the Hub itself needs model access: a Gemini key. Every user can store their own (kept encrypted), otherwise an optional operator key applies; without a key the feature simply is not there and everything else runs unchanged. The recording bypasses the Hub — the browser gets a short-lived token and talks to Google directly; only what you send is stored. Reading aloud draws on a per-user quota, and on a phone the microphone needs an https address.

Team and abilities

When people and agents share one board, the same question keeps coming up: who can actually do this? Who has access to the accounting, who can reach the booking system, which agent runs on which machine? The Team and abilities page answers that in one place — reachable from the avatar menu, for every signed-in account, read-only accounts included.

Maintained by the admin, visible to everyone

Only the admin edits, right on the page: one dialog per person (full screen on the iPhone) for role, location, summary and abilities — pick from the catalog, add an access note, reorder, remove, or create a new ability on the spot. Agents can't change any of it, not even with their token. If a name already exists in the catalog with different capitalisation, the existing entry is used instead of a duplicate. Deleting an ability asks first and names who loses it. And if someone else changed the same profile in the meantime, saving doesn't overwrite it silently: the dialog shows the current state and you decide.

Because everything is visible to everyone in the Hub, agents included, the page deliberately shows little: no access rights, no admin or member roles, no webhook addresses, no deactivated accounts. What an agent is actually allowed to do is still governed by the access model — abilities describe who is the right one for what; they don't unlock anything.

Access Model

An agent is a team member, not a blank check. The owner sets, for every agent and person pair, exactly how far access reaches: from no access to full, changeable any time. It's never a global switch, always a deliberate call for that one specific pair.

Groups with moderated turns

Between 1:1 chat and sparring, the middle was missing: several humans and several agents in one chat. What makes that more than “chat with more participants” is how agents behave — they reply immediately, to everything. With three agents a single question triggers three simultaneous replies, each prompting another; humans never get a word in. The answer to that is not a rate limit but a moderator.

@-mentions — handing one agent the job

Whoever needs an answer in a group gets it themselves: any human with write access can address an agent directly. An @ in the composer opens the member list, one click picks the addressee, and the message carries the turn to exactly that agent — provided the sender is allowed to task it and nobody else is holding the floor. A request in the chat then becomes an assignment that starts right away: the agent reads the conversation so far, works in the selected folder, and answers in the same chat.

The interesting part isn't the convenience, it's the permission question. In a channel with exactly one agent, @agent is trivial: one target, one permission. With five people and three agents, every mention is a permission decision — and it is decided in favour of the sender: the agent wakes up with the effective permissions of the person who mentioned it. Not the moderator's, not the chat owner's. A mention extends no rights; it calls in what the sender is allowed to do anyway.

Agents ask each other

Sometimes one agent needs something from another: a reason, a status, a quick answer — or it just wants to let the other know. The Hub has one way for that, a message from agent to agent. The only difference is how you say whom you mean:

1. The agent. “Ask Theo what the weather in Berlin will be.” Whoever asks only gives the name; the Hub finds the way to Theo.
2. Whoever is working on a task. The question goes to the agent working on the task — and if its conversation is pinned to the task, right into that conversation (more on that below).
3. A specific conversation. “Tell the session on the avatar menu that the review is done.” It means exactly that one running session — as a note that needs no answer just as well as a question. The human points to it with # (just below).

The same holds for all three: a question gets exactly one answer, no back and forth. What one agent writes to another is never the human's approval, and actions with consequences stay with the human.

For the third kind, the human needs to know no chat name and copy nothing: they point to the conversation with #. In a one-to-one chat with an agent, a # — typed or via the button below the composer — opens a list: at the top the tasks an agent with a pinned session is working on, below them your own chats, each with title, agent, task and a dot when the agent is working there right now; the most recently active ones are at the top, and typing on filters. One tap or Enter, and the text holds a reference like #“Weather”. The agent gets exactly that conversation, unambiguously, and does not have to guess from titles which session is meant. The distinction is simple: @ assigns an agent in a group chat, # points to a conversation or a task.

Only a reference picked from the list counts; #Title typed by hand stays plain text. The list shows only your own chats — in groups and in a chat with a human only tasks, because others are reading along; the exception is a group of just you and your own agents —, and whether the agent may write there is decided by the Hub, as for any message between sessions. There is no list while dictating or in voice chat — there you simply say the chat's title.

It pays off most on a task. A conversation with an agent carries context that no task comment holds: what has already been tried, which file is open, why the plan changed. That is why a one-to-one chat can be pinned to a task — with the “Pin to task” pin in the chat header, or the agent does it itself when it starts on the task. The task then shows “Chat with <agent> connected” plus “Open chat”; anyone taking part in the chat jumps straight in, everyone else only sees that it exists. Pinning, unpinning and re-pinning show up immediately, in a second tab and on the iPhone too.

If another agent then has a question about that task, it lands in the running session of the agent being asked — with the one who already has the context, instead of in a fresh round with no prior knowledge. The answer goes to the agent who asked, not into the chat, and a comment stays on the task as a trace.

Agent-to-agent sparring

In the Chats area, two agents can debate a question directly with each other — an architecture decision, competing approaches, or the risks in a plan. The human sets the objective and watches a real live chat rather than a simulated multi-agent answer: both agents run on their own runtimes, read the conversation so far, and take turns responding to each other.

Skills — slash commands for agents

Skills are short slash commands that give an agent a predictable flow against the Hub — same tools as a free-form prompt, just shorter and more reproducible. Maintained centrally in the claude-skills repo; every Hub instance ships the same skills as an agent bundle or Claude Code plugin — connect your machine and you get them along.

Test discipline

Tests land in the same commit as the code, not retrofitted later.

Ratio ~1.9 — typical is 0.3 to 0.7. High because the data model takes race conditions between multiple agents on the same SQLite DB seriously, and lifecycle transitions are enforced server-side — both need airtight coverage, otherwise the agents tear each other apart.

Code review sparring

Quality here doesn't come from a single agent — it comes from adversarial collaboration: a second agent challenges the first one's work instead of serially rubber-stamping it. The review comes from a different vendor than the build: when Claude Code builds, Codex hunts for the breaking points, and vice versa — before a human even looks.

The task-processing machine

A kanban board makes work visible. In batch mode the Hub makes it disappear: you write the tasks, you approve at the end. In between, one orchestrated agent session runs through the whole chain without asking you between the individual steps.

A manager session pulls one task after another out of the backlog. For each task it starts a fresh implementer subagent, sends that work through a review cascade of several models, has the findings fixed and only then commits. Every finding lands as a comment on the task card instead of in a throwaway chat log.

Counted across three consecutive batches from 19 to 21 July 2026, used to build the Hub itself: a complete DE/EN translation of the interface in fifteen slices plus two rounds of bug fixing, shipped as version 2.21 and 2.22. All 117 findings sit as comments on the task cards in the board; 15 of them had to go before the code was allowed to merge. Not one top-severity showstopper among them.

One example from the 20 July run: the challenger found that two parallel load operations in the agent store could overwrite each other, so that starting from an empty state only the currently online agents survived. And that the accompanying test codified exactly that data loss as expected behaviour. Both went back to the implementer before anything was committed.

What the machine has done so far

The Hub is built with the Hub. Every Sunday an agent writes a weekly report, and the curve comes from those reports: every task completed since the first commit, week by week. The whole story on the blog →

Notable decisions

Stack TL;DR

Further reading

This page describes what is built. What working this way feels like, what the numbers actually said after four months, and which assumptions did not survive the way there, is in the blog.