kapptec

How Bun Got Ported to Rust — and What It Teaches Us About Working with Agents

2026-05-14T00:00:00+00:00

After the agent reported background command "Build Bun debug binary" completed (exit code 0) and I had a Bun binary compiled from Rust, I handed Claude the next task: analyze this PR and write a blog post on how Jarred Sumner pulled off the Zig-to-Rust port — so the rest of us can learn to work better with agents. What follows is what came back, possibly with traces of the Mythos model.

On May 14, 2026, Jarred Sumner merged PR #30412 — “Rewrite Bun in Rust” into oven-sh/bun. It was one of the largest single PRs in the history of public open source: 2,188 files changed, 1,009,257 lines added. It reimplemented an entire JavaScript runtime — bundler, package manager, HTTP/2/3 stack, dev server, transpiler, the lot — from Zig to Rust, while keeping the same architecture and the same test suite passing.

It almost certainly couldn’t have happened without Claude agents. The PR doesn’t say so out loud — the body just says “compiler-assisted tools for catching & preventing memory bugs” — but the commit history leaks the orchestration. Ten minutes after the merge, Jarred pushed another commit titled “Delete stray files” that removed 34 files from .claude/workflows/. Those files, briefly public in git history, tell the story.

This post is about what we can learn from that story — not about Bun specifically, but about how to set up a codebase, instructions, and tooling so that agents can do work humans alone couldn’t ship.

The leaked evidence

The deleted directory contained workflow scripts named in a deliberate phase order:

phase-a-port.workflow.js
phase-b0-cyclebreak / movein / moveout / verify.workflow.js
phase-b1-tier.workflow.js
phase-b2-cycle / fill / fix-bugs / keystone / ungate-tier / verify.workflow.js
phase-c-panic-swarm.workflow.js
phase-d-build-queue / crate-shard / todo-sweep / unsafe-audit /
       blocked-on-resolve / bundler-perfile / bundler-shard /
       recursive-ungate / subtree-batch.workflow.js
phase-e-body-port / mass-ungate / proper-port / test-bringup /
       scopeguard-sweep.workflow.js
phase-f-probe-swarm / test-swarm.workflow.js
phase-g-mega-swarm / test-swarm.workflow.js
phase-h-ci-tasks / dedup / deep-dive / diff-review / idioms-audit /
       libuv-audit / main-parity / unsafe-wrap.workflow.js
lifetime-classify.workflow.js

And one more file, .apply-lock-guard.sh:

#!/bin/bash
# Serialize Apply-phase agents on /root/bun-5 working tree.
# Usage: flock /root/bun-5/.apply-lock bash .apply-lock-guard.sh -- <command...>
exec "$@"

A four-line flock wrapper to serialize parallel agents writing to a shared working tree at /root/bun-5. Whoever was running this had many agents simultaneously editing the same checkout and used filesystem locks to keep them from colliding.

The body of phase-a-port.workflow.js is more telling:

export const meta = {
  name: "phase-a-port",
  description: "Phase A: draft .rs for a batch of .zig files (implement → verify → fix)",
  phases: [
    { title: "Implement", detail: "one agent per .zig writes draft .rs per PORTING.md" },
    { title: "Verify",    detail: "adversarial check of .rs against .zig + PORTING.md rules" },
    { title: "Fix",       detail: "apply verifier findings to .rs" },
  ],
};

One agent per Zig file. A second adversarial agent verifies against a PORTING.md style guide. A third applies the verifier’s findings. All outputs are JSON-Schema-validated (IMPL_SCHEMA, VERIFY_SCHEMA are defined further down) so the next phase can consume them mechanically.

What’s still visible in the tree

The workflows got deleted, but their fingerprints are everywhere:

1,292 .zig files retained alongside 1,432 .rs files. The root CLAUDE.md is explicit (line 141): “These are the original Zig implementation, kept only as a porting reference — they are not compiled and not shipped. New code goes in .rs. When fixing a bug or porting a behavior, the .zig sibling is the source of truth for intended semantics.”

