Naming note: the product is Muster. The CLI is bin/elk-os and the env
vars are ELK_OS_*, from the project's working name. Renaming those is a
tracked decision, not an accident. They refer to the same thing.
Claude Code is stateless; your business is not. Muster keeps the records that
outlive a session in a Directus you host, and gives your agents a door into them
over MCP. The row you check in the portal is the row an agent can update while it
works.
git clone https://github.com/AnalogElk/muster.git && cd muster
./bin/elk-os init --profile generic # generate secrets + .env
./bin/elk-os up # docker compose up the whole stack
./bin/elk-os migrate && ./bin/elk-os seed # os_* schema + profile data
./bin/elk-os wire # point Claude Code at this deployment
./bin/elk-os doctor # per-subsystem health report
Docker is the hard dependency. migrate and seed also use stdlib python3;
building the portal image locally additionally needs git, node, and perl on
the host, and prepare-context.sh preflights them with the alternatives spelled
out. Secrets are generated into a gitignored .env and never printed.
Fresh-clone note: a fresh clone gets the Directus record layer. The portal
image elk-os-portal is private, so a clone cannot pull it. Building it needs a
local checkout of analog-elk-front-end (see portal/), which is
not public. The portal is shown in the live demo and is not yet public. The
default is ELK_OS_WITH_PORTAL=true, and up stops without a portal source.
Before the first up, edit .env and set ELK_OS_WITH_PORTAL=false. Directus
and the records then stand up.
What is in it
The schema ships 50 snapshot entries: 38 os_* collections, 6 support tables,
and 6 groups that only organize the Directus sidebar
(KEPT-AND-PRUNED.md). They add up to
five desks and a second front door.
| Desk | Holds |
|---|
| Delivery desk | Projects, tasks, sprints, releases, repositories. What's claimed, what's blocked, what actually shipped. |
| Money desk | Deals, proposals, invoices, payments, expenses. A ledger, not accounting software. |
| Studio operations | Organizations, contacts, activities, support, messages, your own inbox. The studio's records, not its employment paperwork. |
| Retrieval | A local retrieval service over your records. The base snapshot has no knowledge-base (kb_*) or asset-library (dam_*) collections. |
| Operations view | One dashboard over the rest: site, portfolio, delivery, and infrastructure analytics, plus a cost ledger for what the agents spent. |
| Client portal | The second front door. Clients sign in to the same records, scoped to what they may see. |
The four subsystems
One elk-os up stands up four wired pieces:
| Subsystem | What it is |
|---|
| The Claude Code connection | A governance file (CLAUDE.md), an MCP bridge, SessionStart hooks, and persistent memory, rendered per deployment by elk-os wire. |
Directus + os_* | The shared record store. Directus's native MCP server (/mcp) is the agent's door to it. |
| The retrieval engine | A local RAG service (Postgres + Qdrant + Redis + FastAPI) plus the in-portal assistant, answering over your own knowledge base and record data. Embeddings run on the box. |
| The portal | The human surface, team and client, a Next.js app over the same os_* records. |
The loop, concretely
┌─────────────────────────────────────────────────────┐
│ Directus + the os_* records │
│ (tasks · sprints · projects · releases) │
└───────────────▲───────────────────────▲─────────────┘
drags a card in │ │ reads/writes via the
the portal │ │ native Directus MCP (/mcp)
┌──────┴──────┐ ┌──────┴───────────┐
│ Human │ │ Claude agents │
│ (portal) │ │ (wired CLAUDE.md)│
└─────────────┘ └──────────────────┘
elk-os wire enables the native MCP server (settings.mcp_enabled), writes a
.mcp.json pointing Claude at this deployment's Directus, and proves the loop
by reading seeded os_tasks back through the same endpoint and token. doctor
then walks every subsystem, including a live tools/list probe against /mcp
(a WARN until wired), and exits nonzero on any red row.
As a Claude Code plugin
The plugin connects to a board you run. It needs a board URL and a Directus API token. The public demo is a static snapshot and cannot be connected to:
/plugin marketplace add AnalogElk/muster
/plugin install muster@muster
/muster:connect https://your-board.example.com
Two commands to install, then one to connect with your board URL. Four slash commands
(connect, board, up, doctor), one skill, one SessionStart hook, and one
MCP server connection, all named in
.claude-plugin/plugin.json. The first MCP tool
call asks you to approve it, once. There is no zero-click connection.
Why not just a plain Claude Code session?
A plain session is the right tool for a large class of work. Muster is what you
wrap around it when the work is multi-session, ships to others, and cannot be
reviewed line by line:
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
