KBL (pronounced Kibble) lets one engineer supervise far more concurrent engineering work by coding agents than
they could by driving each session themselves. It pulls issues in from GitHub, Azure DevOps, Jira or GitLab, hands
each piece of work to exactly one agent, and keeps people in the loop for the decisions that need them: accepting a
triage, answering a question, steering or taking over an item. Every claim, step and decision is recorded on a
Felix event log with who made it, so the queue, the board and the full history of
a fix are all replays of one record. Agents from any vendor take work through an MCP server, kbl-mcp; people
supervise from the dashboard.
The name comes from Kanban By Log, but the board is only the view. Underneath, KBL is a work scheduler on an event log: exactly one holder per attempt, priorities and dependencies, budgets, and a record you can audit and replay. What we are proving now is the supervision claim, measured: see the supervision plan.
KBL is not agentic. The tracker, kbl-mcp and the dashboard make no model calls and generate no text.
Triage, gathering context, splitting, answering questions and fixing are all work items that an agent or a
person completes.
Style frames from prototype/intake-frame.html, drawn from hand-written fixtures. The quick start runs the real thing.
Status: M0, M1 and M2 are done: the task tools, the tracker with ingest, ready tiers and the work tools, and the dashboard and replay. The current focus is supervision: the human and provenance experience, then a measured experiment (plan). Scale work (more sources, many agents) waits on its result. See Status.
This runs KBL on one machine: Felix, felix-gateway, the work tracker and the dashboard, each in a container built from
this checkout. It is a local, single-user stack, not a deployment: the stand-in identity provider signs in anyone
who asks, the tracker speaks plain HTTP, and nothing keeps its data between starts. Every port is bound to 127.0.0.1.
Self-hosting with a real identity provider is tracked in issue 316.
You need Git, curl, Node 22 or later, Rust 1.97 or later (to build kbl-mcp), and Docker (Compose v2) or Podman (with podman-compose 1.4 or later). The first start
builds the tracker and the dashboard from source and takes about 10 minutes (CI allows 15); later starts reuse the build cache.
git clone https://github.com/GetFelix/KBL.git
cd KBL
dev/quickstart.shWithout building (no npm needed). Once a release is tagged, its tracker and dashboard images are on ghcr.io, and the stack can pull them instead of building:
KBL_IMAGE_TAG=v0.2.1 dev/quickstart.shWith KBL_IMAGE_TAG set, the script never builds. It refuses a checkout whose version differs from the tag
("check out v0.2.1, or unset KBL_IMAGE_TAG to build") and prints at the start whether it is pulling or building.
Download kbl-mcp, kbl-tool and kbl-ingest from the same release (Getting the binaries).
The images exist only after the first tag. The tracker, dashboard and every dev/*.mjs script need only Node and the
container engine, with no npm install.
When it finishes it prints a "view link" for the dashboard (read-only; its gateway token is in it, so keep it to yourself),
the tracker address and a "person token for actions", which the dashboard's Sign in takes for its write actions. Ports 8081, 8788 and 8790 must be free. Choose the engine with CONTAINER_ENGINE=docker or podman.
The script waits for the tracker's /healthz and for the dashboard to reach it before it prints the link, and prints the
tracker log if that never happens. A fresh broker takes a few seconds to settle, and the tracker retries its setup calls
for up to two minutes meanwhile, so a few retrying lines in its log are normal. If the dashboard answers "The tracker
answered 502", check docker compose -f dev/compose.yml --profile quickstart logs tracker (or podman compose); the
dashboard looks the tracker up again by name, so a restarted tracker needs no dashboard restart.
The stack's work log starts at the format this build writes, so supervise_start and the other newer tools work with no
format_raised by hand. The script prints the log's format; a log carried over from an older build that is below it
gets the one command to raise it, as in upgrading.
-
Open the dashboard. Open the printed link. Its queue is empty.
-
Add work. Post an item to the tracker with the person token (the dashboard's Sign in takes the same token for its accept, reject, tier and close actions):
me=$(node -e 'const t=require("./dev/state/tracker-tokens.json").people;console.log(Object.keys(t)[0])') for rec in '{"kind":"imported","item":"demo-1","source":"quickstart","upstream_id":"1","title":"Fix the typo in the README"}' \ '{"kind":"accepted","item":"demo-1","tier":1}'; do curl -fsS -X POST http://127.0.0.1:8790/v1/work/records -H "authorization: Bearer $me" \ -H 'content-type: application/json' -d "{\"record\": $rec}"; echo done
The item shows in the dashboard as ready. To bring in real issues from GitHub, Azure DevOps or Jira, see Running the ingest worker.
-
Connect Claude Code. Build
kbl-mcpon the host (it is the program Claude Code starts, so it runs outside the containers) and write a config for one agent. Once a release is tagged you can instead downloadkbl-mcpand pass its path with--mcp, in place of thecargo buildline:cargo build --release -p kbl-mcp node dev/connect.mjs agent1 --out .mcp.json claude --mcp-config .mcp.json --strict-mcp-config
Ask Claude Code to call
work_next. It claimsdemo-1, and the dashboard shows the item held byagent1.connect.mjswrites the file with mode 600 (it holds the agent's tracker token) and with absolute paths, so any directory works. The stack has agentsagent1toagent8, one tracker token each. The agent's ID token goes indev/state/agent1.id-token(mode 600), and the config pointsKBL_FELIX_ID_TOKEN_FILEandKBL_FELIX_CONTROL_PLANEat it, sokbl-mcprenews its Felix token by itself. The ID token lasts 24 hours: runnode dev/connect.mjs agent1again to write a new one, and the runningkbl-mcppicks it up at its next renewal.--fixed-tokenwrites a Felix token into the config asKBL_FELIX_TOKENinstead; that one is not renewed, so after 24 hours runconnect.mjsagain and restart the host. The view link works once: the page removes the token from the address and keeps the session in that tab only (sessionStorage, cleared on sign-out and when the tab closes). A reload keeps it; a new tab needs a new link fromnode dev/open-dashboard.mjs..mcp.jsonholds tokens and is in.gitignore. -
Bring in GitHub issues (optional). Ingest turns the issues carrying one label in one repository into work. Build it, then point it at a repository and a token file (or export
GITHUB_TOKEN). The token needs read access to that repository's issues:cargo build --release -p kbl-ingest node dev/ingest.mjs --repo OWNER/NAME --token-file ~/.github-token --labels agent-okWith the release binaries on your
PATHthere is nothing to build; skip thecargo build. To take a milestone instead of a label,node dev/ingest.mjs --repo OWNER/NAME --token-file ~/.github-token --milestone v0.8.0. Any filter other than--labelsdrops theagent-okdefault (it applies only when you give no filter), and the script prints the rule it will use before the check.--labels ""means no label filter. It first runskbl-ingest check, which tests the token and lists what the first poll would import without writing anything, then keeps polling the local tracker until you press Ctrl-C. The issues appear in the dashboard's Ready column. Add--check-onlyto stop after the check, or--oncefor a single poll. The config it writes isdev/state/ingest.json. Narrow or change the filter with--labels a,b(all required),--exclude-label x,y,--milestone NAME,--cap N(open roots at most) and--mode propose(see below).--keep-configruns the existing file as it is, for a config you edited by hand.What the mode means:
admitimports each match as a root and queues its triage and augment work first, so agents are handed that before any fix, and the root becomes ready to fix once a person accepts the triage.proposewaits for a person before anything is queued. A rule that sets"triage": "skip"(withadmit) imports an issue that is already well specified straight to Ready to fix, with no triage or augment item. Setting up ingest explains the rest.To keep a person out of the routine decisions, give the tracker a triage policy (
KBL_TRIAGE_POLICY_FILE): rules over what triage recorded, such as "tier 2 or 3, not replication, storage or safety review". The tracker accepts a finished triage that matches a rule, naming the rule on the record, and everything else stays in Needs you. A person can take any such acceptance back from the dashboard. See accepting routine triage by policy. -
Stop it with
dev/down.sh, which also deletes its data.
- See what is running.
dev/ps.shlists the containers and their state;dev/logs.sh [service]prints their logs (FOLLOW=1 dev/logs.sh trackerfollows). Both use the engineup.shchose. - Is the tracker up?
curl http://127.0.0.1:8790/names the service and its version and points to/healthz. - The dashboard says "Connect to a gateway" or "Sign in". Run
node dev/open-dashboard.mjsfor a new view link. A reload keeps the session in the same tab; a new tab, a closed tab or Sign out needs a new link. - "Viewing (read-only)" and the board is full. The view link only reads. "Sign in to act" takes the person token for
actions (printed with the link, or in
dev/state/tracker-tokens.json). kbl-mcporkbl-ingestnot found. The scripts look at the flag,KBL_MCP/KBL_INGEST,target/release,target/debug,~/.kbl/bin,dev/state/binand yourPATH, in that order. Build the binary or put it in one of them.- A port is taken. 8081, 8788 and 8790 must be free;
dev/down.shthendev/quickstart.shstarts clean.
The tracker and the dashboard run as unprivileged users inside their containers, under both Docker and Podman. The tracker starts as root only long enough to read the token file the host owns, then drops to its own user.
felix-arena uses a log as a live feed and a replay, felix-metro seeks back through a long history, and felix-blocks is keyed state with many writers. KBL puts them to work on a backlog that never ends:
- Each piece of work is claimed once, even when agents die. A consumer group hands an item to one agent and gives it to another when the first stops answering. Felix dead-letters a delivery that is handed out too many times; the tracker publishes a new record for the Ready item, so the item is not lost. Work items have no attempt cap there: a failing item uses its tries (two claims), then waits in Needs you for a person.
- People and agents don't overwrite each other. Items are keys written with
cache_put_ifat the version read, so a stale write is refused. - One log is the record.
work.eventsholds every import, claim, decision and refusal in order, with the broker's record of who wrote it. The queue, an item's history and the replay are folds of it. - Budgets hold under a race. A root's budget only decreases, and a create over it is refused.
- Spend is usage, priced by the tracker. Agents report the tokens or AI credits each model used; people keep the price table, and a model with no price is charged the floor until it gets one.
kbl-tool prices import --defaultloads a dated starting table (cost and spend). - Agents stay in their lane. Each agent has its own token and reaches work only through the tracker, which is the only writer of
work.events, the ready streams and the item keys.
- Bring bugs in from GitHub, Azure DevOps or Jira once each, and add your own work
- See the queue: what needs you, what agents hold, what waits on what
- Let any MCP host (Claude Code, the Claude Agent SDK, another vendor's) ask for the next item it can start, through
kbl-mcp - Let agents triage, split and add context as work they claim, with children bounded by a budget per root
- Accept, edit or reject an agent's proposal, or answer its question, from the dashboard
- Read items and an item's history, and move an item into or out of Needs you, from the dashboard or through the tracker's REST API with your own token
- Open a fix's decision replay: scrub through what the agent decided, with the fields it recorded and the steps behind them
- Redo from a past decision as new work, with your note, without touching the first attempt
| Need | Felix feature |
|---|---|
| Handing each item to one agent | A consumer group: per-record ack, visibility timeout, claim extension, max attempts and dead letters |
| Priority | A ready stream per tier, polled in order |
| Items, edges, context and budgets | A log-backed cache with conditional writes (cache_put_if, cache_delete_if) |
| Importing an upstream bug once | cache_put_if on the upstream id, absent only |
| The record | A durable stream (work.events) with the publisher recorded, range reads, subscribe from an offset |
| What each principal may write | RBAC, down to a cache key prefix |
| The browser dashboard | felix-gateway |
Some of this is not yet reachable the way the design wants. The design lists
it under "Felix gaps", and each one has an issue labelled
felix-gap.
Bugs come in as roots from GitHub, Azure DevOps or Jira, and from people. An ingest worker writes each upstream
id once and posts one triage item and one augment item for it. The agent that claims the triage item answers
it with work_triage (a tier and why, a duplicate, dependencies, related items, a split, or what is unclear), and a person accepts or edits that
proposal; the dependencies, related items and split are advice a person acts on. A related item is scheduled alongside and never blocks; only a dependency does. Work the item needs from another repo is
different: the triaging agent posts it as a prerequisite, and the item waits on it before anyone builds. A dependency can sit in any repo or source,
and the board names where each blocker lives (its repo, else its source) when it differs from the row's repo. An item becomes claimable when its last
dependency is done: the tracker folds work.events and publishes it to a ready stream for its priority tier.
A failed check that matches the team's flake list is re-run once by ingest before it becomes work; a green re-run never reaches Needs you, and each entry counts its hits. A check that stays red becomes a fix_check item with the end of the job's log, which an agent claims and pushes to the same pull request; after the team's auto_fix_tries (default 1) it goes to a person as before (failed checks become fix work).
Each agent runs kbl-mcp with its own token, and every work tool calls the tracker. work_next asks the
tracker for the highest-priority ready item: the tracker claims it from the ready streams' consumer group as a
member named after the agent and logs the claim in the same step. Roots take turns in a tier, work_next can be narrowed by kind, tier, repo, excluded roots, milestone, label, type, area or size, and work_peek lists what it would hand out next without claiming. Both skip an item a person blocked until a time or on a named resource (block_item, lift_block, and lift_resource for every block on one named resource; work tracker). An item can need something only some agents have (needs, set by triage, a person or an intake rule); an agent passes capabilities on work_next and work_peek and is handed only work it can do (work tracker). A person can relate two items (relate_items; work tracker) so they are scheduled together, and neither waits on the other. kbl-mcp extends the claim every 30
seconds while the agent works, and work_complete, work_release or giving up ends it. A dead agent stops
extending, so its claim lapses and the item goes to another agent. An item has one holder at a time: a release
that lands while the item is being handed on does not cost the next agent its claim. An agent adds children only under an item it holds (split, augment,
question or test), within a budget per root. Anything else it finds is a proposal a person accepts. An agent can have at most 16 proposals waiting at once, 8 from one root.
While it works, the agent records decide (what it chose and why, with the phase, a running summary and the
steps it rests on), record_step and edit, committing its work before each decision. Known secret shapes in
what it reports, such as a token in a command's output, are replaced with [redacted] before anything is written,
and so are those in a person's note or answer. A secret with no known shape, such as an AWS secret access key, gets
through, as do quoted assignments (TOKEN="...", "token": "..."), password= and Bearer with two spaces or a
tab: the shapes are kept strict because a cut that hits ordinary text loses it from the record for good.
A person's note or review comment on an item is a human_input (POST /v1/work/note). The dashboard folds these
into the story of a fix and its replay.
A redo from a past decision is a new attempt that starts from that decision's recorded summary and a
reviewer's note, so the first attempt stays as it happened.
The tracker validates every call and does the Felix writes itself, so an agent never writes the work streams or keys directly. docs/work-tracker.md and docs/decision-replay.md have the details.
| M | Milestone | Proves |
|---|---|---|
| 0 | The dashboard and the decision replay, locked: style frames drawn from hand-written fixtures | They read well before Felix is involved |
| 1 | Tasks through Felix: core, the dev stack, kbl-tool, kbl-mcp task tools, scripted planner and workers |
Demonstrations 1 and 2 |
| 2 | The tracker: GitHub ingest, items and dependencies, ready tiers, work_next and the rest of the work tools, triage and augmentation as claimable work |
Real issues become claimable work, once each, and people and agents never overwrite each other (demonstration 3) |
| 3 | Real work: Claude Code claims agent-ok issues through kbl-mcp and opens pull requests |
Agents produce reviewed, merged fixes |
| 4 | The dashboard, live, and more sources (My queue, Board, Metrics) with the review limit, and its results: arrival and completion, time waiting on a human, merge rate, cost and human minutes per fix | Anyone can see the queue and what it delivered |
| 5 | Shared state (closed, superseded by KBL: the swarm demo was removed) | Nothing |
| 6 | The reference worker (kbl-run): a model API, artifacts, spend and rate limits |
Agent-created work stays inside its budget (demonstration 4) |
| 7 | Decision replay, live: the fold, the dashboard on felix-gateway, scrub and follow | The log is a complete record that replays, and a fix's decisions read back with no hindsight (demonstrations 5 and 6) |
| 8 | A hostile agent stays bounded: grants and an injected agent held to its budget | A prompt-injected agent cannot escape its budget or grants (demonstration 8) |
| 9 | Any host, at scale: the Agent SDK as a host, 50 agents, broker restart and failover | Any MCP host can take work (demonstration 7), and it holds under loss |
| 10 | Self-hosting: kbl-mcp releases, compose, a quick start |
Anyone can run it |
M0 and M1 are done. core has the record formats and names (including the org.events records for teams, not served yet), dashboard/ follows work.events through felix-gateway and folds it with core as WebAssembly, kbl-tool creates a run,
and kbl-mcp gives an MCP host the task tools. The dashboard
is described in docs/work-tracker.md and docs/dashboard-research.md. M2 is in
progress. Records on work.events carry a format, so a newer build can take over a running log, and an older build
(from this one on) stops at a record it cannot read instead of misreading it: docs/upgrades.md has the upgrade order. The plan is in docs/design.md and the work is tracked in
milestones.
dev/up.sh starts the Felix a run needs, in containers, with nothing to install but Docker (with Compose v2) or
Podman (with a compose provider that honors depends_on conditions, such as podman-compose 1.4 or later) and Node 22.
Set CONTAINER_ENGINE=docker or podman to choose. Podman on macOS can only mount directories its machine shares, so
keep the checkout under your home directory.
dev/up.sh # start from scratch and wait until it serves
node dev/check.mjs # create a run's log, subscribe to it through the gateway, and check a run the viewer was not granted is refused
dev/down.sh # stop it and delete its dataIt runs Felix 0.7.2 (a control plane and one broker, with the fleet features that store each record's publisher and allow atomic commits turned on) and
felix-gateway 0.9.0, plus a stand-in identity provider. The broker acknowledges a record only once it is written and
fsynced, which the tracker requires of work.events: it refuses to start on a stream a failover could cut
(What Felix must guarantee). The stack keeps nothing between starts, so every up.sh
begins with a new tenant and an empty log.
| What | Where |
|---|---|
| Control plane (REST) | http://127.0.0.1:8443, tenant agents, namespace default |
| Broker (QUIC) | 127.0.0.1:5000, certificate written to dev/state/broker-cert.pem |
| Gateway (WebSocket) | ws://127.0.0.1:8787/ws, configured by dev/scope.toml |
| Identity provider | http://127.0.0.1:9400; /token?sub=<name>&aud=kbl mints an ID token for anyone |
A Felix principal comes from an ID token the tenant trusts, and the stand-in provider signs one for any name, so a
script can be a different agent per name. Exchange the token at the control plane
(POST /v1/tenants/agents/token/exchange) for a Felix token. The seed script makes agents-admin the tenant's
administrator: kbl-tool (see Creating a run) signs in as that name to create a run's streams and caches. The stack creates no runs itself.
The gateway's scope gives a viewer read-only access to agents.log.<run> and agents.blobs.<run> for one run at a time, and only for a run it was granted.
The stand-in provider signs in anyone, so never expose these ports beyond localhost.
A run is one job: a goal, a budget and a team of agents, with its own set of Felix resources. kbl-tool run create
makes those resources: the run log, the tasks stream with its workers consumer group, the messages stream, and the
board, leases, presence, results, artifacts and spend caches (the nine in docs/design.md;
spend is a cache used as counters). It then writes run_started to the log with the goal, the budget and the agents.
The run's id must be new, and creating one that exists is refused.
With the dev stack running:
cargo run -p kbl-tool -- run create demo --goal "Review PR 12" --budget-usd 5 --workers 4created run demo (9 resources)
log agents.log.demo (run_started at offset 1)
tasks agents.tasks.demo (group workers)
The run lists a planner and the workers w1 to w4. --budget-usd is in dollars (5 or 0.25), and a run can
list 1 to 64 workers.
The defaults match the dev stack. Point the tool at another Felix with these, as flags or environment variables
(kbl-tool --help has the flag names):
| Variable | Default | What |
|---|---|---|
KBL_TENANT, KBL_NAMESPACE |
agents, default |
Where the run lives |
KBL_FELIX_CONTROL_PLANE |
http://127.0.0.1:8443 |
Creates the resources |
KBL_FELIX_BROKER |
127.0.0.1:5000 |
Writes run_started and creates the group |
KBL_FELIX_CA_FILE |
dev/state/broker-cert.pem |
The certificate the broker is trusted by, relative to where you run the tool |
KBL_FELIX_BROKER_NAME |
localhost |
The name in the broker's certificate |
KBL_IDP |
http://127.0.0.1:9400 |
The stand-in identity provider that signs in agents-admin |
KBL_ID_TOKEN |
none | An ID token for the tenant, used instead of the stand-in provider |
The tool connects to the broker before it creates anything, so a wrong certificate path or a broker that is down fails
without using up the id. If it stops after that (the broker went away, say), the run is left without run_started and
the id cannot be used again, so use a new one.
kbl-mcp is the server an agent reaches Felix through. It speaks MCP over stdio, so
any MCP host can start it: Claude Code, the Claude Agent SDK, or a host from another vendor. One kbl-mcp process
serves one agent and holds that agent's Felix token (or the ID token it renews one from), so the agent can do on Felix only what its token allows.
run_info reports the run, the agent's name and the tenant, and the task tools post and work tasks.
On start it connects to the broker, and it exits with the broker's error if the token or address is wrong, so a host
sees a failed server instead of a list of tools that cannot work.
Each release carries kbl-mcp, kbl-tool and kbl-ingest for Linux (x86_64,
aarch64), macOS (aarch64, x86_64) and Windows (x86_64). Download the archive for your platform, verify it, and put the
binaries on your PATH. Each archive and SHA256SUMS carry a signed attestation of the release workflow that built
them; gh attestation verify (GitHub CLI 2.49 or later) checks it, and SHA256SUMS catches a corrupt download:
tag=v0.2.1 # the release you want
target=x86_64-unknown-linux-gnu # or aarch64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-apple-darwin
base=https://github.com/GetFelix/KBL/releases/download/$tag
curl -fLO "$base/kbl-$tag-$target.tar.gz" -O "$base/SHA256SUMS"
grep "kbl-$tag-$target.tar.gz" SHA256SUMS | shasum -a 256 -c # on Linux sha256sum -c also works
gh attestation verify "kbl-$tag-$target.tar.gz" -R GetFelix/KBL
gh attestation verify SHA256SUMS -R GetFelix/KBL # the checksums are attested too
tar -xzf "kbl-$tag-$target.tar.gz"
kbl-$tag-$target/kbl-mcp --help
install -m 755 kbl-$tag-$target/kbl-mcp kbl-$tag-$target/kbl-tool kbl-$tag-$target/kbl-ingest /usr/local/bin/ # or any directory on your PATHOn Windows, download kbl-<tag>-x86_64-pc-windows-msvc.zip and SHA256SUMS, then in PowerShell compare
(Get-FileHash kbl-<tag>-x86_64-pc-windows-msvc.zip).Hash with its line in SHA256SUMS and run
Expand-Archive kbl-<tag>-x86_64-pc-windows-msvc.zip .; gh attestation verify kbl-<tag>-x86_64-pc-windows-msvc.zip -R GetFelix/KBL works there too. The binaries themselves are not code-signed. If macOS refuses one that a
browser downloaded, run xattr -d com.apple.quarantine on it (curl downloads are not affected). To build from source instead, use cargo build --release -p kbl-mcp -p kbl-tool -p kbl-ingest.
With the dev stack running, build it and run the check that starts it the way a host would, lists its tools and calls one:
cargo build -p kbl-mcp
node dev/check-mcp.mjsA planner posts tasks and workers take them one at a time. Felix hands each task to one worker of the workers group
and to another if that worker goes quiet, so a task can be tried more than once but has one result.
| Tool | Does |
|---|---|
task_post |
Puts a task on the run's tasks stream and logs task_posted. A body over 4 KiB is stored as an artifact. An id you choose is refused if that task already has a result; posting the same id twice before it finishes makes two tasks and one result |
task_claim |
Takes the next task, waiting up to 30 seconds (10 by default), and logs task_claimed. A worker holds one task at a time |
task_complete |
Writes the result under the task's key in the results cache only if no result is there, then acknowledges the task, and warns in its reply if the acknowledgement fails (the result still stands). A first result logs task_done; a later one is kept as an artifact and logs task_duplicate |
task_release |
Hands the task back to the group now (task_released) |
task_give_up |
Dead-letters the task so it is not handed out again (task_dead) |
While a worker holds a task, kbl-mcp extends the claim every 30 seconds (it stands for 90), so a model call that
takes minutes keeps its task and a worker that dies loses it within 90 seconds. If Felix answers stale_claim, or
extensions fail for a full 90 seconds, kbl-mcp logs task_claim_lost and the agent's next task tool call says the
claim lapsed and drops the task, except task_complete, which still writes the result (only the first write to a task's key lands, so it is safe), never acknowledges the task, and warns that the claim had lapsed. After two failed extensions in a row the next call warns that the claim is at risk.
A worker restarted under the same name gets back the tasks its predecessor held, one per task_claim and ahead of new
work. Each counts as another attempt, and one whose claim lapses before it is claimed goes back to the whole group. A
task that already has a result is acknowledged and logged task_duplicate instead of being handed to the model. A task
delivered a third time is dead-lettered (task_dead) without reaching the model, since Felix's attempt limit is one
setting for the whole broker and a model task is too costly to try five times. A delivery the broker gives no attempt
count for is dead-lettered too, so the limit cannot fail quietly. task_claim never takes longer than the wait asked
for. Any operation Felix refuses is logged as refused and returned to the model as the tool's error.
A body or result over 1 MiB (1,048,576 bytes) is refused, because the format for splitting larger ones is not defined.
With the dev stack running, this starts a planner and five workers and runs a job, a poison task and a restart:
cargo build -p kbl-mcp -p kbl-tool
node dev/check-tasks.mjsA host such as Claude Code usually stops after one item unless it is told to keep going. This prompt makes it take work until there is none:
Use the kbl tools to take work, and keep going until there is none.
1. Call work_next. If it says nothing is ready, print KBL_QUEUE_EMPTY on a line of its own and stop.
2. Work the item the reply gives you until it is done or you have a question for a person: follow the rules in the reply, run its checks, and call work_complete. If you cannot finish it, call work_release with the reason.
3. Call work_next again.
Stop when nothing is ready or when you are asked to stop. Do not wait for more work to appear.
The work_next reply says the same in its loop field, so a host that was given no prompt still learns to call
work_next again after each item and to stop when the reply says nothing is ready. The field is reply text only; the
standing rules, the records and the log are unchanged.
dev/agents.mjs starts N such sessions. It makes no model calls: it runs the host you already have, once per session,
in a directory with its own .mcp.json that points at kbl-mcp with that session's tokens. Sessions run without a
terminal, so an agent asks a person only through work_ask; a question in the host's own chat would wait forever.
node dev/agents.mjs --run demo --tokens tokens.json --ca-file "$PWD/dev/state/broker-cert.pem" \
--tracker-url http://127.0.0.1:8790The tokens file names each session and its two tokens, one per agent. Prefer it to --agent name=<felix>,<tracker>,
which puts tokens in the process list. With teams on, kbl-tool agent add <name> mints a tracker token for a new
agent with one command, and the tracker accepts it at once; agent list and agent revoke go with it
(One agent token per session).
{ "w1": { "felix": "<Felix token>", "tracker": "<tracker token>" },
"w2": { "felix": "<Felix token>", "tracker": "<tracker token>" } }| Flag | Does |
|---|---|
--sessions N |
Starts the first N agents in the file |
--host CMD |
Runs CMD [--host-arg ...] <prompt> instead of claude -p <prompt> --mcp-config .... The .mcp.json path is in KBL_MCP_CONFIG and the directory is the working directory. Write an argument that starts with a dash as --host-arg=-x |
--restart-delay S |
Waits before starting a session that exited without saying the queue was empty (5) |
--max-restarts N |
Gives up on a session after N early exits in a row (10), so a missing host or a bad token does not loop forever; the launcher then exits 1 |
--idle-delay S |
Waits before a session that found nothing asks again while another session is still going (15). The wait doubles with each empty answer in a row and starts over after a session that ran for a minute or more or exited early |
--idle-max S |
Longest idle wait (300) |
A session that exits without printing KBL_QUEUE_EMPTY (a crash, a killed process, a host that ran out of context) is
started again, and the item it held goes to another session once its claim lapses (90 seconds by default). A session
that found nothing ready asks again after --idle-delay, then after twice that, up to --idle-max, while any other is
going, because that one may hold an item that will come back. Every ask starts a host and spends its tokens, so the
backoff keeps an idle session cheap. A launcher killed with SIGKILL leaves a private config directory in the temp
directory; the next launcher removes it. Ctrl-C stops every host and the launcher. The launcher ends by itself when every session has found
the queue empty. node dev/check-agents.mjs runs three sessions with a scripted stand-in for the host.
One agent can run a pool of worker agents of any vendor through its own kbl-mcp. Point KBL_SUPERVISE_CONFIG at a
TOML file of launch profiles (example profiles for Claude Code, Codex CLI and GitHub Copilot CLI are in
docs/supervise-profiles.md), and the agent gets three more tools:
| Tool | Does |
|---|---|
supervise_start {count, filter, profile?, model?} |
Keeps count workers on the work the filter matches, each with its own worker token, held to the filter. The profile and model come from the config's fit table unless given |
supervise_stop {worker} or {all: true} |
Stops one worker, or every worker and the top-up |
supervise_status |
Workers and what each holds, who finished or failed since the last look (a worker that fails or exits at once also shows the last line of its log), ready counts by kind and tier, and the top-up state |
Set git_identity on a profile so workers commit as an identity you choose, and turn off the vendor's Co-Authored-By trailer (Claude Code: --settings with {"attribution": false}, v2.1.281+); see commit identity.
A worker starts with only the environment names in its profile's pass_env. On macOS, Claude Code needs USER there to read its saved login, or an ANTHROPIC_API_KEY; otherwise workers exit with "Not logged in".
kbl-mcp makes no model calls: it runs the configured command, without a shell, or calls the configured hook, and
picks a profile by a fixed table. A timer tops the pool up while ready work matches. Stopping a worker gives back the
item it holds at once. A hosted (hook) worker has no process to watch, so it calls worker_finish when it is done: the
supervisor drops it from the pool and the top-up can replace it. node dev/check-supervise.mjs
runs a pool of scripted workers (dev/fake-worker.mjs) against the dev stack. See
docs/design/supervise.md.
A scripted planner and workers make the same tool calls a model would, so a run needs no model key. A seed decides the tasks and what happens to each: most are finished, some are handed back once and then finished, some are handed back every time and dead-lettered, and some are given up at once. Which worker takes a task does not change its fate, so a seed always ends every task the same way.
cargo build -p kbl-mcp -p kbl-tool
node dev/scripted.mjs --seed 2 --workers 3 # runs a job and checks each task ended as the seed says
node dev/check-scripted.mjs # runs one seed twice with different crews and compares
node --test dev/lib/script.test.mjs # the seed rules, with no Felix
node dev/check-death.mjs # kills workers holding tasks, restarts one, and finishes a task twice
node dev/check-poison.mjs # a task that always fails and one that is given up are both task_dead
node dev/check-tracker-triage.mjs # a scripted agent answers four triage items; a person acts on two (needs the tracker built too)
node dev/check-tracker-policy.mjs # a policy file accepts routine triage by rule and leaves safety-tagged triage for a person (needs the tracker built too)
node dev/check-tracker-ingest.mjs # kbl-ingest polls one issue from a stand-in GitHub again and again, and after losing its state, and imports it once
node dev/check-tracker-fix-check.mjs # a red check on an agent's pull request becomes one claimable fix_check item, and a green head ends it
kbl-tool run log <run> # prints a run's log, one JSON record per lineThe dev checks start the tracker with KBL_REVIEW_LIMIT=0. The tracker's own default is 3, which pauses new fix claims once three agent PRs are in review (the review limit); a check that finishes many fixes would stall at it. A check that tests the limit passes its own value.
The death check kills a worker and lets a stalled claim lapse with a 2 second claim visibility so it finishes quickly, and restarts a worker under the default 90 seconds to show it does not wait for the claim to lapse.
To add it to Claude Code, put this in a project's .mcp.json (or use claude mcp add):
{
"mcpServers": {
"felix": {
"command": "/path/to/target/debug/kbl-mcp",
"env": {
"KBL_RUN": "demo",
"KBL_AGENT": "w1",
"KBL_FELIX_TOKEN": "<the agent's Felix token>",
"KBL_FELIX_CA_FILE": "/path/to/dev/state/broker-cert.pem"
}
}
}
}Two variables are required, and one way to authenticate:
| Variable | What |
|---|---|
KBL_RUN |
The run the agent works in |
KBL_AGENT |
The agent's name in that run, such as w1 |
KBL_FELIX_TOKEN |
The agent's Felix token for the broker, used as it is until it expires. It is read from the environment only, never from a flag, so it stays out of the process list |
A Felix token from a production control plane lasts 15 minutes, and a fixed one cannot be replaced while kbl-mcp
runs. To keep an agent working for longer, give it an ID token instead and let it renew its own Felix token. Leave
KBL_FELIX_TOKEN unset and set a control plane and one source for the ID token:
| Variable | What |
|---|---|
KBL_FELIX_CONTROL_PLANE |
The control plane's address, such as https://felix.example.com. Plain http is accepted only for this machine, because the ID token goes there as a bearer credential |
KBL_FELIX_ID_TOKEN_FILE |
A file holding the ID token. It must be mode 600 or 400. It is read again on every renewal, so whatever keeps the token fresh only has to rewrite the file |
KBL_FELIX_ID_TOKEN_COMMAND |
A command whose output is the ID token, run through sh -c on every renewal (cmd /C on Windows). Use it instead of the file when the host can mint one on demand |
The command is passed to sh -c, so its text shows in the process list while it runs: put no secret in it, and let it read one from a file or the environment. The mode check applies on Linux and macOS.
Set exactly one of the file and the command, and not KBL_FELIX_TOKEN as well. kbl-mcp trades the ID token at
/v1/tenants/<tenant>/token/exchange for a token for the broker when it starts, and again once two thirds of that
token's life has passed, whether or not the agent is busy. The Felix client keeps its publish and cache streams open
for the life of a connection, and a write the broker forwards to another broker carries the token its stream opened
with, so after each renewal kbl-mcp opens a new connection and switches to it
(felix issue 2736). A claim the agent holds keeps standing across the
switch: Felix ties an ack or an extension to the delivery, not to the connection. If a renewal fails (the control plane is down, the
ID token expired or was revoked), kbl-mcp keeps using the Felix token it has and tries again every few seconds. Once
that token expires too, calls that open a new stream fail and the error says the control plane refused the ID token.
Nothing prints a token, the control plane's answer or the command line, and the command's error output is
discarded.
The ID token itself must outlast the agent's work or be replaced in the file or by the command before then, since
kbl-mcp does not renew that.
The rest are the variables kbl-tool uses, with the same defaults: KBL_TENANT,
KBL_NAMESPACE, KBL_FELIX_BROKER, KBL_FELIX_BROKER_NAME and KBL_FELIX_CA_FILE. The default for the
certificate file is relative to the host's working directory, so give an absolute path when a host starts the server.
Issuing a token per agent is not built yet, so for now dev/check-mcp.mjs asks the stand-in identity provider for the
administrator's. node dev/check-renewal.mjs starts a worker from an ID token file, renews its Felix token every second,
and checks a claim it holds survives.
You need Node 22 or later, Python 3, a Chrome or Chromium, and Rust 1.97 or later for the crates. From the repository root:
# Syntax of the page and scripts, and no em dashes in the docs
node scripts/lint.mjs
# Rewrite the fixtures; `git diff prototype` should stay empty
python3 prototype/make-intake-fixture.py
# Fold the dashboard fixtures: My queue, the board, the review limit, metrics, actions, the burst,
# and the decision replay (story, explanation at a step, fork, redo limit)
node scripts/check-intake.mjs
# Build and test the Rust crates
cargo test --workspace
# Run the previous build of the tracker and this one over the same log (needs the dev stack, below, and a
# checkout of the previous commit built into its own target directory)
KBL_TRACKER_OLD=<previous>/kbl-tracker KBL_MCP_OLD=<previous>/kbl-mcp node dev/check-upgrade.mjs
# Build and test the dashboard (see dashboard/README.md for the one-time setup)
cd dashboard && npm ci && npm run wasm && npm test && cd ..
# Serve the repository, then open http://localhost:8000/prototype/intake-frame.html (?view=queue|list|board|metrics, ?fixture=fixture-work-capped.json, fixture-work-burst.json or fixture-work-quiet.json, ?select=gh-801, ?theme=light, ?density=compact;
# fixture-work-replay.json with ?story=gh-792 opens the decision replay, ?story=gh-795 the redo limit)
python3 -m http.server 8000check-intake.mjs looks for Chrome, Chromium or Edge in the usual install paths; set CHROME to a binary
otherwise. Chrome gets 60 s to start (CHROME_STARTUP_MS changes that); if it exits or never comes up, the error
includes its exit code and stderr. The launcher is scripts/lib/browser.mjs; new checks should use it.
scripts/shoot-intake.mjs takes the stills in docs/screenshots/ from the same page, including every view and state in both themes under docs/screenshots/ux/.
Press ? in the frame for its keys, or Ctrl+K for the command palette. docs/usability-test.md is the script for testing it with people.
prototype/intake-frame.html?demo=1 (add &theme=light for the light theme) plays a 30-second scripted story from prototype/fixture-work-demo.json: records only, nothing generated. scripts/record-demo.mjs records it frame by frame to mp4 and webp; the page owns its clock, so no frame is dropped.
CI runs five jobs: lint (with the fixture regeneration), dashboard frame, the Rust checks (format, clippy, tests), the dashboard build (WebAssembly fold, TypeScript checks, tests, Vite build) and the dev stack (which also creates a run, checks that creating it again is refused, and starts kbl-mcp to list its tools), and requires the CI ok check.
- docs/work-tracker.md: the tracker, its work kinds, grants, budgets and the dashboard
- docs/decision-replay.md: how an agent's decisions are recorded and read back
- docs/threat-model.md: who can reach what, and the check behind every route and record kind
- docs/deploy.md: the container images and the Helm chart for running KBL on Kubernetes
- docs/ingest-setup.md: setting up ingest: a starter config,
kbl-ingest checkand its dry run - docs/metrics.md: the Prometheus metrics of the tracker, ingest and
kbl-mcp, and how to expose them - docs/upgrades.md: upgrading a running KBL and going back, and the record format rules behind it
- docs/dashboard-research.md: the evidence behind the dashboard
- docs/brand/story.md: the story of the product
- docs/design.md: the design, data model and build order
- Felix docs
See CONTRIBUTING.md.
MIT. See LICENSE.