10,841 PORT NOTE: / PERF(port): / TODO(port): comments across the Rust source. That’s an average of seven to eight per file. They aren’t decorative. Look at src/bundler/defines.rs:

// PORT NOTE: Zig pre-counted `key_buf_len`/`e_strings_to_allocate` to size
// two bump allocations, then `iter.reset()` and re-walked. With per-entry
// copies the pre-sizing pass is dead — emit directly.
// PERF(port): was single-buffer key arena; now per-entry Vec reuse.

Each annotation explains why the Rust diverges from the Zig — for the next agent that reads the file.

108 Cargo crates in a single workspace, prefixed bun_core, bun_sys, bun_paths, bun_jsc, bun_runtime, bun_js_parser, bun_js_printer, bun_bundler, bun_install, … Tiny crates aren’t just an architectural choice — they’re a parallelism boundary. Each crate is a sharded work unit an agent can own, check, and finish independently with cargo check -p <crate>.
Hard-coded branch naming. CLAUDE.md line 266: “Branch names must start with claude/. This is a requirement for the CI to work.” The CI distinguishes agent commits from human ones.
A prescriptive style guide masquerading as developer docs. src/CLAUDE.md (14 KB) contains a six-column table telling you which std:: APIs are forbidden and what to use instead — bun_sys::File over std::fs::File, bun_paths::dirname over Path::parent, bun_core::env_var::*::get() over std::env::var, and so on. No discovery, no judgment. The agents don’t get to “find a Rusty equivalent.” They get told.
A “code review self-check” section in the same file:

Before writing code that makes a non-obvious choice, pre-emptively ask “why this and not the alternative?” If you can’t answer, research until you can — don’t write first and justify later.

And, bluntly, in the Important Notes section:

Be humble & honest — NEVER overstate what you got done or what actually works in commits, PRs or in messages to the user.

That last one only exists because someone — many someones — were overstating.

The phases as a thinking pattern

Read the phase names as a sentence, not a list:

A — implement a first draft (one agent per file)
B0–B2 — break dependency cycles, move types between crates, tier them so each crate compiles
C — sweep panics out of the codebase (“panic-swarm”)
D — fan out per-crate, per-subtree, per-bundler-file work; sweep TODOs and audit unsafe
E — port real function bodies on top of the now-compiling skeleton
F–G — swarm probes and tests
H — diff review, dedup, idiom audit, libuv parity, unsafe wrap-up, CI cleanup

The shape is a draft, then a structural pass to make it compile, then bodies, then tests, then audits. Each phase has different invariants, different inputs, different verifier prompts. A single “port this codebase” mega-prompt would have produced slop — broken down this way, each phase becomes a small enough problem to give to an agent with a tight contract.

Portable lessons

If you take one thing from this, take this: the workflow scripts leaked because the agent infrastructure was project-specific, not generic. Jarred didn’t run “Claude, port my repo.” He built a porting harness for his repo, with his conventions, his crate layout, and his style guide, and then ran agents through it. The model is the same one anyone can use; the leverage came from the harness around it.

Specific patterns worth stealing:

1. Keep the old code in-tree as ground truth. Don’t delete the Zig source the day you check in the Rust. Agents lose track of intent between sessions; the original is the only stable reference for “what is this supposed to do.” 1,292 .zig files weren’t dead weight — they were the spec.

2. Annotate every divergence with WHY, not WHAT. PORT NOTE: reshaped for borrowck — drop deflate borrow before re-borrowing self. The next agent doesn’t need to be told that Rust has a borrow checker. It needs to be told that this specific line exists because a previous agent already fought through the obvious naive version and that version didn’t work. Without this, every agent re-discovers and re-litigates the same workarounds.

3. Write a prescriptive style guide, not an aspirational one. If you have an opinion, encode it as a forbidden/replacement table. Agents are excellent rule-followers and terrible taste-havers. Don’t let them choose between std::fs::File and your wrapper — say you must use the wrapper, here is the wrapper, here is when to call which method.

