@hummer98/elevens

elevens

c11-native multi-agent orchestration package — successor to cmux-team.

Status. elevens is the successor to cmux-team, migrated from manaflow-ai/cmux to Stage 11 Agentics' c11 as the substrate. As of v0.9.0 (T016) the legacy cmux backend has been removed and c11 is the only supported substrate (see Substrate). For the full migration history and phase schedule, see docs/seed.md.

日本語版 README はこちら

Demo

https://github.com/user-attachments/assets/1d402a69-f48c-4a43-b52d-9c80f0f90ea1

Why elevens?

Claude Code's built-in sub-agents are useful, but you can't see what they're doing. You only get the final result — the process is a black box.

This matters more than it might seem. When AI agents work invisibly, two problems compound:

• Late detection: You only discover something went wrong after the work is done — wasting compute and time, with no way to intervene mid-course
• No improvement signal: Without seeing intermediate behavior, you can't tell why a result was good or bad — which makes it hard to improve your prompts, tasks, and agent design

elevens is an AI observatory, not another automation black box. The terminal panes aren't decoration — they're the product. A 10-second glance at a Conductor pane is often enough to catch a problem that would otherwise only surface at the end.

To peek into another project's runtime state without leaving your shell: elevens status --project-root /path/to/other (read-only by default; cross-project writes require --project-root-confirm or CMUX_TEAM_PROJECT_ROOT_CONFIRM=1).

The design principle: reduce cognitive load by making the process visible, not by hiding it.

What you do: Give Claude instructions in natural language. What Claude does: Splits panes via c11, launches sub-agents, monitors them, and integrates results — all in plain sight.

Prerequisites

• Claude Code installed
• c11 installed (the only supported substrate since v0.9.0 / T016)
• bun installed (required for the Manager daemon)
• Running Claude Code inside a c11 session
• Nerd Font (recommended) — enhances TUI dashboard icons

  brew install --cask font-hack-nerd-font

  Works without Nerd Font (falls back to Unicode symbols). Set CMUX_NERD_FONT=0 to use fallback icons explicitly.

Installation

npm install -g @hummer98/elevens

About auto-update

The daemon detects new versions via update-notifier and surfaces them in the TUI banner. Install is always manual — run npm i -g @hummer98/elevens@<latest> yourself to avoid surprises across mixed Node environments (Volta / nvm / Homebrew).

Two modes (default: off):

mode	behavior
off	do nothing (no registry access)
notify	detect every 12h and show a TUI banner; no install

Configuration (precedence: env > config > default):

• CMUX_TEAM_AUTO_UPDATE=off|notify (also accepts 0|false as off)
• .team/config.json: { "autoUpdate": "off" | "notify" }

Related:

• NO_UPDATE_NOTIFIER=1 disables detection (standard update-notifier env var)
• Boot log: auto_update_config mode=<mode> source=<env|config|default>

Breaking change (v4.5.0, T294):

• The task mode (auto-creation of update tasks) is removed. CMUX_TEAM_AUTO_UPDATE=task|1|true and .team/config.json: autoUpdate: "task" | true | false now exit with status 1.
• The elevens self-update subcommand is removed.
• Migration: set autoUpdate to notify (or off), then run npm install -g @hummer98/elevens@latest when the banner appears.

Substrate

elevens runs on top of the c11 terminal multiplexer. Since v0.9.0 (T016), c11 is the only supported substrate — the legacy cmux backend and the ELEVENS_BACKEND env var have been removed. If you previously pinned ELEVENS_BACKEND=cmux, unset it and install c11:

unset ELEVENS_BACKEND
brew install --cask c11   # or download the c11.app bundle from Stage-11-Agentics/c11

elevens locates the c11 binary in this order: (1) the bundled CLI inside c11.app/Contents/Resources/bin/c11 when launched from the app (auto-detected via CMUX_BUNDLED_CLI_PATH), or (2) the first c11 on $PATH. There is no env var to override this — if c11 is missing or fails, the daemon fails fast and exits with a clear error message rather than silently degrading.

Configuration (.team/config.json)

