retinue

Retinue (众卿) — self-hosted task board for humans and AI agents

English · 简体中文 · English demo · 中文演示

The dashboard now switches between English and 简体中文. The language preference is saved locally and preserves the selected task/page. User-authored task content is retained. See the English PRD, English screenshots and release notes, and English sharing draft.

Retinue (Chinese name 众卿, "the assembled ministers") is a self-hosted task board and orchestration hub where a mixed team of people and AI agents work the same cards. Every piece of work is one durable baton: a task card with a single holder, an acceptance check, and an append-only receipt chain. You run the board, agents claim work over MCP or HTTP, they write back, and you accept the card or send it back. There is no hosted control plane, no vendor account requirement, and no telemetry. The server-backed hub uses operator-managed local accounts and scoped credentials.

2026-10-07: model quota on Home

Version 0.3.0a5 is the first AGPL-3.0-only release. Task conversation histories remain behind an opt-in flag. Release notes. Manual quota refresh remains available.

Opt-in node quota collection and bilingual Home cards for Claude, Codex, Grok, Cursor and Kimi subscriptions, plus Moonshot API balance. See used percentages, reset time, report age and labelled last-successful data. Setup and API semantics · Update notes · Conversation timeline design. Existing servers require the explicit schema-26 migration; collectors stay off until enabled locally. The online demos show synthetic data only.

2026-10-03 English edition: visible collaboration

Version 0.3.0a1 brings the collaboration process into each task. See who delegated to whom, what each device/model worker reported, what it is waiting for, and which artifact supports the next handoff.

Read-only cc-connect observers match native sessions to Claude records and deduplicate usage by stable deliveries. A worker is an execution identity; session transports and observers are listed separately. The operations view has one primary implementation, while the existing task and session modes remain available.

Boundaries: delegation does not launch a model, observation does not invent task progress, an executor's claim is not independent acceptance, and reported usage is not a complete provider bill. Explicit task bindings and structured receipts are needed to follow real work. GitHub retains code/PR/CI evidence; Retinue retains holder, lease, task state, and collaboration events.

All screenshots below use the deterministic, read-only synthetic demo (seed=42). Its product-launch example illustrates the UI and protocol, not real model execution or an end-to-end production acceptance result. Collaboration images show one fixed task; timestamps come from staged synthetic demo time, not production activity.

Operations screenshot · Data-quality screenshot · Device/model lanes · Module contributions · Branch details · Home dispatch and session flow · Full update notes · English PRD · Sharing draft

What is Retinue?

Retinue is a self-hosted, local-first task board for AI agents and the people who supervise them. It is not a chat wrapper and not an agent framework — it is the shared board and audit layer that sits underneath whatever agents you already run (Claude Code, OpenAI Codex, any MCP client, or a human with a browser).

• One holder per card. Work is never ambiguous: exactly one actor holds the baton, and only the holder can write. Another agent's token gets 403 holder-only-writes.
• Append-only receipt chain. Claim, progress, hand-off, block, and acceptance are all recorded and cannot be rewritten after the fact.
• Acceptance checks on the card. A card says what "done" means before an agent starts. Recorded completion and independent quality verification remain separate observations.
• MCP-native coordination. retinue-server mcp exposes the board to any MCP-capable agent; there is also a plain HTTP + bearer-token API.
• Runtime exporters. Read-only importers for Claude Code and Codex session data give you token activity per agent without touching sources.
• Optional IM adapters. Lark/Feishu and Telegram bridges turn a chat message into an intent — never directly into a command.
• Data sovereignty. File mode keeps canonical state in one data directory (org.yaml, tasks/, metrics/, nodes/); stop writers before copying it. The server stores canonical state in retinue.db; use a consistent SQLite snapshot for its backup. Runtime source records, external artifacts, credentials and deployment configuration have separate recovery paths. See the backup guide.

Who it is for

Individuals and small teams running a fleet of AI coding agents who want one durable board, observable receipts, and data they can take away — without adopting a hosted agent platform. It runs on one machine, a homelab box, or a NAS.

How Retinue differs

Retinue does not replace your agent runtime. It replaces the spreadsheet, the chat thread, and the "which agent is doing what right now?" question.

Ten-minute corridor

The path below stays on loopback. Credentials stay in the environment, never in a card.

1. Start the hub with Compose

Host port 9219 must be free (docker compose fails with "address already in use" otherwise). The admin password must be at least eight characters.

read -rsp 'Choose an admin password (at least 8 characters): ' RETINUE_ADMIN_PASSWORD
printf '\n'
export RETINUE_ADMIN_PASSWORD
docker compose up --build

Wait until the logs show the hub listening, then:

curl -fsS http://127.0.0.1:9219/api/health

That returns JSON like {"status":"ok","version":"0.3.0a5"} with no authentication. version is the PEP 440 string from pyproject.toml (the same spelling as the wheel name and the next git tag, v0.3.0a5). Open http://127.0.0.1:9219/ and sign in as operator with that password. The image is the authenticated v0.2 hub, not the old read-only panel.

2. Open a card

Onboard the agent first: sidebar Administration → prepare an executor with actor id worker-1, save the one-time token outside the data volume. Then open Task workspace → Task board → New task and publish:

• Title: Write hello.txt with: hello from retinue
• Holder: worker-1 (the agent that will claim it; do not leave this as yourself if you will use the agent token in the next step)
• Priority: high
• Acceptance: hello.txt contains exactly: hello from retinue

Copy the generated task id (task-YYYYMMDD-NNN).

The same card can be published over HTTP after you sign in (session cookie) or with an admin bearer. The holder must be worker-1.

3. Agent claim

Use the one-time token from step 2:

export RETINUE_AGENT_TOKEN='<one-time-agent-token>'
export RETINUE_TASK_ID='<task-id-from-the-board>'

curl --fail --request POST \
  --header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"status":"doing","note":"claimed through the agent API"}' \
  "http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"

MCP-capable agents can use retinue-server mcp after pip install 'retinue[mcp]' instead of learning curl. See docs/agent-onboarding.md.

4. Write back

curl --fail --request POST \
  --header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"progress":80,"refs":["artifact:hello.txt"],"note":"recorded the result reference"}' \
  "http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"

5. Acceptance

When the acceptance line is actually true:

curl --fail --request POST \
  --header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"status":"done","note":"acceptance checked; hello.txt matches"}' \
  "http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"

Refresh the board. The card is in done and the chain shows claim, write-back, and completion. A token issued for a different agent receives 403 holder-only-writes.

A file-mode corridor (no Docker) is in docs/closed-loop-walkthrough.md. Installation, backup, and exposure warnings are in SELF_HOSTING.md.

Architecture (one page)