4. Split implement from verify from apply. The phase-A workflow had three roles per file: drafter, adversarial reviewer, fixer. The adversarial agent can’t see the drafter’s reasoning, only its output and the rules. This forces the drafter to be explicit (because the reviewer will catch implicit assumptions) and stops the kind of self-validating drift that single-agent loops produce.

5. Demand structured outputs between phases. IMPL_SCHEMA and VERIFY_SCHEMA weren’t optional — the workflow validates them. When agents hand off to other agents, free-form prose loses information. Make them fill in a JSON object with rs_path, confidence, todos, rs_loc, note. The next phase parses that, doesn’t re-read essays.

6. Shard the work for parallelism, lock the writes. ~200 small crates make parallelism cheap because the cargo check granularity matches the agent granularity. A flock guard around the working tree makes the parallelism safe. Both are needed — the architecture and the mechanism.

7. Tag agent work in CI. claude/-prefixed branches give you a way to gate, count, and roll back agent-produced changes separately from human ones. This is the boring kind of infrastructure that becomes essential the moment your agent volume exceeds your review volume.

8. Write rules to fight confabulation explicitly. “NEVER overstate what you got done.” “Pre-emptively ask why this and not the alternative.” These read like leadership advice, but in context they’re load-bearing — they exist because the failure mode of an agent saying “all tests pass” when seven crates didn’t compile is real, and it has to be addressed in the system prompt, not at code review time.

9. Make build and test one command. bun bd test <file> builds and runs. Agents don’t have to remember a two-step incantation, which means they don’t fail by forgetting step two. “Get your tests to pass. If you didn’t run the tests, your code does not work” only works as an instruction if running tests is a single tool call.

10. Treat the meta-infrastructure as part of the work. The leaked .apply-lock-guard.sh is four lines. The leaked workflows are 4,000. The CLAUDE.md files in the repo are another 30 KB. None of this ships to users. All of it shipped Bun.

The footnote you actually want

Bun’s Rust binary is 3–8 MB smaller, the tests still pass, the benchmarks are neutral-to-faster, and the codebase is now in a language where the compiler can catch the bug class that has historically cost the team the most time. The proof of the approach is not the workflows — it’s that one of the most hostile software-engineering tasks imaginable (rewriting a million-line systems codebase in a language with a completely different memory model, without breaking compatibility) shipped, with all tests green, in a single PR.

If you’re considering whether agents can do real work: they can. The question is whether you’re willing to build the harness.

How to Run Playwright with Deno

2024-12-23T00:00:00+00:00

JavaScript and TypeScript Runtimes

Deno 2.1 LTS has emerged as an alternative to Node.js. We’re testing how to use the UI test automation tool Playwright with it. This article demonstrates the setup and compares the performance.

Deno is pronounced as ‘DEE-noh’. Since version Deno 2.1, the runtime environment for JavaScript, TypeScript, and WebAssembly (WASM) has been offered in a Long Term Support (LTS) variant, where critical bugs and security issues are fixed for 6 months while the APIs remain stable. These semi-annual releases are published under the MIT license.

Since Deno is delivered as a single binary file, installation is very simple, even on CI/CD pipelines.

To demonstrate compatibility with Node, we’ll use the UI tests for this website as an example.

These UI tests were implemented using Playwright.

Node 22

For projects without Playwright, the tool can be added using npm add playwright.

npx playwright install
npx playwright test kapp.technology

Deno 2.1

In Node projects, packages must be prefixed with npm:. It’s necessary to explicitly grant Deno access to network, disks, and packages. The convenient blanket approach is using --allow-all.

deno install
deno run --allow-all npm:playwright install
deno run --allow-all npm:playwright test kapp.technology
deno run --allow-all npm:playwright show-report

You can find more information about this in the GitHub issue NPM: Playwright does not work #16899.

The Test Script

The script verifies the basic correctness of:

