Skip to content
GetFelixPublic

About

KBL (Kanban By Log): a work tracker for coding agents, backed by Felix. Bugs come in from GitHub, Azure DevOps or Jira, each item goes to one agent over MCP, and people guide it from a dashboard.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

KBL

KBL

CI License: MIT Minimum supported Rust 1.97

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.

My queue: what needs you, what agents hold, and what is waiting

Decision replay: scrub through an agent's decisions and see the state at each step

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.

Quick start

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.sh

Without 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.sh

With 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.

  1. Open the dashboard. Open the printed link. Its queue is empty.

  2. 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.

  3. Connect Claude Code. Build kbl-mcp on 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 download kbl-mcp and pass its path with --mcp, in place of the cargo build line:

    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 claims demo-1, and the dashboard shows the item held by agent1. connect.mjs writes the file with mode 600 (it holds the agent's tracker token) and with absolute paths, so any directory works. The stack has agents agent1 to agent8, one tracker token each. The agent's ID token goes in dev/state/agent1.id-token (mode 600), and the config points KBL_FELIX_ID_TOKEN_FILE and KBL_FELIX_CONTROL_PLANE at it, so kbl-mcp renews its Felix token by itself. The ID token lasts 24 hours: run node dev/connect.mjs agent1 again to write a new one, and the running kbl-mcp picks it up at its next renewal. --fixed-token writes a Felix token into the config as KBL_FELIX_TOKEN instead; that one is not renewed, so after 24 hours run connect.mjs again 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 from node dev/open-dashboard.mjs. .mcp.json holds tokens and is in .gitignore.

  4. 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-ok

    With the release binaries on your PATH there is nothing to build; skip the cargo 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 --labels drops the agent-ok default (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 runs kbl-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-only to stop after the check, or --once for a single poll. The config it writes is dev/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-config runs the existing file as it is, for a config you edited by hand.

    What the mode means: admit imports 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. propose waits for a person before anything is queued. A rule that sets "triage": "skip" (with admit) 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.

  5. Stop it with dev/down.sh, which also deletes its data.

Troubleshooting

  • See what is running. dev/ps.sh lists the containers and their state; dev/logs.sh [service] prints their logs (FOLLOW=1 dev/logs.sh tracker follows). Both use the engine up.sh chose.
  • 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.mjs for 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-mcp or kbl-ingest not found. The scripts look at the flag, KBL_MCP / KBL_INGEST, target/release, target/debug, ~/.kbl/bin, dev/state/bin and your PATH, 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.sh then dev/quickstart.sh starts 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.

What it shows about Felix

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_if at the version read, so a stale write is refused.
  • One log is the record. work.events holds 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 --default loads 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.

What you will be able to do

  • 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

Felix features it uses

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.

How it works

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.

Status

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.

Running Felix locally

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 data

It 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.

Creating a run

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 4
created 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.

Giving an agent its tools

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.

Getting the binaries

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 PATH

On 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.mjs

The task tools

A 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.mjs

Running agents in a loop

A 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:8790

The 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.

Supervising a pool of workers

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.

Scripted agents

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 line

The 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.

Developing

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 8000

check-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.

Documentation

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.

About

KBL (Kanban By Log): a work tracker for coding agents, backed by Felix. Bugs come in from GitHub, Azure DevOps or Jira, each item goes to one agent over MCP, and people guide it from a dashboard.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages