Skip to content

armgit / kanzo

Public Imported from GitHub
0

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.

Comment on each pull request with what it costs to run

emanuele-em9a02b76780cc
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.yml
new file mode 100644
index 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
+ fi
diff --git a/.github/workflows/resources.yml b/.github/workflows/resources.yml
new file mode 100644
index 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