Created per-project by elevens start. All keys are optional — the file can be edited by hand and is re-read on next start. General precedence: CLI flag > env var > .team/config.json > built-in default.

Key	Type	Default	Purpose
mainBranch	string	auto-detected from origin/HEAD	Primary development branch used as the default worktree base & merge target. Overrides: env CMUX_TEAM_MAIN_BRANCH, CLI --main-branch, per-task --base-branch.
layout	"wide" | "16x9"	"16x9"	Pane layout preset at startup. Override: CLI --layout.
sleepPrevention	"off" | "idle" | "aggressive" | boolean	"aggressive"	macOS sleep prevention mode. aggressive = caffeinate -dis (block display + idle + system sleep, default since T256), idle = caffeinate -i (block user-idle only; allows display sleep), off = no caffeinate. Boolean is accepted for backward compatibility (true → aggressive, false → off). Override: CLI --sleep-prevention <mode> or --no-sleep-prevention.
autoUpdate	"off" | "notify"	"off"	Version detection mode (see above). Override: env CMUX_TEAM_AUTO_UPDATE.
models.master / models.conductor / models.agent	string	Claude defaults	Per-role model selection (e.g. "claude-sonnet-4-6").
dashboard.port	number	0 (ephemeral)	Fixed listen port for the web dashboard server (T034). Accepts integers in [1, 65535] only. Pinning it keeps the URL stable across daemon restarts (bookmarkable). Unset / 0 / invalid values fall back to an ephemeral port. See docs/spec/12-web-dashboard.md.
dashboard.lanAccess	boolean	false	Expose the web dashboard on your LAN so you can read /files from a phone or another machine. true binds to 0.0.0.0 and writes dashboardServer.lanUrl (http://<LAN-IP>:<port>) to .team/team.json; the TUI Settings tab (4 key) then shows a QR code for the /files viewer. Only the literal value true enables it (anything else falls back to false). There is no authentication — anyone who can reach your machine on the network can read docs/ / .team/artifacts/ / .team/output/ and the metrics API. Enable it only on trusted networks. See docs/spec/12-web-dashboard.md §2.3.1.
envrcHookPromptSkipped	boolean	false	Internal flag set when the user declines the direnv hook prompt — normally not edited by hand.
cmux.reservedRenameDelayMs	number	800	c11 title-pinning tuning knob (T026). Delay (ms, clamped to [0, 60000]) before re-renaming a reserved Conductor pane so the fixed tab name wins over c11's default title setter. Raise this if a future c11 update shifts the title timing.

Example:

{
  "mainBranch": "develop",
  "layout": "16x9",
  "sleepPrevention": "idle",
  "autoUpdate": "notify",
  "models": { "conductor": "claude-sonnet-4-6" }
}

See docs/spec/05-install-and-infrastructure.md for the full resolution semantics (including mainBranch auto-detection and worktree start-point order).

Usage

Basic Workflow

Start c11, launch Claude Code inside it.

$ elevens start
  → Daemon starts with TUI dashboard
  → Manager / Master panes created, Conductors spawned
  → Switch to Master pane to give tasks

You:    Build a TODO app with React
Claude: Task created.
  → Daemon detects task → assigns to an idle Conductor
  → Conductor spawns Agents as tabs in the same pane
  → Watch each agent working in real time

You:    How's it going?
Claude: (checks manager.log, cmux tree)
        Conductor-1: implementing (2/3 agents done)

You:    Also clean up worktrees
Claude: → elevens create-task --title "..." --status ready
       → Daemon assigns it to another idle Conductor in parallel

Commands

CLI Commands (run from terminal)

See elevens --help for the full list. Common commands:

Lifecycle

Command	What it does
elevens start	Start daemon + Master + Conductors (self-heals if layout got lost)
elevens status	Show team status
elevens --version	Show version

Note: elevens stop was removed in v4.3.0. The daemon auto-stops when the cmux session exits (pidfile release). To terminate manually: kill <pid> (see .team/daemon.pid).

Task management

Command	What it does
elevens create-task --title <t> [--status ready] [--body <b>] [--depends-on <ids>] [--base-branch <branch>] [--run-after-all] [--exclusive] [--epic-id <Eid>]	Create a task (--base-branch: worktree start-point & merge target, default: main; --exclusive: run alone after drain, implies --run-after-all; --epic-id: link to a parent Epic, e.g. E001)
elevens update-task --task-id <id> --status <s>	Update task status
`elevens close-task --task-id --deliverable-kind <files	merged
elevens abort-task --task-id <id>	Abort a running task
elevens restart-task --task-id <id>	Restart an assigned Conductor session
elevens delete-task --task-id <id>	Delete a draft/ready task
elevens await-task --task-id <id> [--timeout <sec>]	Wait for task completion

Base branch (--base-branch): By default each task's worktree is cut from your mainBranch (resolved via env CMUX_TEAM_MAIN_BRANCH → config.mainBranch → origin/HEAD), and the Conductor treats it as the merge target. Pass --base-branch develop to cut from and merge back to develop instead — useful for hotfixes or feature branches that should not target main. Start-point resolution order: explicit --base-branch → local <mainBranch> ahead of origin → origin/<mainBranch> → local <mainBranch> → HEAD (see docs/spec/05-install-and-infrastructure.md for details).

Epic (PoC — Phase 1)

A third category alongside Task / Artifact. An Epic is a "goal you want to achieve" that an autonomous Epic Planner (run manually via /loop in Phase 1) decomposes into Tasks. See docs/spec/14-epic.md for the full spec.

Command	What it does
elevens epic create --title <t> [--body <intent>] [--budget-token <n>] [--budget-iteration <n>] [--budget-hours <h>]	Create a new Epic (status=active) with optional budget caps
elevens epic list [--status active|blocked|closed|aborted|all]	List Epics, filtered by status
elevens epic show <Eid>	Show frontmatter + body + child Tasks (linked via --epic-id)
elevens epic resume <Eid> [--budget-token <n>] [--budget-iteration <n>] [--budget-hours <h>] [--journal <text>]	blocked → active (optionally raise budget)
elevens epic abort <Eid> [--journal <text>]	active/blocked → aborted

Phase 1 PoC scope: CLI + epic.md + Planner template + manual /loop. Daemon integration / auto-spawn / abort cascade / hard budget enforcement are Phase 2.

Integration Queue / Integrator (PoC — Phase 1)

A post-development lane. Conductors finish by delivering a PR (deliverable=pr); a single Integrator (/loop, run manually in Phase 1) pulls those closed PRs from the queue and is the only actor that touches main / deploy / the real device — serializing integration via the single-writer pattern. Opt-in per project (base Conductor templates stay local-merge by default). See docs/spec/17-integration-queue.md for the full spec.

Command	What it does
elevens integ enqueue --task <id> [--pr <url>] [--branch <name>] [--force]	Enqueue a closed deliverable=pr Task as an integration item (Qnnn)
elevens integ list [--state queued|integrating|verifying|done|failed|all]	List items, filtered by state
elevens integ show <Qid>	Show item detail
elevens integ update <Qid> --state <state> [--batch <B>] [--artifact <A>] [--followup <id>] [--retry-inc] [--reason <text>]	FSM transition (5 states; done/failed require --artifact, failed also --followup)

Phase 1 PoC scope: CLI + Item FSM + Integrator template + opt-in Conductor pr-only notes. Daemon auto-enqueue / event-driven Integrator spawn / staging release-train / deploy guardrail hook are Phase 2.

Agent / Conductor

Command	What it does
elevens spawn-conductor [--resume <session-id>] [--task-prompt <path>]	Boot / spawn a Conductor on the current surface (proxy auto-resolved). Self-registers via CONDUCTOR_REGISTERED. T421: also handles --resume (replaces the deprecated elevens conductor / elevens resume)
elevens spawn-agent --conductor-surface <s> --role <r> --prompt <p>	Spawn an Agent tab
elevens agents	List running agents
elevens close-agent --surface <s>	Gracefully stop an Agent
elevens kill-agent --surface <s>	Force-terminate an Agent (crash)
elevens send-agent --surface <s> <message>	Send a message to Agent / Conductor
elevens spawn-master	Boot Master role (proxy auto-resolved)
elevens reset-conductor [--surface <s>] [--force]	Locally reset a Conductor (any state → reserved) from its own surface terminal. --surface defaults to CMUX_SURFACE. --force is required when the lane has an assigned task — that task is aborted with reason=reset_conductor and cascade is applied. Symmetric with the SESSION_CLEAR(running) recovery path
elevens clear-conductor [--surface <s>]	Remove a broken Conductor from the pool. The surface is never closed — the entry is dropped, maxConductors is decremented by 1, and any re-registration from that surface is rejected (resets on daemon restart / cmux-team start). --surface defaults to CMUX_SURFACE. Only broken Conductors can be cleared; for other states use reset-conductor / abort-task / restart-task
elevens clear-master --surface <s>	Remove a Master (any state) from the pool. The surface is never closed: the Master entry is dropped, its master file deleted, watcher stopped, and re-registration rejected (resets on daemon restart). To stand up a fresh Master use spawn-master or reset-master
elevens reset-master --surface <s>	Recreate a Master: remove the old one (surface left untouched) and spawn a new Master in a new pane. The main way to recover a stuck disconnected Master

Token Pool

Command	What it does
elevens token add	Register a manual API key interactively (paste token)
elevens token add --subscription <handle> [--plan max-x20] [--tags any]	Register a Claude Max / subscription token (no keychain snapshot, Claude Code-managed auth)
elevens token list	List registered tokens with utilization
elevens token remove --handle <h>	Remove a token
elevens token rotate --handle <h>	Re-probe credential and update auth hash
elevens token set-plan --handle <h> --plan <p>	Override plan/ratio manually
elevens token promote --handle <h>	Set selectable=true on an auto-discovered token
elevens token migrate-subscription	Delete cmux-team-token keychain entries for subscription rows (idempotent)
elevens pool status	Show pool capacity dashboard

Manual vs subscription tokens

• manual — A persistent API key. elevens stores the token in macOS keychain (service cmux-team-token) and injects CLAUDE_CODE_OAUTH_TOKEN into spawned agents.
• --subscription — A Claude Max subscription. Claude Code itself manages auth via ~/.claude/.credentials.json and refreshes the token as needed. elevens does not keep a keychain snapshot and does not inject the token into agents — it lets Claude Code handle authentication and only observes the requests through the proxy to track utilization. Use this for any subscription-backed handle.

Diagnostics

Command	What it does
elevens trace-task <task-id>	Show session history for a task
elevens trace-hooks	Show hook signal history
elevens artifacts [add|show|open|search]	Manage knowledge artifacts
elevens metrics [--since <range>] [--group-by day]	Show task lifecycle / tool call / token aggregates (see docs/spec/11-metrics.md)
elevens metrics snapshot|compare|health|query	Daily snapshot, cohort comparison, health check, and DuckDB ad-hoc query
elevens events [--follow] [--types <names>] [--format json|tsv]	Tail / filter the events stream (.team/logs/events.jsonl)
elevens events emit --type <name> [--message <text>] [--actor <id>] [--data k=v]...	Append a free-form user signal to the events stream (best-effort; works while daemon is stopped). See docs/spec/10-events-stream.md §6.20

Slash Commands (run within Claude)

Command	What it does	When to use
/master	Reload Master role	After /clear
/elevens:watch	Watch events stream and auto-handle PR merge (squash) / git pull --ff-only (opt-in); conflicts are escalated, not auto-resolved	When you want Master to auto-merge completed PRs and surface escalations
/team-spec [summary]	Brainstorm requirements	Deciding what to build
/team-task [action]	Task management	Create / list / close tasks
/team-archive [range]	Archive closed tasks	Task cleanup
/artifact [type] [title]	Save findings as artifact	Knowledge capture
/docs-sync [--dry-run|--auto]	Sync docs/spec/ with implementation	Doc maintenance
/trace-task <task-id>	Analyze a task's session history	Debugging, review

Architecture

┌─────────────────────────────────────────┐
│  elevens daemon (TypeScript/bun)        │
│  ┌───────────────────────────────────┐  │
│  │  TUI Dashboard                    │  │
│  │  Tasks: 2 open | Conductors: 1/3  │  │
│  └───────────────────────────────────┘  │
│  Queue ← Master/Hook write via CLI      │
│  Loop  → Task scan → Conductor spawn    │
│  Monitor → Completion → Result collect   │
└───────────┬────────────┬────────────────┘
            │            │
     [Master]    [Conductor-035]
     Claude Code  Claude Code
     (Opus)       → [Agent] Claude Code

Deterministic Manager

The Manager is not a Claude Code session. It's a TypeScript program with a deterministic event loop:

• HTTP message queue via the built-in proxy (elevens send <TYPE>) — event-driven, not polling
• File-based task state (.team/tasks/ + task-state.json)
• zod schema validation for all messages
• ink TUI dashboard
• Web file viewer (/files) — browse docs/ / .team/artifacts/ / .team/output/ in a browser with a 2-pane layout (Markdown rendering, HTML report / image serving, mtime sorting, type filtering). A time-series mode (time chip) lists every file across all three roots newest-first by title instead of by directory, and the pane divider is draggable — both are remembered in localStorage. URL is dashboardServer.url in .team/team.json + /files. elevens open <file> makes the open tab follow to that file (no new tabs). Set dashboard.lanAccess: true to read it from a phone over the LAN (QR code in the TUI Settings tab — note there is no authentication)
• Task dependency resolution via depends_on field
• Priority sorting (high > medium > low)
• Agent completion via fs.watch — Agent's Stop / SessionEnd hook writes a done marker, Conductor awaits it with elevens await-agent (no busy polling, T181)

Task Dependencies

---
id: 13
title: Consolidated report
status: ready
depends_on: [10, 11, 12]  # waits for all to complete
---

Communication

Direction	Mechanism
Master → daemon	elevens send <TYPE> → HTTP message to proxy
daemon → Conductor	cmux send (/clear + new prompt on a persistent Conductor pane)
daemon ← Conductor	Done marker file (.team/conductors/<id>/done) + SESSION_* hook messages
Conductor → Agent	elevens send-agent / spawn-agent (direct cmux send is blocked by hook)
Conductor ← Agent	elevens await-agent (fs.watch on Agent done marker)
daemon → external readers	events stream (.team/logs/events.jsonl, JSONL append-only) — opt-in, consumed by elevens events --follow and Master /elevens:watch

Project-Specific Agent Instructions

You can give each overlay role (10 in total: researcher / architect / planner / design-reviewer / implementer / inspector / dockeeper / task-manager / master / conductor) a project-local overlay by writing .team/agent-instructions/<role>.md. The overlay content is injected into the corresponding prompt:

• Agent roles (8) — overlay is applied at elevens spawn-agent time (replaces {{PROJECT_INSTRUCTIONS}} in the agent prompt-file).
• master / conductor (T342) — overlay is applied as a shared system-prompt overlay at daemon start: generateMasterPrompt / generateConductorRolePrompt injects it into .team/prompts/master.md / .team/prompts/conductor-role.md. They cannot be passed to elevens spawn-agent --role (it returns exit 1 with a "reserved" error).

# Write an overlay
elevens set-agent-instructions --role implementer --from-file ./my-impl-notes.md
elevens set-agent-instructions --role researcher --body "Limit search to papers from 2025 onward"
elevens set-agent-instructions --role master --body "Always summarise progress in 3 lines"
elevens set-agent-instructions --role conductor --from-file ./conductor-overlay.md

# Inspect / list
elevens get-agent-instructions --role implementer
elevens list-agent-instructions

# Delete (idempotent)
elevens delete-agent-instructions --role implementer

Max overlay size is 100 KB. The dashboard's Settings tab (4 key) shows a read-only preview of all role overlays plus a config snapshot.

Token Pool

When you have multiple Claude accounts, elevens can automatically distribute Agent spawns across them to avoid rate limits.

Enable (opt-in, per-project):

// .team/config.json
{ "tokenPool": { "enabled": true } }

Or via env: CMUX_TEAM_TOKEN_POOL=1.

Register tokens (macOS Keychain required for manual; subscription does not use keychain):

# Manual API key (interactive, stored in keychain)
elevens token add

# Claude Max subscription (no keychain, Claude Code-managed auth)
elevens token add --subscription @tayo --plan max-x20 --tags any

elevens token list     # show all tokens with 5h/7d utilization

Selection algorithm (per Agent spawn):

1. Exclude handles in policy.exclude
2. Skip tokens with active lease (120 s) or util_5h > 95%
3. Admit by: projectDefault match → include list → isOss flag → tag match ("any")
4. Score = 0.3 × util_5h + 0.7 × util_7d — pick the lowest

The TUI dashboard header shows the 7-day forecast sparkline (Day 0..6 daily allocation, 100% = sustainable pace under the BLOCKER_7D=0.95 cap) and the next account the agent spawn will pick:

pool 7d  ██▇▅▅▆█   next: @kddi 5h:65%

Per-surface decoration (@handle <5h:X%/7d:Y%> cap:Z%) is removed in favor of the aggregate header. Run elevens pool status for per-account detail.

See docs/spec/09-token-pool.md for tag filtering, exclude/include policy, and plan ratio details.

Traceability

All API requests are automatically recorded through the built-in proxy when the daemon is running.

Inspecting a Task's Sessions

# Show session history for a specific task (Conductor + Agents)
elevens trace-task 035

Traces are stored in .team/traces/traces.db with request/response bodies in .team/logs/traces/bodies/. Metadata headers (x-cmux-task-id, x-cmux-conductor-surface, x-cmux-role) are propagated so every API request can be correlated with its originating task.

Post-mortem evidence when the daemon dies silently (v0.8)

If the daemon crashes without leaving a clear cause in manager.log, the following files under .team/ let you reconstruct WHEN / WHAT / WHY after the fact:

• .team/daemon.heartbeat — sync write every 10s. If it survives, the daemon died abnormally; its mtime marks the time of death (±10s).
• .team/logs/manager.telemetry.jsonl — RSS / heap / event-loop lag sampled every 30s (look for monotonic growth = leak-style OOM).
• .team/logs/manager.stderr.log — the daemon's OS fd 2 is redirected here, so Bun runtime panics / Rust panics / libc aborts all land in this file.
• fatal_uncaught / signal_received events in .team/logs/manager.log — synchronous record of JS exceptions and signals (SIGTERM/SIGINT/SIGHUP).

See docs/spec/15-post-mortem-evidence.md for the analysis cookbook (with example commands) and the postMortem.* config overrides in .team/config.json.

Troubleshooting

Daemon won't start

bun not installed: brew install oven-sh/bun/bun

Not in c11: Run inside a c11 session. CMUX_SOCKET_PATH must be set.

Panes too narrow

Too many panes cause cmux commands to fail. Exit the cmux session (daemon auto-stops) and restart with CMUX_TEAM_MAX_CONDUCTORS=1 to limit concurrency.

View Conductor session logs

grep conductor-xxx .team/logs/manager.log
# → task_completed ... session=abc-123
claude --resume abc-123

Known Limitations

• API rate limits: Multiple concurrent agents. Claude Max recommended. Control with CMUX_TEAM_MAX_CONDUCTORS (default: 3).
• Pane width: Too many panes can break cmux commands.
• Trust prompts: New directories trigger trust confirmation. Conductor auto-approves but may need manual intervention.

Testing

Do NOT run bun test against the whole manager directory. The full-suite invocation suffers O(N²) slowdown and may hang for 30+ minutes (see .team/artifacts/A021-research.md). Use the per-file loop:

cd skills/cmux-team/manager
for f in *.test.ts state-machine/*.test.ts dashboard-*.test.tsx; do
  bun test --timeout 30000 "$f" || echo "FAIL: $f"
done

CI (.github/workflows/test.yml) runs the same per-file loop on every PR and on push to main. The aggregate-mode invocation will be restored once the root cause (module-level singleton accumulation) is fixed.

Contributing

See CONTRIBUTING.md for testing, repository structure, and coding conventions.

License

MIT License — see LICENSE for details.