the local website
the pull or merge request and
the published website

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {

  // Go to https://www.kapp.technology/
  await page.goto('https://www.kapp.technology/');

  // Click header >> text=Kapp Technology
  await page.locator('header >> text=Kapp Technology').click();
  await expect(page).toHaveURL('https://www.kapp.technology/');

  // Click nav >> text=Angebot
  await page.getByRole('navigation').getByRole('link', { name: 'Angebot' }).click();
  await expect(page).toHaveURL('https://www.kapp.technology/angebot-und-services/');

  // Click text=Angebot Blog Kontakt
  await page.getByRole('link', { name: 'Blog' }).click();
  await expect(page).toHaveURL('https://www.kapp.technology/blog/');

  // Click text=Der Neubau unserer Website
  await page.getByText('Der Neubau unserer Website').click();
  await expect(page).toHaveURL('https://www.kapp.technology/blog/relaunch-unserer-website/');

  // Click footer >> text=Angebot
  await page.getByRole('contentinfo').getByRole('link', { name: 'Angebot' }).click();
  await expect(page).toHaveURL('https://www.kapp.technology/angebot-und-services/');

  // Click text=Jetzt Kontakt aufnehmen
  await page.getByRole('link', { name: 'Jetzt Kontakt aufnehmen' }).click();
  await expect(page).toHaveURL('https://www.kapp.technology/contact/');

  // Click div[role="main"]:has-text("Hallo. Say Hello Senden")
  await page.locator('div[role="main"]:has-text("Hallo. Say Hello Senden")').click();
  await page.getByPlaceholder('Email Address').click();
  await page.getByPlaceholder('Email Address').fill('hello@example.com');
  await page.getByPlaceholder('What would you like to say?').fill('Hello from Test Automation.');
  await page.getByRole('button', { name: 'Senden' }).click();
  await expect(page.getByRole('button', {
    name: 'Nachricht abgeschickt!'
  })).toBeVisible();

});

Results

These spontaneous performance tests with just one test script can only give an impression: Both platforms are roughly equally fast.

JavaScript Platform	Target	Command	User	System	CPU	Total
Deno 2.1	local	deno run –allow-all npm:playwright test local	18.60s	3.37s	186%	11.787
Deno 2.1	public	deno run –allow-all npm:playwright test kapp.technology	33.92s	6.09s	201%	19.816s
Node 22	local	npx playwright test local	18.11s	2.91s	186%	11.269
Node 22	public	npx playwright test kapp.technology	33.67s	5.21s	205%	18.931s

Benefits

As developers, we write the UI tests locally and then run them in continuous integration pipelines or against the published website.

When each pull request can be easily deployed and tested like with Netlify, it brings a great gain in security. That’s when it becomes worthwhile to invest in Playwright test scripts.

Generate resource-friendly static websites

2022-08-04T00:00:00+00:00

Thanks to Rust, three new generators create static websites from Markdown very efficiently.

There are a number of legacy website generators written in Rust:

Zola, 2018
Cobalt, 2014
mdBook, 2015

If you want to learn how to write a simple generator in Rust, you will find an interesting blog post here.

A challenge for HTML generators written in Rust is that they need a template engine that translates content with layouts into HTML pages at runtime.

The off spring🔗

The current generation of website generators implemented in Rust has learned from the ergonomics and simplicity of Nextjs, Eleventy und Gatsby - all written in Javascript - it seems.

Pylon

Pylon is a static website generator that can be easily integrated into existing shell scripts. The following special features are implemented:

Link Checker
Copy data directories into the website structure
Global metadata can be made accessible to all pages
Asset are located in the same directory as the content
Freely definable shortcodes for use in markdown

Like Zola, Pylon uses Jinja templates implemented with Tera.

Oinky

Oinky uses Handlebars as a template language to translate markdown files into a static HTML website.

The special feature of Oinky is the DSL, which allows the creation of data structures that can then be processed with handlebars.

Blades, 2020

[Blades][13]is fast and reduced to the essential features. With [Ramhorns][14], Blades uses a fast, [Mustache][15] - based template engine with no if, else expressions or loops. Blades claims to be 10x faster than the speedy [Hugo][16], but doesn’t provide any benchmarks to prove it.

