Self-hosted, sharable kanban for humans and agents. One 4.7 MB binary, 5 MB of RAM, 10 to 60 tokens per agent reply, starts in 3 ms, zero setup.
Rust ai-agentsclaude-codeclicodexcoding-agentskanbanlocal-firstmcpmcp-servermodel-context-protocolproductivityproject-managementraspberry-pirustself-hostedsqlitetask-manager
Comment on each pull request with what it costs to run
emanuele-em9a02b76780cc
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex bbcc353..15101f7 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -27,7 +27,7 @@ For a change to the board, also try it in a browser, in light and dark mode.## What a good change looks like-- **Light.** No new dependency without a strong reason. If it could cost speed or memory, measure before and after.+- **Light.** No new dependency without a strong reason. If it could cost speed or memory, measure before and after: CI comments on every pull request with what it changes in size, memory, speed and agents' tokens, and `python3 .github/resources/measure.py --help` runs the same measurements on your machine.- **Few tokens.** MCP replies stay short plain text; say what a change does to their size.- **Plain web.** The board is HTML, CSS and JavaScript with no build step, and runs on Safari 13.1, Chrome 80 and Firefox 78.- **Small commits.** One change per commit, with a short imperative subject and a body that says why.diff --git a/.github/resources/measure.py b/.github/resources/measure.pynew file mode 100644index 0000000..a4660b3--- /dev/null+++ b/.github/resources/measure.py@@ -0,0 +1,258 @@+#!/usr/bin/env python3+"""Measures what two Kanzo builds cost to run, side by side, and prints JSON.++ measure.py --base BIN Cargo.lock --head BIN Cargo.lock [--pr N] [--rounds 3]++Each build gets its own throwaway data folder and a board of 3,000 tasks. The+builds take turns, round after round, so a busy runner slows both alike; every+number is the median of the rounds. Peak memory needs Linux's /proc.++Only the standard library, so it runs on any runner without installing anything.+"""++import argparse+import http.client+import json+import os+import socket+import statistics+import subprocess+import tempfile+import time++TASKS = 3000+STARTS = 10+BOARD_LOADS = 20+DESCRIPTION = (+ "Users on slow connections see the board flash empty before the tasks load.\n\n"+ "- Keep the last board in memory between polls\n"+ "- Only redraw the columns that changed\n"+ "- Check it on Safari 13.1, Chrome 80 and Firefox 78\n"+)+++def free_port():+ with socket.socket() as s:+ s.bind(("127.0.0.1", 0))+ return s.getsockname()[1]+++def proc_status(pid):+ """Resident memory now and at its peak, in bytes, and the thread count."""+ if not os.path.exists("/proc"):+ # Elsewhere, like a Mac trying the script, there's only memory now.+ rss = int(subprocess.check_output(["ps", "-o", "rss=", "-p", str(pid)])) * 1024+ threads = len(subprocess.check_output(["ps", "-M", "-p", str(pid)]).splitlines()) - 1+ return rss, rss, threads+ fields = {}+ with open(f"/proc/{pid}/status") as f:+ for line in f:+ key, _, value = line.partition(":")+ fields[key] = value.split()[0] if value.split() else ""+ return int(fields["VmRSS"]) * 1024, int(fields["VmHWM"]) * 1024, int(fields["Threads"])+++def tree_size(path):+ return sum(os.path.getsize(os.path.join(d, f)) for d, _, files in os.walk(path) for f in files)+++class Board:+ """A running `kanzo` board on a free port, with a keep-alive connection to it."""++ def __init__(self, binary, home):+ self.port = free_port()+ self.proc = subprocess.Popen(+ [binary, "--home", home, "--port", str(self.port), "--no-open"],+ stdout=subprocess.DEVNULL,+ )+ start = time.perf_counter()+ while True:+ try:+ socket.create_connection(("127.0.0.1", self.port), timeout=1).close()+ break+ except OSError:+ if self.proc.poll() is not None:+ raise SystemExit(f"{binary} exited with {self.proc.returncode}")+ if time.perf_counter() - start > 10:+ raise SystemExit(f"{binary} did not listen within 10 s")+ time.sleep(0.0002)+ self.start_ms = (time.perf_counter() - start) * 1000+ self.conn = http.client.HTTPConnection("127.0.0.1", self.port, timeout=30)++ def request(self, method, path, body=None):+ headers = {"Content-Type": "application/json"} if body is not None else {}+ self.conn.request(method, path, body=json.dumps(body) if body is not None else None, headers=headers)+ res = self.conn.getresponse()+ data = res.read()+ if res.status >= 400:+ raise SystemExit(f"{method} {path}: {res.status} {data[:200]!r}")+ return data++ def json(self, method, path, body=None):+ return json.loads(self.request(method, path, body))++ def stop(self):+ self.conn.close()+ self.proc.terminate()+ self.proc.wait(timeout=10)+++def seed(board):+ """A busy project spread over every column, and a small one for agents' replies."""+ board.json("POST", "/api/projects", {"slug": "bench", "name": "Bench"})+ statuses = board.json("GET", "/api/board")["statuses"]+ for i in range(TASKS):+ task = board.json(+ "POST",+ "/api/tasks",+ {"project": "bench", "title": f"Keep the board steady while it reloads ({i})", "description": DESCRIPTION},+ )+ status = statuses[i % len(statuses)]+ if status != statuses[0]:+ board.json("PATCH", f"/api/tasks/{task['id']}", {"status": status})+ if i % 5 == 0:+ board.json("POST", f"/api/tasks/{task['id']}/comments", {"body": "Started on this; the poll is next."})++ board.json("POST", "/api/projects", {"slug": "small", "name": "Small"})+ ids = []+ for i in range(8):+ task = board.json(+ "POST", "/api/tasks", {"project": "small", "title": f"Small task number {i + 1}", "description": DESCRIPTION}+ )+ ids.append(task["id"])+ for body in ("Looked into it: the cache is cold on first load.", "Fixed in the last commit."):+ board.json("POST", f"/api/tasks/{ids[0]}/comments", {"body": body})+ return ids+++class Mcp:+ """`kanzo mcp` on stdio, as an agent starts it, in a folder that isn't a git repo."""++ def __init__(self, binary, home, cwd):+ self.proc = subprocess.Popen(+ [binary, "--home", home, "mcp"], cwd=cwd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True+ )+ self.next_id = 0++ def send(self, method, params=None, notify=False):+ msg = {"jsonrpc": "2.0", "method": method}+ if params is not None:+ msg["params"] = params+ if not notify:+ self.next_id += 1+ msg["id"] = self.next_id+ self.proc.stdin.write(json.dumps(msg) + "\n")+ self.proc.stdin.flush()+ if notify:+ return None+ while True:+ line = self.proc.stdout.readline()+ if not line:+ raise SystemExit(f"kanzo mcp closed during {method}")+ reply = json.loads(line)+ if reply.get("id") == self.next_id:+ if "error" in reply:+ raise SystemExit(f"{method}: {reply['error']}")+ return reply["result"]++ def call(self, tool, args):+ result = self.send("tools/call", {"name": tool, "arguments": args})+ return "".join(c.get("text", "") for c in result.get("content", []))++ def stop(self):+ self.proc.stdin.close()+ self.proc.wait(timeout=10)+++def measure(binary, lock):+ binary = os.path.abspath(binary) # `kanzo mcp` runs from another folder+ out = {"binary_bytes": os.path.getsize(binary)}+ with open(lock) as f:+ out["crates"] = sum(1 for line in f if line.strip() == "[[package]]") - 1 # Kanzo itself++ with tempfile.TemporaryDirectory() as tmp:+ home = os.path.join(tmp, "home")+ subprocess.run([binary, "--home", home, "init"], check=True, stdout=subprocess.DEVNULL)++ starts = []+ for _ in range(STARTS):+ board = Board(binary, home)+ board.request("GET", "/api/ping")+ starts.append(board.start_ms)+ board.stop()+ out["start_ms"] = statistics.median(starts)++ board = Board(binary, home)+ board.request("GET", "/api/ping")+ time.sleep(1)+ out["idle_rss_bytes"], _, out["idle_threads"] = proc_status(board.proc.pid)+ out["page_bytes"] = sum(len(board.request("GET", p)) for p in ("/", "/app.js", "/logo.png"))+ out["empty_db_bytes"] = tree_size(home)++ ids = seed(board)+ loads, size = [], 0+ for _ in range(BOARD_LOADS):+ start = time.perf_counter()+ size = len(board.request("GET", "/api/board"))+ loads.append((time.perf_counter() - start) * 1000)+ out["board_ms"] = statistics.median(loads)+ out["board_bytes"] = size+ time.sleep(1)+ out["loaded_rss_bytes"], out["peak_rss_bytes"], out["loaded_threads"] = proc_status(board.proc.pid)++ mcp = Mcp(binary, home, tmp)+ init = mcp.send(+ "initialize",+ {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "bench", "version": "1"}},+ )+ mcp.send("notifications/initialized", notify=True)+ out["instructions"] = init.get("instructions", "")+ out["tools"] = mcp.send("tools/list")["tools"]+ out["tools_bytes"] = len(json.dumps(out["tools"], separators=(",", ":")))+ out["replies"] = {+ "list_projects": mcp.call("list_projects", {}),+ "list_tasks (8)": mcp.call("list_tasks", {"project": "small"}),+ "get_task": mcp.call("get_task", {"id": f"small#{ids[0]}"}),+ "next_task": mcp.call("next_task", {"project": "small"}),+ "add_comment": mcp.call("add_comment", {"id": f"small#{ids[1]}", "body": "Done the first half."}),+ "update_task": mcp.call("update_task", {"id": f"small#{ids[1]}", "status": "review"}),+ "create_task": mcp.call("create_task", {"project": "small", "title": "Write the docs"}),+ }+ out["mcp_rss_bytes"], out["mcp_peak_rss_bytes"], _ = proc_status(mcp.proc.pid)+ mcp.stop()++ board.stop()+ out["db_bytes"] = tree_size(home)+ return out+++def median_of(rounds):+ """Numbers as the median of the rounds; text from the last round."""+ merged = {}+ for key, last in rounds[-1].items():+ if isinstance(last, (int, float)) and not isinstance(last, bool):+ merged[key] = statistics.median(r[key] for r in rounds)+ else:+ merged[key] = last+ return merged+++def main():+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ parser.add_argument("--base", nargs=2, metavar=("BIN", "LOCK"), required=True)+ parser.add_argument("--head", nargs=2, metavar=("BIN", "LOCK"), required=True)+ parser.add_argument("--pr", type=int)+ parser.add_argument("--rounds", type=int, default=3)+ args = parser.parse_args()++ rounds = {"base": [], "head": []}+ for _ in range(args.rounds):+ for name in rounds:+ rounds[name].append(measure(*getattr(args, name)))+ result = {name: median_of(r) for name, r in rounds.items()}+ result.update(pr=args.pr, tasks=TASKS, rounds=args.rounds)+ print(json.dumps(result, indent=1))+++if __name__ == "__main__":+ main()diff --git a/.github/resources/report.py b/.github/resources/report.pynew file mode 100644index 0000000..bb79a81--- /dev/null+++ b/.github/resources/report.py@@ -0,0 +1,162 @@+#!/usr/bin/env python3+"""Turns measure.py's JSON into the Markdown comment on a pull request.++ report.py resources.json > comment.md++With ANTHROPIC_API_KEY set, it counts the tokens agents read with Claude's own+tokenizer; without it, it gives their size in bytes. The JSON comes from the pull+request's code, so only its numbers reach the comment, never its text.+"""++import json+import os+import re+import sys++MARKER = "<!-- kanzo-resources -->"+MODEL = "claude-opus-5-5"+++class Tokens:+ """Counts tokens the way agents pay for them: what a request costs more with the text in it."""++ def __init__(self):+ from anthropic import Anthropic++ self.client = Anthropic()+ self.empty = self.count()++ def count(self, text=".", **extra):+ return self.client.messages.count_tokens(+ model=MODEL, messages=[{"role": "user", "content": text}], **extra+ ).input_tokens++ def text(self, text):+ return self.count(text or ".") - self.empty++ def tools(self, tools):+ defs = [{"name": t["name"], "description": t.get("description", ""), "input_schema": t["inputSchema"]} for t in tools]+ return self.count(tools=defs) - self.empty++ def system(self, text):+ return self.count(system=text) - self.empty if text else 0+++def label(name):+ """A reply's name from the JSON, kept to plain characters so it can't add Markdown or mentions."""+ return re.sub(r"[^a-z0-9_ ()]", "", name.lower())[:40]+++def agents_rows(build, tokens):+ """Tool list, instructions and replies, in tokens or in bytes."""+ if tokens:+ rows = {+ "Tool list, read every session": (tokens.tools(build["tools"]), "tokens"),+ "Instructions, read every session": (tokens.system(build["instructions"]), "tokens"),+ }+ for name, text in build["replies"].items():+ rows[f"Reply to `{label(name)}`"] = (tokens.text(text), "tokens")+ return rows+ rows = {+ "Tool list, read every session": (build["tools_bytes"], "bytes"),+ "Instructions, read every session": (len(build["instructions"].encode()), "bytes"),+ }+ for name, text in build["replies"].items():+ rows[f"Reply to `{label(name)}`"] = (len(text.encode()), "bytes")+ return rows+++def size(n):+ n = abs(n)+ if n >= 1_000_000:+ return f"{n / 1_000_000:.2f} MB"+ if n >= 1_000:+ return f"{n / 1_000:.1f} KB"+ return f"{n:.0f} B"+++def fmt(value, unit):+ if unit == "bytes":+ return size(value)+ if unit == "ms":+ return f"{value:.1f} ms"+ return f"{value:,.0f} {unit}" if unit else f"{value:,.0f}"+++def change(base, head, unit, noise):+ """The change and whether it's more than noise: 1% for sizes and counts, 15% for times."""+ diff = head - base+ if diff == 0 or (unit == "ms" and abs(diff) < 0.5):+ return "same", False+ pct = diff / base * 100 if base else 100.0+ sign = "+" if diff > 0 else "−"+ text = f"{sign}{fmt(abs(diff), unit)} ({sign}{abs(pct):.1f}%)"+ real = abs(pct) >= noise+ return (f"**{text}**" if real else text), real+++def main():+ with open(sys.argv[1]) as f:+ data = json.load(f)+ base, head = data["base"], data["head"]+ tokens = Tokens() if os.environ.get("ANTHROPIC_API_KEY") else None++ # (section, name, key, unit, noise in %)+ measured = [+ ("Program", "Binary", "binary_bytes", "bytes", 1),+ ("Program", "Crates in Cargo.lock", "crates", "", 0),+ ("Memory", "Idle board", "idle_rss_bytes", "bytes", 5),+ ("Memory", f"Board with {data['tasks']:,} tasks loaded", "loaded_rss_bytes", "bytes", 5),+ ("Memory", "Peak of the board", "peak_rss_bytes", "bytes", 5),+ ("Memory", "`kanzo mcp` after a session", "mcp_rss_bytes", "bytes", 5),+ ("Memory", "Threads when idle", "idle_threads", "", 0),+ ("Speed", "Start", "start_ms", "ms", 15),+ ("Speed", f"`/api/board` with {data['tasks']:,} tasks", "board_ms", "ms", 15),+ ("Storage", "Empty database", "empty_db_bytes", "bytes", 1),+ ("Storage", f"Database with {data['tasks']:,} tasks", "db_bytes", "bytes", 1),+ ("Storage", f"`/api/board` reply with {data['tasks']:,} tasks", "board_bytes", "bytes", 1),+ ("Storage", "Board page (HTML, JS, logo)", "page_bytes", "bytes", 1),+ ]+ sections = {"Agents": []}+ for section, name, key, unit, noise in measured:+ if key in base and key in head:+ sections.setdefault(section, []).append((name, base[key], head[key], unit, noise))+ base_agents, head_agents = agents_rows(base, tokens), agents_rows(head, tokens)+ for name, (head_value, unit) in head_agents.items():+ base_value = base_agents.get(name, (0, unit))[0]+ sections["Agents"].append((name, base_value, head_value, unit, 1))++ lines, moved = [], {}+ for section, rows in sections.items():+ lines += [f"**{section}**", "", "| | main | this PR | change |", "| --- | ---: | ---: | ---: |"]+ for name, b, h, unit, noise in rows:+ text, real = change(b, h, unit, noise)+ lines.append(f"| {name} | {fmt(b, unit)} | {fmt(h, unit)} | {text} |")+ if real:+ short = re.sub(r" \(.*\)", "", name).split(", ")[0].replace("`", "")+ moved.setdefault(section, []).append(f"{short[0].lower()}{short[1:]} {text.strip('*').split(' (')[0]}")+ lines.append("")++ if moved:+ summary = "If merged, " + "; ".join(f"{s.lower()}: {', '.join(m)}" for s, m in moved.items()) + "."+ else:+ summary = "If merged, nothing moves by more than noise."+ note = (+ f"Tokens counted with `{MODEL}`'s tokenizer."+ if tokens+ else "Agents' text is in bytes: add an `ANTHROPIC_API_KEY` secret to count tokens."+ )+ print(MARKER)+ print("### Resources")+ print()+ print(summary)+ print()+ print("\n".join(lines))+ print(+ f"<sub>Measured on GitHub's ubuntu-26.04 runner, median of {data['rounds']} round{"s" if data["rounds"] != 1 else ""} with the builds taking turns. "+ f"Changes in bold are past noise: 1% for sizes, 5% for memory, 15% for times. {note}</sub>"+ )+++if __name__ == "__main__":+ main()diff --git a/.github/workflows/resources-comment.yml b/.github/workflows/resources-comment.ymlnew file mode 100644index 0000000..28454b7--- /dev/null+++ b/.github/workflows/resources-comment.yml@@ -0,0 +1,56 @@+# Posts resources.yml's numbers on the pull request, as one comment it updates on+# every push. It runs main's report script, never the PR's code, so it can hold the+# token to comment and the Anthropic key that counts tokens, even for PRs from forks.+name: Resources comment++on:+ workflow_run:+ workflows: [Resources]+ types: [completed]++permissions:+ actions: read+ contents: read+ pull-requests: write++jobs:+ comment:+ if: github.event.workflow_run.conclusion == 'success'+ runs-on: ubuntu-26.04+ steps:+ - uses: actions/checkout@v7+ with:+ persist-credentials: false+ - uses: actions/download-artifact@v8+ with:+ name: resources+ run-id: ${{ github.event.workflow_run.id }}+ github-token: ${{ github.token }}+ path: ${{ runner.temp }}/resources+ # Ubuntu's own Python takes no packages outside a virtual environment.+ - run: python3 -m venv "$RUNNER_TEMP/venv" && "$RUNNER_TEMP/venv/bin/pip" install --quiet anthropic==2.3.0+ - run: >+ "$RUNNER_TEMP/venv/bin/python" .github/resources/report.py+ "$RUNNER_TEMP/resources/resources.json" > "$RUNNER_TEMP/comment.md"+ env:+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}+ # The PR number comes from the PR's own run, so it only counts if that PR's+ # head is the commit that was measured.+ - env:+ GH_TOKEN: ${{ github.token }}+ REPO: ${{ github.repository }}+ HEAD_SHA: ${{ github.event.workflow_run.head_sha }}+ run: |+ pr=$(jq -r '.pr' "$RUNNER_TEMP/resources/resources.json")+ [[ "$pr" =~ ^[0-9]+$ ]] || { echo "no PR number in the results"; exit 1; }+ if [ "$(gh api "repos/$REPO/pulls/$pr" --jq .head.sha)" != "$HEAD_SHA" ]; then+ echo "PR #$pr has moved on from $HEAD_SHA; its next run will comment"+ exit 0+ fi+ id=$(gh api "repos/$REPO/issues/$pr/comments" --paginate \+ --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("<!-- kanzo-resources -->"))) | .id' | head -1)+ if [ -n "$id" ]; then+ gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null+ else+ gh api "repos/$REPO/issues/$pr/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null+ fidiff --git a/.github/workflows/resources.yml b/.github/workflows/resources.ymlnew file mode 100644index 0000000..d87079f--- /dev/null+++ b/.github/workflows/resources.yml@@ -0,0 +1,41 @@+# Measures what a pull request does to Kanzo's size, memory, speed and agents'+# tokens: it builds main and the PR merged into main, and runs both side by side.+# resources-comment.yml posts the numbers on the PR. This half runs the PR's code,+# so it gets no secrets and can't write to the repo.+name: Resources++on:+ pull_request:++permissions:+ contents: read++concurrency:+ group: resources-${{ github.event.pull_request.number }}+ cancel-in-progress: true++jobs:+ measure:+ runs-on: ubuntu-26.04+ steps:+ # The PR merged into main, and its first parent: main as it is now.+ - uses: actions/checkout@v7+ with:+ fetch-depth: 2+ persist-credentials: false+ - run: git worktree add ../main HEAD^1+ - run: rustup update stable --no-self-update && rustup default stable+ # Each from its own folder, so each reads its own .cargo/config.toml.+ - run: cargo build --release --locked+ - run: cargo build --release --locked+ working-directory: ../main+ - run: >+ python3 .github/resources/measure.py+ --base ../main/target/release/kanzo ../main/Cargo.lock+ --head target/release/kanzo Cargo.lock+ --pr ${{ github.event.pull_request.number }}+ > resources.json+ - uses: actions/upload-artifact@v7+ with:+ name: resources+ path: resources.json