As with Zola, themes are also supported, but the amount of style templates is limited compared to Hugo.

Conclusion

If you want to process tens to hundreds of thousands of Markdown files, you can use the generators presented here to save a lot of time and maybe even money when updating static websites at high frequency.

#is_material

The New Kid On The Block: Microsoft Playwright

2022-05-09T00:00:00+00:00

Testing web applications is unpopular with many developers because it is tedious. Test automation is a prerequisite for efficient development of a high quality web application. Features can be delivered to customers faster, because changes can be delivered within minutes instead of days. Microsoft has launched Playwright, a new end-to-end testing tool that makes a lot of things easier.

Playwright is designed to support ‘every’ web browser on ‘any’ operating system. In fact, web applications can be tested with modern browsers such as Chrome, Firefox, Safari, Edge under the operating systems of Apple, Linux and Windows. In each case, the Chromium, WebKit and Firefox rendering engines, which are available as open source, are used. The tool also supports tests with mobile browser versions.

Polyglot🔗

Tests can be written in the most used programming languages:

Typescript, JavaScript
Python
.NET
Java

This breadth browser and platform support is made possible by the approach of relying on the Chrome Debugger Protokoll protocol.

Tests are processed in parallel. They wait until the browser has loaded the page. Developers have a test inspector and a test generator at hand as support.

Playwright can also very easily take images of the web page and use them as a basis for test cases. Videos of the test process can also be generated.

An example can illustrate how to write non-blocking tests with async and await, here in JavaScript:

	const { test, expect } = require('@playwright/test');
	
	test('basic test', async ({ page }) => {  
	
	  await page.goto('https://github.com/login');
	
	  await page.fill('input[name="login"]', 'USER NAME');
	
	  await page.fill('input[name="password"]', 'PASSWORD');
	
	  await page.click('text=Sign in');
	
	});

Developers write the tests locally in their development environment and then run them integrated in the Continuous Integration pipelines.

Conclusion🔗

By relying on locator functions, Playwright reduces the brittleness of tests we have experienced in the past with other testing tools.

test('display image', async ({ page }) => {
  const url = 'about/';
  await page.goto(baseURL + url);
  await expect(page).toHaveURL(baseURL + url);
  console.log(page.url)
  expect(await page.locator('img[alt="Andreas Kapp"]').screenshot()).toMatchSnapshot('about.png');

});

One of the major obstacles to test automation so far has been the cost and effort of maintaining the tests in the long run.

Today seems to be the day when we see Selenium and Cypress disappearing in the rearview mirror.

Refactoring Of Our Website

2019-11-24T00:00:00+00:00

After building our website with Jekyll for several years, we decided to migrate to Zola.

The reason: Jekyll uses Ruby. Updates on our Mac’s were way too time-consuming. Time to move on.

Our new website based on JamStack uses Rust as backend programming language. Our CI/CD pipeline benefits from very fast builds. Alternatively, you may also rely on a static website generator called ‘Hugo’, which is written in Go and is quite popular as well.

Click here to find more about Zola and the Jinja2-based template engine Tera. Zola is very handy, however the quite good documentation lags a bit behind the releases and is quite developer-centric.

What we are doing right now: PraxKit

2017-07-14T00:00:00+00:00

A the start of June we went live with PraxKit. We developed the product in cooperation with Andrea from Kapp Coaching & Therapie.

The App contains everything that’s needed from finding an appointment until making the billing.

An attractive solution for making the billing is included. Our goals: As simple and portable as possible. Therefore the PraxKit app runs on the smartphone. But also on the computer.

Currently we are insentivly working on the User Interface Design and the development of a simple procedure in the medical practice administration.

Our clients and audience are independent therapists.

Do you want to stay up-to-date with the development of Praxkit, then register yourself here News or contact us through the website here www.praxkit.ch.

See you soon!

Announcing Kapp Technology

2017-03-30T00:00:00+00:00

Our offerings: Research, consulting and software engineering. We use our knowledge and experience to create sustainable solutions.