A language that promises to run near C speed, parallelize itself across CPU and GPU, and still formally verify that the code the AI wrote does what you asked. That’s a lot of promises stacked together. I had never touched Bend 1, so this is new territory for me too: on launch day, I pointed my agents at two of my Rust projects and told them to port them to Bend 2. The result of that test is the most interesting part of this article.

Before we start, the disclaimer: this is a review written on the second day of the language’s life, based on a one-day experiment. I may be wrong about several of my assumptions, and that’s fine. The comments are down below; feel free to correct and add to it.

Who Victor Taelin is

First things first, the author deserves an introduction. Victor Taelin is a Brazilian functional programming researcher who spent more than a decade obsessed with one specific problem: optimal reduction of the lambda calculus, Lamping’s 1990 algorithm, and then Lafont’s interaction nets.

His own autobiography tells the story: he worked at the Ethereum Foundation, created the Formality proof language, retired early on the ETH he stacked from salary, went back to the problem on his own dime, created HVM (the Higher-Order Virtual Machine), and founded the Higher Order Company, which raised a $4 million seed to turn the research into a product.

And here’s a point that matters a lot to me: I love seeing a Brazilian doing serious programming language design work. We barely have real cutting-edge research in this country, let alone in computing fundamentals. For that alone, Taelin already has my respect and my congratulations for what he’s built so far.

So let it be on record: every criticism in this article is constructive, from someone rooting for Bend to go further. Nothing against him or the project.

Where Bend comes from

The first version of Bend showed up in May 2024, with Python-like syntax running on top of HVM2, and the promise of automatic parallelism: write sequential code, the runtime spreads it across every core and even the GPU, no threads, no locks, no mutexes.

The launch went viral. Almost a thousand points on Hacker News, over 20 thousand GitHub stars, a Fireship video. And then reality hit: the HN thread was merciless. 24-bit numbers, no FFI, a simple sum taking 42 minutes on a user’s machine, single-core C++ beating the demo’s RTX 4090. Taelin himself admitted back then that the codegen was bad, and admitted now, in the Bend 2 thread, that the 2024 hype didn’t convert into usage: “there is also my own failure into making the language actually be used, rather than just a viral moment”.

Bend 2 is the answer to that. And pay attention: it’s a different language. The README is explicit that Bend 1 programs don’t load. Interaction-graph evaluation (HVM) is out; native compilation to a single C file is in, with clang for CPU and Metal or CUDA for GPU. Numbers are now real Nat, U32, and F32, and the memory limit jumped from 2 GB to 8 TB, according to gihyo’s Japanese announcement. Interaction nets stay in the architecture, but in his words, “inets live in it architecturally, but they don’t exist at runtime”.

What Bend 2 promises

The new pitch now revolves around AI. The project page sells a “post-AGI” vision: humans will stop writing and reading code, so we need an ambiguity-free way to tell the AIs what we want. Bend’s solution is splitting the program into two files:

• LAWS.bend: the system’s invariants, written by the human.
• PROOF.bend: the proofs of those laws, written by the AI.

Bend’s type checker is a proof checker, in the lineage of Lean and Rocq, so bend PROOF.bend becomes a commit gate: if the proof doesn’t close, the code doesn’t ship. The site’s demo is a little game with the law “winning is impossible” and a direct invitation: “Skeptical? Try breaking the game”. The positioning is explicit: LAWS.bend is an AGENTS.md with mathematical backing.

And what does it look like? The syntax feels like Python with dependent types. A complete program with effects:

import Base

# Performs effects on the CPU.
def main() -> IO(Unit):
  do IO<Unit>:
    name : String <- IO.try(String, IO.get_env("USER"))
    IO.print("Hello, " ++ name)

Parallelism is divide-and-conquer: you split the work in two and the runtime spreads it over whatever cores it finds. And the ! operator dispatches the function to the GPU:

# Computes 2^d in parallel: a tree of d levels, one leaf per unit.
def pow2(+d: Nat) -> U32:
  match d:
    case 0n:
      1
    case 1n+p:
      a b = pow2(p) pow2(p)
      (a + b : U32)

# Runs pow2 on the GPU, via `!`.
def main() -> IO(Unit):
  result = pow2!(20n)
  IO.print(U32.show(result))

Notice the differences from mainstream languages: there’s no if (every branch is a match on True/False), natural numbers pattern-match on the successor pattern (1n+p), and the +d marks the parameter as affine, which is what lets the language live without a garbage collector.

And proofs are ordinary defs. The law declares what holds; the proof is induction with explicit rewrites:

# CLAIM: for every nat x, x + 0 equals x.
law add_zero:
  for x: Nat
  {Nat.add(x, 0n) == x : Nat}

# PROOF: induction on `x`, one rewrite (`%`) per step.
def add_zero(x):
  match x:
    case 0n:
      {==}
    case 1n+xp:
      %add_zero(xp) : {1n+Nat.add(xp, 0n) == 1n+_ : Nat}
      {==}

No tactics, no inference, everything annotated by hand. It’s verbose on purpose: that’s the price of the 0.1s checker.

The other promises, all with benchmarks on the page:

• Runs fast: Game of Life on an M4 Max in 7.8s on one core, against C’s 6.78s. On the GPU, 0.06s, or 124x.
• Checks fast: 3,200 generic instantiations checked in 0.38s, against Lean’s 19.2s and Rocq’s 6.04s. The idea is that the agent can verify after every edit.
• Parallelizes by itself: the ! operator sends the function to the GPU, no threads, no locks, no hand-written kernels.
• No garbage collector: affine types, each closure can be called at most once, so memory resolves statically.

Two honest details I liked seeing published: the site itself warns “Bend is still evolving. Expect bugs”, and Taelin stated that the compiler is 99% AI-written, with only the checking kernel audited by humans. Consistent with his thesis, at least.

And there’s already a business plan: the Bender, a paid, proprietary “proving agent”, a harness on top of Anthropic and OpenAI models today, with a dedicated model and its own symbolic prover on the roadmap.

Not everyone swallowed the benchmarks

The technical reception had strong caveats, and they matter. Nezk’s gist, “Why the benchmarks of Bend’s 2 typechecker are misleading (and possible problems with its type system)”, points out that Bend skips elaboration, unification, and implicit arguments, which is exactly where Lean and Rocq spend their time. Comparing times like that would be comparing an apple to a rocket.

Heavier: Liam Powell’s post, “Bend 2 and the Vibe-Coding Trap”, notes that the expression “formal verification” appears nowhere on Bend’s site or code, redoes the game demo in SPARK/Ada proving the same two properties automatically with GNATprove (“all checks proved (12 checks)”), without the 442 lines of manual proof, and concludes that Bend is “decades behind the state of the art”.

These are criticisms from people who know the subject, and they deserve an answer. That said, Bend 2’s main HN thread sits at over 600 points, so attention the project has.

What I tested

A tagline doesn’t compile a program, so I went and tested. I have a bend-tests repository where I pointed my agents at porting real projects of mine, written in Rust, to Bend 2 (v2.0.16, pinned via mise; to get a sense of the maturity, the language had nine releases in ten hours on GitHub the day after launch). The documentation for the whole experiment lives in docs/ in there, and that’s where the next sections come from.

The three candidates

I picked three of my projects with different profiles. Fair warning: none of the three is a worthy Bend example, and I know it. I just grabbed small, simple projects I had lying around, somewhat at random, to see where the language breaks when you rub ordinary day-to-day code against it.

ghpending is my CLI that lists open issues and PRs across my repositories via GraphQL. The port covers the main command, the filters, the sorting, and the config.toml, with output verified byte-for-byte identical to the Rust binary in the cases tested against the real GitHub API (on my loaded config, the only difference is the fork view the port left out).

tclock is my fork of clock-tui, a terminal clock with timer and stopwatch. The port covers clock, timer, and stopwatch, without the widget system (which alone is 2,075 lines of the Rust), verified by driving the binary through a pty.

ai-jail, my sandbox for AI agents (bubblewrap, Landlock, seccomp), never even became code: the paper evaluation killed it. A port would be a C program with a Bend main, which defeats the purpose. And it had the most interesting part to prove: the policy logic, like “path resolution never escapes the root”. But there’s no way to embed that in the Rust binary, so it stays for a next round.

The numbers

I measured Rust and Bend side by side on both ports:

Read that table carefully, because it lies. The runs are network-bound. The 43-repo gap is Rust doing more work (fork lookups, sequential viewer query). Bend’s tclock redraws whole frames, 26 KB/s against ratatui’s 2 KB/s of diffs. And the lower line count is partly because the port does less. No number here shows Bend faster than Rust on the same work.

The proofs in practice

Here’s the part Rust can’t imitate, so it’s worth the detail. The design that worked was proving an isolated guard, leaving the algorithm outside the proof. ghpending’s --limit allocator ended up in two stages: the first is the original algorithm in U32, unproven; the second is a Nat guard that takes the first stage’s proposal and cuts any excess. The laws say the budget is conserved and that no repo gets more items than it has.

This is the real guard, from the port’s alloc.bend:

# the lesser of b and w
def take(b: Nat, w: Nat) -> Nat:
  match b w:
    case 0n w0:
      0n
    case 1n+bp 0n:
      0n
    case 1n+bp 1n+wp:
      1n+take(bp, wp)

# what is left of b once w is taken from it
def rest(b: Nat, w: Nat) -> Nat:
  match b w:
    case 0n w0:
      0n
    case 1n+bp 0n:
      1n+bp
    case 1n+bp 1n+wp:
      rest(bp, wp)

The law holds even if the unproven stage proposes garbage. The guard doesn’t trust arithmetic it can’t see. That’s the pattern that makes proofs work in real code.

The mutation test is the honest measure of the thing. I injected an off-by-one into the guard that leaks budget: the three sample outputs came out identical, so a test suite of that size would have passed it. The proof gate rejected it, with the exact term that stopped matching. That’s Bend working as promised, down to the detail.

Now the price: 93 lines of laws and proofs to guarantee two simple facts about a guard of some 30 lines, starting from zero, because Base ships no Nat lemmas (the only arithmetic lemmas are U32.add_comm and Word.add_comm, which don’t help in a Nat proof; we had to prove addition associativity by hand, and Taelin acknowledged in the thread: “We need a mathlib!”).

And what stayed outside the proof: the algorithm’s exactness (it would need division lemmas, days of work), everything U32 (underneath it’s a 32-bit vector; proving arithmetic on it without a lemma library is impractical), and literally everything else in the program: JSON, sorting, rendering, IO. The provable surface of a program like ghpending is a few percent of the code.

The checker, on the other hand, is the best part of the tool: 0.1s per round, errors pointing at one exact line. It took some 30 check rounds on ghpending. For an agent iterating in a loop, it’s exactly the feedback format it needs.

The price of escaping to C

Everything Base lacks becomes a foreign effect: a Bend def whose body is a C function (for the native binary) and a JS twin (for the dev runner). The two ports needed eight hand-written effects:

• Http.post: because there’s no TLS, HTTP, or DNS (the official HTTP demo hard-codes an IP).
• Clock.unix and Clock.local: because IO.now is milliseconds since boot, with no wall clock and no timezone.
• Tty.width, Tty.raw, Tty.key, Tty.size: because there’s no stdin, no raw mode, no terminal query. None of that exists.
• Clock.millis: convenience.

And the official guide is clear about the trade: there’s no ABI promise. The names are runtime internals and any release can rename them, so “rebuild your effects with every update”. In a language with nine releases in ten hours, good luck with that. Details that complete the picture: there’s no flag to link an extra library (ghpending uses a $CC wrapper that injects -lcurl), custom handle types are WONTFIX, and including a C header mid-file worked by luck, because the runtime defines short names like lock and u32.

Here’s where the conceptual point lands: the moment you cross the FFI boundary, the proof stays behind. The checker guarantees what’s inside its model; the C code on the other side is an act of faith. Rust has exactly the same problem with unsafe, where the borrow checker’s guarantees hold up to the edge of the block and inside it the proof is on you. If you want strong end-to-end guarantees, the C boundary has to be minimal or nonexistent, and in Bend today it’s enormous for any real program.

Where Bend fits

Crossing the three projects with what the language offers, the winning shape is a small pure core, with a sharp spec that tests cover poorly, inside a thin shell of effects:

• allocators, schedulers, rate limiters, quota logic
• deterministic game or simulation rules, especially with rollback netcode (the only domain where Base already has what’s needed: UDP, windowing, audio)
• consensus state machines, ledgers, matching engines
• parsers and codecs with a round-trip law
• CRDT merge functions (commutative, associative, idempotent)
• access policy evaluators (like ai-jail’s)

And the design center the authors declare: the AI writes the code and the proofs, the human writes only the LAWS.bend, and the checker arbitrates. The shortest honest description I found: a proof-carrying language for AI-written kernels. Compared with Lean or Coq, which prove well and deliver applications poorly, Bend is far more executable.

One thing that surprised me in my own numbers: at first I’d assume the natural niche was academic math research. It’s the opposite. For mathematics it loses badly to Lean 4, Coq, and Isabelle: no tactics, almost no inference, nothing at mathlib’s scale, no reals, and a foundation (Type : Type, no positivity check) that would make a mathematician’s hair stand on end. What it does is software verification, closer to Dafny, F*, or Liquid Haskell than to a proof assistant.

Two limitations weigh even in that niche: Bend emits a whole program instead of a library, so the proven core can’t be linked into a Rust application today; and the cost of proving without a lemma library is high.

What would change the verdict

Recorded in use-cases.md, the list of what would make me reevaluate:

• library output with a C ABI, so a proven core can live inside a Rust or C program
• U64/I64 and F64
• a lemma library for Nat, lists, and ordering
• stdin, subprocesses, TLS, and JSON in Base, or a package hub that has them
• incremental or faster native builds (62s for 1,000 lines today)
• an effects ABI that survives a release

The unvarnished reality

Now my reading, and you already know I don’t sugarcoat.

It’s a newborn language. It launched two days ago. Outside the language’s own repo, a GitHub search today finds only a few dozen 48-hour spikes, almost all with zero stars, nothing that looks like a real project. The repo’s 21 thousand stars are almost all inherited from Bend 1; the repo was renamed. The site’s demos are all toys: a little game, Game of Life, pow2. They’re demonstrations of possibility, with no real usage yet.

The stdlib needs to grow by an order of magnitude. A language’s strength lives in its standard library and ecosystem. The only historical exception to that rule was JavaScript, and that’s a can of worms that doesn’t fit in this article.

The killer app is missing. Every language that made it had one. My tests point to the niche (proven pure cores, written by AI), but someone needs to turn that into an app the world wants to use. And here’s a concrete suggestion, free of charge: Taelin could pick popular open source software he thinks would be better in Bend and rewrite it. Taelin is the exact opposite of the stubborn maintainer who turns his nose up at AI: he designed the whole language around AI. So put that to work: grab a ripgrep, a jq, a sqlite, rewrite it with AI in Bend, and publish the side-by-side comparison. Performance, lines of code, and above all what the proofs guarantee that the original doesn’t. A real-world before/after like that is worth more than a thousand little game demos. And as a bonus, every one of those rewrites hands back the most valuable feedback there is: which stdlib holes actually hurt in a real project. Nothing reprioritizes what to implement in the next version better than real code hitting what’s missing.

Don’t expect webapps, mobile, or anything day-to-day anytime soon. Maybe that’s not even the goal, and that’s fine too. But the “C speed” promise cuts the other way: if the differentiator is performance, it’s easier to go straight to C, especially now, with an LLM writing the code for you.

And here’s my concrete situation. I use Rust a ton. I hate the syntax, and I find the ergonomics miserable. But since the LLM writes the code and I don’t have to deal with it by hand, I tolerate it, and in exchange I get performance, good-enough guarantees, and a gigantic ecosystem of crates and frameworks. Ecosystem. That’s what decides it.

I don’t pick a language by the elegance of the paper. I pick it by the size of the ecosystem I don’t have to write by hand.

The proof-and-GPU focus, and the doubt that remains

One thing nagged me the whole time: Taelin clearly concentrates everything on two pillars, proofs and GPU, and I wasn’t sure what that meant for the language’s scope. I went and read what he himself said in the pre-launch thread and on HN, and the story is more interesting than I assumed.

The GPU pillar is research inheritance. Ten years of interaction nets and optimal reduction, from HVM to here. But there’s a nuance that surprised me: Bend 2 consciously betrays his academic idealism. In his own words: “Bend2 is designed to be practical, not idealistic”, closer to C than to Haskell, because he couldn’t make interaction nets beat the lower-order variants on common hardware. The GPU stayed as the practical application of the obsession, without becoming a fetish.

The proof pillar is older than the LLM era: it goes back to the Ethereum Foundation days, immutable contracts holding millions with a bug, which produced Formality. The LLM era just gave the old obsession a market outfit: “the same capabilities that proved Navier-Stokes will now be writing real proofs that your own apps are correct”.

And here comes my hypothesis that didn’t survive the research. I was ready to write that the minimal stdlib was maybe on purpose, that the idea was never general-purpose programming, and that my criticism of the library desert was aiming at the wrong target. Wrong me. His words are general ambition, period: “the potential to become the most sensible choice for any vibe-coded project”, “Bend is made for the general public”, and the team “working hard to […] make this language competitive with the mature alternatives in the market”. The only deliberate leanness is the checker’s, no inference, verbose on purpose. The small Base is day two of life, so much so that he himself asks for a mathlib.

That makes my stdlib criticism bite even harder: if the declared goal is to be the choice for any vibe-coded project, the comparison with mature ecosystems is the game he chose to play.

And there’s the business angle, which he admits with rare frankness: “we ship without a product”. The language is the free substrate; the sellable thing is the Bender and the proving infrastructure behind it. Worth keeping an eye on that space.

The doubt that remains, and this one I register with no answer: the generalist ambition is his north star, but the reality I measured pushes Bend toward the niche of AI-written verified cores. Which of the two wins, only time will tell.

The final word

If I could give Taelin one piece of advice, it would be this: the hard part, the research, he’s already done. Now comes the less glamorous part, the one that decides whether a language lives or dies: marketing and ecosystem building. Adoption, teaching material, killer app, stdlib, mathlib. Going way beyond toys and demos.

The example that comes to mind is Zig. Years on the road and still fighting for adoption, even with immediate practical use: zig cc alone is a trivial drop-in for compiling C, without using any of the language. Real apps use it; Mitchell Hashimoto’s Ghostty is the famous case. But Andrew Kelley, the author, is a notoriously difficult figure, from the crowd that turns its nose up at AI, and he clearly doesn’t understand ecosystem building, and that holds Zig back. Technical perfectionism doesn’t mix with marketing and adoption.

Bend 2 has real potential. Instant checker, proofs catching bugs that tests don’t catch, parallelism without ceremony. But potential alone means nothing if adoption doesn’t come. I’m rooting for it to come, and rooting double because a Brazilian is leading.

And one final provocation, this time for you who read this far. Thin stdlib, zero frameworks, zero third-party libraries, no killer app: all of that stops being a problem when you look from another angle and becomes an opportunity map. Everything missing in Bend is something someone will have to write, and whoever gets there first etches their name into the project’s history. If you always wanted to contribute to impactful open source but never found room in the mature projects, where everything already exists, here’s an empty lot waiting.

Those are my two cents. Don’t take it too seriously.

What I liked most about Jarred’s post was the level of detail. He did not sell the idiotic fantasy of writing a prompt like “rewrite Bun in Rust” and waiting for a miracle. Quite the opposite. What he described was procedure: PORTING.md, lifetime analysis, LIFETIMES.tsv, a trial run with three files, dynamic workflows, adversarial reviewers, process correction when the agents started doing stupid things with git stash, then compiler errors becoming a work queue, then smoke tests, then the whole suite, then multi-platform CI. No irresponsible vibe coding. Engineering using AI as a multiplier.

That’s why I was disappointed by Andrew Kelley’s response, “My Thoughts on the Bun Rust Rewrite”. Andrew is Zig’s creator. I wanted to read the best possible technical argument defending Zig. I wanted to see him explain where Bun confused a language problem with an architecture problem. I wanted to see which Zig APIs could have helped, which invariants should have been hardened, where comptime, allocators, arenas, errdefer, DebugAllocator, and Zig’s new I/O design could change the analysis.

Instead, a large part of the text becomes an attempt at character assassination. Comments about personality, management, VC, startup culture, backstage gossip. There may even be real resentment there. I don’t care. It does not help technically.

So I decided to do the exercise I expected to have read: put Claude Fable 5 and GPT 5.6 Sol as technical arbiters and ask them for the answer Andrew should have written. Not the polite answer. Not the fan-club answer. The technical answer.

Before handing over the microphone, one off-topic note. If you, like me, stared at those beautiful GitHub animations in Bun’s post and thought “I want that in my projects”, I went there and built it. github-visualize is a self-hosted dashboard that tracks your repositories and replays commit evolution, the hourly heatmap, and the CI race until everything turns green. It’s all open on GitHub.

But now let’s separate support from proof. One thing is to say “I would have done something similar”. Another is to say “it was technically impossible to continue in Zig”. To answer that, we need to look at causes: which bugs were really language bugs, which were architecture problems, which were ecosystem costs, and which could have been reduced with different discipline inside Zig itself.

That’s where the analysis starts.

First, minimum vocabulary. Use-after-free is using memory after freeing it. Double-free is freeing the same memory twice. Leak is forgetting to free. Ownership is who is responsible for destroying a resource. Lifetime is how long a reference remains valid. FFI is the boundary where Rust or Zig call C/C++ and lose part of the language guarantees. GC root is a way to tell the garbage collector: “do not collect this object yet”. Pinning is holding a buffer in place so it cannot be moved, detached, or invalidated while someone still has a pointer to it. Reentrancy is when a call enters the runtime again before the previous call has finished.

What Rust actually buys

The strongest thesis in Bun’s post is simple: a large percentage of the listed bugs were use-after-free, double-free, or forgotten resources in error paths. In safe Rust, a good portion of that becomes compiler error or automatic cleanup through Drop, as long as the resource is modeled as an owning value. Rust does not prove the general absence of leaks: Rc cycles, mem::forget, Box::leak, and abort still exist. But it makes accidental leaking in error paths much harder.

That is correct. And it is a strong argument.

Rust’s strong point here is not magic. It is that Rust forces certain ownership and lifetime relationships to appear in the type, instead of being scattered around as convention. When a value has an owner, when it is moved, when it leaves scope, when a destructor runs, that stops being just an agreement between programmers. The compiler participates.

In Bun’s current code, you can see the pattern in miniature. A MySQL byte wrapper stores a pinned JavaScriptCore value, and Drop undoes the pin when the object dies:

impl Drop for Bytes {
    fn drop(&mut self) {
        if !self.pinned.is_empty() {
            // `pinned` is rooted by the caller's MarkedArgumentBuffer for the
            // lifetime of this Value (see struct doc); the FFI itself is `safe fn`.
            JSC__JSValue__unpinArrayBuffer(self.pinned);
        }
        // self.slice dropped automatically
    }
}

Source: src/sql_jsc/mysql/MySQLValue.rs. The important detail is not the FFI call itself. It is that cleanup follows the value’s owner.

This is the round Rust wins cleanly. In a small project, discipline is enough. In half a million lines, with reentrant callbacks, threadpool, libuv, sockets, TLS, JavaScriptCore, parser, bundler, package manager, and Node API, discipline becomes recurring cost.

Rust probably reduced the invalid state space the team needed to keep in their heads. Real win.

But a real win does not mean total victory.

Zig was not defenseless

The weakest argument you can make against Zig is pretending it is C with new syntax. It is not. Zig has explicit mechanisms to address exactly part of these problems.

The most obvious one is errdefer, the idiomatic mechanism for cleanup on error paths:

fn readThing(alloc: std.mem.Allocator, fail: bool) ![]u8 {
    const buf = try alloc.alloc(u8, 16);
    errdefer alloc.free(buf);

    if (fail) return error.Boom;
    return buf;
}

test "leak em caminho de erro" {
    const alloc = std.testing.allocator;
    try std.testing.expectError(error.Boom, readThing(alloc, true));
}

std.testing.allocator reports leaks in tests. DebugAllocator helps find double-free, leaks, and many invalid memory uses, including making bugs noisier by not immediately reusing addresses. This is not the same thing as a static proof of the absence of use-after-free. It is not a borrow checker. It does not cover allocation done inside C++, JavaScriptCore, BoringSSL, or any other external allocator. It only catches what goes through it and only on the paths exercised by tests.

The allocator’s own comment is precise about what it provides:

//! * Captures stack traces on allocation, free, and optionally resize.
//! * Double free detection, which prints all three traces (first alloc, first
//!   free, second free).
//! * Leak detection, with stack traces.
//! * Never reuses memory addresses, making it easier for Zig to detect branch
//!   on undefined values in case of dangling pointers.

Source: debug_allocator.zig. It is a good testing and debugging tool. It is not a theorem.

Even so, it is wrong to say Zig had no tools. It did.

The difference is feedback timing. In Rust, a lot appears at compile time. In Zig, a lot appears in tests, fuzzing, instrumented allocators, ASAN, review, and architectural style. In critical code, that matters. Early feedback is better.

But it also matters to say the whole sentence: if the problem was lack of clear invariants in the Zig code, the answer could have been a rewrite in Rust. It could also have been an aggressive restructuring of the Zig.

We do not know which would have been cheaper. We only know which one Bun chose.

Drop is not just sugar, but it is not a miracle either

Bun’s post is right to contrast defer with Drop.

In Zig, you write:

var resource = try Resource.init(allocator);
defer resource.deinit();

This is explicit. It is in your face. There is no hidden control flow. That is Zig’s philosophy: if something happens, you should be able to point to where it happens.

In Rust, if the type implements Drop, cleanup follows the owner:

impl Drop for Resource {
    fn drop(&mut self) {
        self.deinit();
    }
}

This is not just syntactic sugar. Rust’s destruction rules connect Drop to ownership, move semantics, field destruction order, and panic unwind. Ordinary safe code cannot use a value after it has been moved, nor double-drop the object as if it still owned it. It is a language guarantee.

But the guarantee ends where semantics the compiler does not understand begin.

If drop calls an FFI function to unprotect a JavaScriptCore value, Rust guarantees the destructor will run on normal scope and drop paths, not on abort, mem::forget, intentional leaks, or Rc cycles. It does not prove that the JSC pointer is still valid. It does not prove the GC has no special rule. It does not prove an asynchronous C callback will not call back after you destroyed the wrapper.

The comment in the same Bun wrapper shows the size of the contract that still remains outside the compiler:

/// JS could `transfer()`/detach an earlier ArrayBuffer, or drop the last
/// JS reference to it and force GC, while we still hold a borrowed slice
/// into it. Pinning the backing `ArrayBuffer` makes it non-detachable for
/// the duration, and the caller's stack-scoped `MarkedArgumentBuffer`
/// roots the wrapper so GC can't sweep the cell. `Drop` unpins.
pub struct Bytes {
    pub slice: ZigStringSlice,

Source: MySQLValue.rs. Notice the size of the contract. It did not disappear because this is Rust. It became documented and encapsulated.

That is the real boundary: Rust improves the Rust side of the contract. It does not perform magic inside the JavaScriptCore heap.

The FFI boundary is still hell

Bun is not a simple CLI. Bun is a JavaScript runtime. It talks to JavaScriptCore, uWebSockets, usockets, BoringSSL, SQLite, compression libraries, system APIs, asynchronous handles, buffers that JavaScript can detach in the middle of a coercion, reentrant callbacks, and a conservative GC.

That is where the debate gets interesting.

Inside an unsafe block, Rust requires discipline. The Rustonomicon on FFI itself treats foreign calls and raw pointers as programmer obligations. If the binding is lying, if the real ownership does not match the type, if the foreign callback outlives the Rust object, the compiler does not save you.

Bun’s binding documents the preconditions in the declaration itself:

unsafe extern "C" {
    /// By-value `JSValue`; C++ side null-checks and reads its own heap state.
    /// No caller-side preconditions → `safe fn`.
    safe fn JSC__JSValue__unpinArrayBuffer(v: JSValue);
    /// 0 = detached/null, 1 = FastTypedArray (GC-movable — caller should dupe;
    /// no unpin needed), 2 = pinned ArrayBuffer (caller must unpin).
}

Source: MySQLValue.rs. The language lets you declare a foreign call safe. The obligation to prove that safety remains ours.

But there is an important difference: Rust lets you encapsulate that unsafe behind safe APIs. You can create handle types, NonNull, PhantomData, Pin, lifetimes marking the relationship between wrapper and runtime, wrappers that do not implement Send or Sync, RAII for GC roots, and a smaller surface for audit. The goal is not to eliminate danger. It is to shrink the place where danger lives.

The most didactic example in Bun’s post is the uv_close bug. The first version compiled, but handed a Box to libuv to close asynchronously and let the Box fall at the end of the scope. Use-after-free followed by double-free. The fixed version in the current code makes the transfer explicit:

spawn::WindowsStdioResult::Buffer(pipe) => {
    // `uv_close` is async — libuv keeps the raw handle pointer until the
    // next loop tick. Leak the Box so it outlives this scope; dropping it
    // here would be a use-after-free + double-free when the callback fires.
    Box::leak(pipe).close(Subprocess::on_pipe_close)
}

Source: js_bun_spawn_bindings.rs. It compiled in Rust and was still wrong at the C/async boundary. The review process caught it.

Here leak does not mean “leak forever”. It means removing the Box from Rust’s lexical control and transferring ownership to libuv’s asynchronous protocol, whose callback later reconstructs and frees the allocation.

Zig also lets you write good wrappers. The difference is that it does not have the safe/unsafe boundary as part of the language. In Zig, everything is explicit and reviewable. In Rust, a larger part of the contract can become type.

For a large team, that matters. It matters even more when part of the code is being generated by agents.

Arenas: yes, Bun already used them

Here the pro-Zig argument needs to be honest. Arenas are idiomatic and excellent for certain problems: parser, AST, request lifecycle, data that dies together.

But Bun’s post does not ignore arenas. It explicitly says the existing approach was already a mix of lifetimes by arena, reference counting, and “pay really close attention”. It even cites parser state and AST nodes as good cases for an arena.

The excerpt from the post is this:

Our current approach is a mix of:

- arena lifetimes, where the scope of when it's accessible is clear
  (parser state doesn't escape the calling function and so AST nodes
  are a good choice there)
- reference-counting
- pay really close attention

Source: Bun’s official post. The good counter-argument is not “use arena”. They already did. The good counter-argument is asking whether the remaining boundaries could have been hardened in Zig.

So the correct response is not “you forgot arenas”. They did not forget.

The correct response is: arena solves the case where lifetime is clear. It does not, by itself, solve a socket handle that closes asynchronously, a callback that runs later, an SSL session that needs a specific free, a GC root, a pointer that may be invalidated by reentrancy, or an object that crosses several API layers with implicit ownership.

Arena is a good tool. It is not a religion.

If Bun had hardened the boundaries more in Zig, maybe part of the rewrite’s benefit could have come from that: more restricted APIs, fewer raw pointers crossing subsystems, handles with explicit ownership, allocators instrumented by default in tests, fuzzing aimed at reentrancy, wrappers that force deinit, less “pay attention”.

But that would also be a rewrite. Just inside Zig.

The borrow checker helps, but not where the internet thinks

A lot of people talk about the borrow checker as if it were a universal bug detector. It is not. The borrow checker is the part of the Rust compiler that prevents certain invalid borrows: two mutable owners at the same time, a live reference after the owner dies, use after move. That is a lot. It is not everything.

It does not understand the JavaScriptCore heap. It does not understand every GC rule. It does not automatically understand that a C callback can trigger JS, that JS can detach an ArrayBuffer, that it can reenter the runtime, that it can invalidate a pointer captured earlier. These invariants need to be modeled.

But when they are modeled, Rust charges you.

A small example in Bun: a uSockets wrapper that turns a C pointer into a Rust borrow tied to &mut self:

impl PacketBuffer {
    pub fn get_peer(&mut self, index: c_int) -> &mut sockaddr_storage {
        // SAFETY: uSockets guarantees a non-null, properly-aligned peer pointer for
        // indices < packet count. The returned storage lives inside the C-owned packet
        // buffer, which is exclusively loaned to the data callback for its duration; no
        // other Rust or C path holds a reference to it. The reborrow of `&mut self`
        // ties the returned lifetime to this handle, so the borrow checker prevents
        // obtaining a second overlapping `&mut` via `get_peer`/`get_payload`.
        unsafe { &mut *us_udp_packet_buffer_peer(self, index) }
    }
}

Source: src/uws_sys/udp.rs. The unsafe still exists. But after the wrapper creates the reference, the borrow checker can prevent certain abuses on the Rust side.

And Bun is not only JavaScript heap. It is parser, bundler, module resolver, package manager, file watcher, HTTP protocol, buffers, caches, tables, queues, process state, glue code. In these parts, local ownership matters a lot. Vec, String, slices, maps, wrappers, enums, finite states: all of that becomes easier to refactor with the compiler slapping your hand.

The honest argument is not “the borrow checker solves Bun”. It is: the borrow checker reduces many classes of error on Bun’s Rust side, and that frees human attention for the part that remains hard.

That is strong enough. No need to exaggerate.

comptime: here Zig has a real advantage

The best technical counterexample in Bun’s own post is Output.pretty.

In Zig, the format string could be a comptime parameter. Bun’s own post puts the difference like this:

// Zig:
pub inline fn pretty(comptime fmt: string, args: anytype) void;
Output.pretty("<r>{f}<r>", .{hyperlink});

// Primeira API Rust:
pub fn pretty(payload: impl PrettyFmtInput);
Output::pretty(format_args!("<r>{}<r>", hyperlink));

This allowed processing color and formatting markers in the literal known at compile time, before mixing runtime arguments. When porting to Rust, the first version became a function. Result: the tag parser touched bytes that came from the arguments. Issue #30693 shows the regression in port/canary involving an OSC 8 hyperlink escape and <r>, not a failure released in stable.

The bug was exactly the contamination between template and runtime argument:

TerminalHyperlink::Display emits an OSC 8 hyperlink:

\x1b]8;;URL\x1b\ai\x1b]8;;\x1b\

The closing string terminator ST is the final two bytes `\x1b\`.

This is then wrapped via `Output::pretty(format_args!("<r>{}<r>", hyperlink))`.
The rendered string tail is `...\x1b\<r>`.

Source: issue #30693.

Then they fixed it using a macro.

The current code makes the difference explicit:

/// Write to stdout with `<tag>` color expansion.
/// Function form: performs the `<tag>` → ANSI rewrite at runtime on the rendered
/// payload (using stdout's colour state). Prefer the `pretty!` macro for literal
/// templates so the rewrite happens at compile time.
#[inline(always)]
pub fn pretty(payload: impl PrettyFmtInput) {
    let buf = payload.into_pretty_buf(enable_ansi_colors_stdout());
    write_bytes(Destination::Stdout, &buf);
}

And right below:

/// Compile-time `<tag>` → ANSI escape rewriter.
///
/// This must be a proc-macro because it consumes a string literal and emits
/// a new string literal usable as a `format_args!` template.
///
/// `pretty_fmt!("<red>{s}<r>", true)`  → `"\x1b[31m{}\x1b[0m"`
/// `pretty_fmt!("<red>{s}<r>", false)` → `"{}"`
pub use bun_core_macros::pretty_fmt;

Source: src/bun_core/output.rs.

This demonstrates a legitimate strength of Zig: comptime is the language itself running at compile time. You do not switch to a parallel system. In Rust, macros are powerful and mature, but they are another mechanism. For some kinds of API, Zig is simply more direct.

But let’s not turn a porting bug into universal proof against Rust. The problem there was not “Rust is fragile”. It was the wrong translation of a comptime API into a runtime function. Bun’s own post recognizes that and fixes it with a macro.

The correct reading is simpler: Zig had a structural guarantee there. The first Rust version lost that guarantee. That cost a regression in port/canary.

Point for Zig.

Binary size and performance: careful with cheap causality

Bun’s post shows good numbers: smaller binary, some faster benchmarks, better startup in certain scenarios.

The numbers from the post:

Bun v1.4.0 (canary) — Windows — 76 MB
Bun v1.3.14          — Windows — 94 MB
Bun v1.4.0 (canary) — Linux   — 70 MB
Bun v1.3.14          — Linux   — 88 MB

Bun.serve  — 169.6k → 177.7k — +4.8%
node:http  — 103.8k → 108.5k — +4.5%
fastify    —  91.5k →  95.9k — +4.8%

Source: Bun’s official post.

I believe the numbers. I do not believe in simple attribution.

A rewrite changes many things at the same time. It changes code layout, removes debt, changes toolchain, touches LTO, changes how generics/comptime are instantiated, changes linker, changes dead code, changes ICU, changes internal organization. When all of that happens together, you cannot look at the graph and say: “it was Rust”.

You also cannot say: “it was only the rewrite”.

The post itself talks about a combination: Rust, ICU changes, Identical Code Folding, LTO, codegen, accumulated cleanup. LTO is optimization at the final link stage, when the compiler sees more of the program before generating the binary. Identical Code Folding is the linker merging identical functions into one. Andrew is right to point out that Zig also supports LTO and that some of these gains could have been pursued before. But that does not prove the result would be the same. It only proves causality is mixed.

Bun’s Cargo.toml shows there is explicit build engineering in this story:

# Cargo's defaults (lto=false, codegen-units=16) leave us at ~105 crates × 16
# CGUs ≈ 1680 separately-optimized units with NO cross-crate inlining beyond
# `#[inline]`-annotated leaf fns. `lto = "fat"` + `codegen-units = 1` collapses
# the whole Rust crate graph into one LLVM module, matching Zig's shape.
[profile.release]
lto = "fat"
codegen-units = 1
debug = "line-tables-only"
strip = "none"
panic = "abort"

Source: Cargo.toml.

And there is LTO configuration crossing Rust and C++:

/**
 * Cross-language LTO: rustc emits LLVM bitcode (`-Clinker-plugin-lto`) into
 * `libbun_rust.a` so the final lld `-flto=thin` link sees through Rust↔C++
 * call edges. When false but `lto` is true, both halves still LTO
 * independently (C++ via `-flto=thin`, Rust via `[profile.release] lto =
 * "fat"`); only the cross-language inlining is lost.
 */
crossLangLto: boolean;

Source: scripts/build/config.ts. It is not “Rust won”. It is language, toolchain, linker, configuration, and code working together.

Same thing for stack usage and parser depth. The post attributes improvement to Rust emitting better llvm.lifetime.start/end and allowing stack slot reuse. Codegen detail? Yes. But a codegen detail delivered by today’s toolchain counts. Zig itself still has an open issue about stack allocations that do not disappear at the end of scope. For the user, it matters little whether the advantage comes from the pure language, the compiler, or backend maturity. What matters is that it works today.

The mechanism described by Bun is this:

Rust's LLVM IR codegen emits LLVM's llvm.lifetime.start and
llvm.lifetime.end intrinsics for stack variables when they are no longer
in use, which lets LLVM reuse stack space slots.

And the Zig ticket says, bluntly, that this case is still not solved:

Block stack allocations do not disappear at end of block scope #23475

There is also the architectural solution: iterative parser with an explicit stack on the heap. Works in Zig and Rust. But it is more work.

Honest reading: the numbers favor Bun’s Rust version in that experiment. They do not prove general language superiority.

Miri, crates, and the real world

There are Rust advantages that have no direct equivalent in Zig today.

Crates is the obvious one. The Rust ecosystem is large, mature, and practical. For a project the size of Bun, a good off-the-shelf library is real engineering value. Zig is still maturing on this point.

Miri is also a real advantage. It detects classes of undefined behavior in executed Rust code: out-of-bounds, use-after-free, uninitialized data, alignment problems, data races in certain cases. The project itself documents the limits: it is not a formal proof, it evaluates the executions you provide, and it has restricted support for FFI and platform APIs. It does not replace testing. But to validate isolated unsafe abstractions, it is a tool Zig does not have in the same way.

Bun does not merely cite Miri in the abstract. It is in the toolchain:

[toolchain]
channel = "nightly-2026-05-06"
components = ["rust-src", "rustfmt", "clippy", "miri", "llvm-tools"]

Source: rust-toolchain.toml.

And there is an internal test explaining exactly the use:

// Run under Miri (`bun run rust:miri -p bun_ptr`): every path here walks raw
// pointers through `Box::into_raw` / `heap::take`, so Tree Borrows is what
// proves the ref/deref/destructor handoff does not alias or use-after-free.

Source: src/ptr/ref_count.rs. It does not prove the whole program. It exercises a dangerous abstraction under a model made to detect undefined behavior on those executed paths.

There is also hiring, tooling, documentation, IDE, review culture, CI, examples, people in the market. This is not a political detail. It is engineering. A language exists inside an ecosystem.

If Bun were a smaller project, with a smaller team, less pressure, and less Node-compatible surface area, maybe I would weigh this differently. But Bun became a runtime used by millions of monthly downloads. The margin for “let’s maintain perfect discipline” shrinks.

Async: Zig may have a better answer, but it is not Bun’s present yet

Zig removed the old async/await and is redesigning I/O around std.Io, passed by the caller in a way similar to Allocator. The idea is good: avoid classic function coloring, make the function less coupled to blocking, threaded, or event-driven execution, and treat I/O as an explicit capability.

The proposed format is like this:

const std = @import("std");
const Io = std.Io;

fn saveData(io: Io, data: []const u8) !void {
    const file = try Io.Dir.cwd().createFile(io, "save.txt", .{});
    defer file.close(io);

    try file.writeAll(io, data);

    const out: Io.File = .stdout();
    try out.writeAll(io, "save complete");
}

Source: Kristoff on Zig’s new async I/O. io is a capability passed explicitly, like Allocator.

I like this direction a lot.

But it is still in transition. The tracking issue remains open: there is a prototype, roadmap, discussion, parts landing gradually. It is not a stable foundation Bun could bet on today without cost.

So the argument here cannot be “Zig already solved it”. The correct formulation is: Zig is moving toward an async/I/O design that may be cleaner in some aspects than the traditional colored model. But Bun needed to make a decision with what exists now, not with what promises to exist later.

That is always cruel to young languages. But it is real.

The rewrite process matters more than the language

The best part of Jarred’s post is not Rust. It is method.

The mental loop of the post is literally this:

// Pseudocode, not real code:
let task;
while ((task = todoList.pop())) {
  const result = task();
  const feedback = await Promise.all([review(result), review(result)]);
  await apply(feedback, result);
}

Then compiler errors became a queue:

~16,000 compiler errors left

error: deref *mut EventLoop before field access
error[E0034]: multiple applicable items in scope
error: event_loop/EventLoopTimer.rs: port Timespec::ns from bun.zig

And the per-crate cycle was explicit:

- For each crate, run cargo check, group the output by file and save the errors to a file
- Fix all the compiler errors within that crate
- 2 adversarial reviewers for the crate's changes
- 1 fixer applies the fixes

Source: Bun’s official post.

He did not tell Claude to rewrite an entire runtime and go to sleep. He built loops. Separated implementer from reviewer. Used different context for adversarial review. Did a trial run. Fixed the workflow when agents started tripping over each other. Banned dangerous commands. Split worktrees. Turned compiler errors into a queue. Ran the same TypeScript suite because the suite did not depend on the runtime language. Used multi-platform CI as judge.

That is the part everyone should study.

The model did not replace engineering. The model executed work inside an engineering process. When the process was bad, the result was bad. When the process improved, the result improved.

It is the detail the tribal discussion ignores. The story is not “Claude rewrote Bun”. The story is “an engineer turned a giant migration into several verifiable loops and used Claude to accelerate each loop”.

Much more interesting.

So did Zig fail?

No.

Zig did not fail because Bun chose Rust. Rust also did not become the universal answer because Bun chose Rust.

What the public evidence shows is more boring: that code, at that moment, was too expensive to evolve with the level of confidence the team wanted. Rust bought predictability. Bought compiler feedback. Bought ecosystem. Bought an explicit safe/unsafe boundary. Bought tooling. Bought an environment where AI agents can bang against compiler errors and move forward mechanically.

That is enough to justify the decision.

But it is not enough to prove Zig was technically unviable for Bun. Many cited problems also look like boundary problems: implicit ownership, overly permissive APIs, allocation without a visible contract, resources crossing layers without a type carrying the owner, tests that maybe did not capture difficult invariants, and the human cost of reviewing all of that.

Those things could have been attacked in Zig. Maybe an aggressive Zig restructuring would have solved a lot. Maybe not. Maybe it would cost more than the port. Maybe it would cost less, but deliver less confidence. We do not have the counterfactual.

And that is exactly why the conclusion needs to be calibrated.

I support Jarred’s decision as a product and engineering decision. His post is one of the most useful reports I have ever seen about a large AI-assisted rewrite. But liking the decision does not force me to pretend it was the only possible technical conclusion.

And there is one important disclaimer. Anthropic acquired Bun in December 2025, and Jarred opens the post by saying that he and the Bun team now work there. Anthropic sells Claude Code. Jarred had every institutional incentive to use as much Claude as possible and turn this rewrite into a public demonstration of his new employer’s product. That does not prove bad faith, nor does it invalidate a technical result. But it adds bias to the decision and to the way the case is presented. Ignoring that conflict of incentives would be as naive as ignoring Andrew’s resentment over Bun leaving Zig.

The best reading is less dramatic: Bun chose to pay a large cost now to reduce recurring maintenance costs later. Rust was a defensible choice, maybe a great one for that team at that moment. Zig remained an excellent language, but would have required another kind of reengineering: more explicit invariants, less informal ownership, more tools enabled by default, harder boundaries.

Andrew could have written that. He could have defended Zig on technical ground. He could have said: “Rust bought some real guarantees, but a large part of the problem was architecture and process; here is how Zig could have attacked the same causes.” That would have been a useful post.

We do not need to declare a winner. Language does not replace architecture. It only changes which errors become cheap to detect and which still depend on human discipline.

Bun chose to trade part of that discipline for compiler. I think it is a good bet.

I do not think it buries Zig.

I like this phase. The project stops being “what I imagined in my setup” and becomes “what breaks on somebody else’s machine.” Then Windows shows up. macOS. Arch. AUR. Weird paths. Tokens saved somewhere else. Different shell. Different terminal. Annoying? Yes. Necessary? Also yes.

But today’s main dish is not ai-jail or ai-memory. It’s TUI. More specifically, my recent habit of writing small terminal tools in Rust with Ratatui, while wanting them to look like Bubble Tea.

The app I won’t open

Over the last few weeks I also worked on a private project I do not plan to open source. It’s a TUI to track my US bank account, investments, assets, positions, covered calls, open calls, all that boring grown-up stuff. I won’t publish the code because this tool was born glued to my financial workflow, my spreadsheets, my statements, and my internal hacks. Opening it would turn a tool for myself into free support for other people’s bank bugs. No thanks.

But I can show the general look. I censored what needed censoring:

Obvious note, but I’ll make it explicit: every value, ticker, position, and date shown in the screenshot is bogus demonstration data. It is not real account data, not my real portfolio, and not investment advice.

Every time I build a small TUI, the same question comes back: what stack should I use?

If I were writing everything by hand, I would probably pick Python or Go. They are more comfortable for this kind of small utility. Python because it is direct, full of libraries, great for scripts that talk to APIs and parse JSON. Go because it produces simple binaries, cross-platform support is sane, and the CLI ergonomics are good.

But today I rarely write all that code by hand. I orchestrate Claude, Codex, OpenCode, ask for reviews, ask for refactors, ask for tests. In that setup, Rust’s lack of ergonomics hurts less, because the LLM is the one fighting the borrow checker, trait bounds, and annoying lifetimes. I stay closer to reviewer and end user. And then Rust starts looking very attractive.

Good tooling. cargo is great. Tests are easy to run. Cross compile is manageable. The final binary is clean. Dumb memory bugs mostly disappear. I am not saying Rust is magically better than Go or Python for every TUI. It isn’t. But with an LLM writing most of it, the cost that would usually make me avoid Rust drops a lot. And current models are surprisingly competent with Rust, as long as you make them run tests, fix warnings, and you don’t accept the first version as if Moses brought it down from the mountain.

Ratatui is good, but I wanted the Charm look

Ratatui is a Rust library for building full terminal interfaces: dashboards, interactive apps, tables, lists, gauges, layouts, the whole thing we used to call “modern ncurses.” It grew out of tui-rs, and today it is probably the obvious path if you want to build a serious TUI in Rust.

Ratatui works well. My problem is taste: by default, I don’t find it pretty. Not ugly in the “this looks like a DOS program from 1993” sense. You can build good-looking stuff with it. But many Ratatui TUIs fall into that square, gray, functional look, like a datacenter admin panel.

I like the Charmbracelet vibe more. gum, for example, is a collection of commands that make shell scripts interactive without turning them into a festival of read -p and case. Prompt, select, filter, spinner, table, pager, styling. You can make a bash script feel like a decent app in minutes.

And then there is Bubble Tea, in Go, inspired by Elm architecture. You have a model, receive messages, update state, render a view. Simple idea, very good fit for terminal apps: state comes in, event comes in, view goes out. Charm also has visual taste I like: good colors, decent spacing, light components, nothing that looks like a WinForms form thrown into a terminal.

So I wanted this: stay in Rust with Ratatui, but steal the feeling of Bubble Tea. Not the whole runtime. Not a perfect clone. Just the visual direction and a few components.

That is how ratatui-bubbletea was born.

The project does not replace Ratatui. It sits on top. The idea is to offer a theme and component layer inspired by Bubble Tea/Bubbles, while still rendering through Ratatui.

Right now it is split into crates:

• ratatui-bubbletea-theme, with palette, helpers, and shared styles.
• ratatui-bubbletea-components, with ready-made components like select list, spinner, progress, table, text input, viewport, and help.
• ratatui-tea, optional, for people who want ergonomics closer to Model, Msg, and Cmd, without pretending Rust became Go.

The README has the full examples and documentation for what exists today. For now, I treat it as a small toolkit. It serves my apps, and if it serves somebody else, fine. If it doesn’t, no drama either. The goal was to stop reimplementing the same theme and the same widgets every time I started a new TUI.

ai-usagebar as the public example

Since I won’t open the financial app, I needed a public example using this aesthetic. So I updated my ai-usagebar.

If you don’t remember it, I explained the project in “I Built a Waybar Widget for Omarchy to Monitor LLM Plan Usage: ai-usagebar”. It started as a Waybar widget to show LLM plan usage: Claude, OpenAI Codex/ChatGPT, Z.AI, OpenRouter. One glance at the bar and I know whether I am close to the limit and which vendor to use next.

Later it also became a standalone TUI. And thanks to contributions, it now supports Windows too. That is funny because its origin is completely Linux/Omarchy/Waybar. But that is open source: somebody uses it in another environment, finds friction, sends a PR, and now the project is a little less provincial.

In ai-usagebar, the visual change will not alter anybody’s life. It is a simple screen. Tabs, gauges, text, shortcuts. But it is a good example because it is small, real, tested, packaged, and does not depend on my private app. You can look at the code and see how I applied the theme layer.

The scratch-my-own-itch apps

All these projects follow the same logic: I have an itch, I make a small tool, I use it, adjust it, package it. No startup roadmap. No manifesto. Just a tool that fixes something annoying in my own setup.

One recent example is clock-tui. It did not start with me. It was an old Rust project, tclock, that looked abandoned. I wanted a big clock on my second vertical monitor. That monitor sits on the side, and I like having a huge desk clock taking up part of the screen. I used the original clock-tui for a while.

But an entire vertical screen just to show the time is wasteful. I already had ghpending, which lists open issues and PRs across all my projects. It is my “is anybody waiting for an answer?” in CLI form. I also wanted to see my agenda.

So I made another small app: google-calendar-tui. It uses the Gmail accounts already registered in GNOME Online Accounts and summarizes my upcoming appointments in the terminal. Read-only. No new OAuth ritual. No extra secret config scattered somewhere weird.

With those two pieces, I modernized clock-tui and added auto-refreshing widget layout support. Now the clock takes the screen the way I wanted, but around it I also get GitHub pending work and Google Calendar appointments.

This is exactly the kind of thing I would never build if it cost me an entire weekend. But with an LLM, it becomes a sequence of small tasks: read the old project, modernize dependencies, run tests, add a widget module, call ghpending, call google-calendar-tui, organize layout, fix bugs, package. It still takes work. But it is supervision and refinement work, not fighting boilerplate.

Tweaking Geary without a fork

Another itch came from GNOME.

Since I wanted to centralize my accounts in GNOME Online Accounts, I started using Geary and GNOME Calendar on the second monitor too. I like the idea: accounts configured once, desktop apps reusing the same infrastructure, no tiny program inventing its own login flow.

The problem is that Geary has a fixed three-column layout. On a normal screen, fine. On a vertical monitor, it gets cramped. The folder column, message list, and email body fight for space. I did not want to maintain a Geary fork just to hide a sidebar. Forking a large GTK app is debt. You blink and spend the rest of your life resolving merge conflicts.

So I made a GTK module: geary-hide-sidebar-module. It injects behavior into Geary at runtime and lets me collapse/expand the sidebar, with a shortcut and auto-collapse for narrow windows. No rebuilding Geary. No fork to maintain. Just a small module with one very specific job.

This is a good lesson: sometimes you do not need to fork the whole application. You can adjust it from the outside. GTK_MODULES exists. Wrappers exist. Config exists. CSS exists. Scripts exist. Not every customization has to become eternal maintenance of somebody else’s code.

Small code got cheap

That is why I keep insisting on this idea of small apps. With current LLMs, it became very easy to implement a specific idea to make your environment fit your needs. No waiting for someone else to have the exact same pain. No searching GitHub for three hours for a tool that does 80% of what you want and 40% of what you don’t want.

You describe the itch, create a repo, ask for a prototype, test it, ask for refactoring, ask for tests, ask for packaging. If it sucks, throw it away. If it works, install it and use it.

I do not let this turn into random junk dumped in ~/bin with no owner. My apps have tests. They have automated builds. Many have GitHub releases, AUR packages, normal installation with yay on Arch. They use XDG paths, so config goes to ~/.config, cache goes to ~/.cache, data goes to ~/.local/share. Organized. Upgradable. Removable. Something another person can clone and contribute to.

Here are all the links in one place:

• ratatui-bubbletea
• ai-usagebar
• clock-tui
• ghpending
• google-calendar-tui
• geary-hide-sidebar-module
• ai-jail
• ai-memory

If you use any of them and it breaks in your setup, open an issue. If you know how to fix it, send a PR. I actually use these tools, so useful bug reports tend to turn into fixes fast.

My practical rule is this: customize your environment without turning everything into duct tape. Build small tools. Test them. Package them. Document them. Let the LLM carry the boring weight and use your brain to decide what is worth keeping.

That is the fun part of programming that had gone missing for a bit. Now it is back.

Five days ago I wrote a long post on coding-agent memory where I recommended agentmemory as the answer. After a week running it in personal production, I’m walking it back. This post explains what went wrong and the open source project I started building to fix it: ai-memory.

Why agentmemory didn’t pan out

agentmemory has the right ideas (Karpathy’s LLM Wiki, tiered consolidation, automatic-capture hooks, MCP) but the implementation has structural problems that hurt in daily use. The main ones I hit in practice:

• BM25 reindex on every restart. The index persists to a file (mem:index:bm25.bin) through a remote KV called iii-engine. With few observations it flies, but pass 10K observations and state::set starts timing out, the file stays at ~96 empty bytes, and every restart pays ~5 minutes rebuilding from scratch (issue #309, still open).
• 5-second data-loss window. All persistence flows through a 5s debounce on IndexPersistence. When the 30s state::set timeout blows up, the Node process dies taking everything that was in memory with it (#204).
• Two config-read paths in the same codebase. process.env directly in one place, getMergedEnv() in another. The classic “I set the variable and nothing changed” (#456).
• Wrong hook key on ~47% of Claude Code tool calls. The hook reads data.tool_output, but Claude Code sends tool_response. Six weeks of observations silently vanishing (#539).
• Engine runs from the caller’s working directory. Windows users thought they’d lost memories because every terminal opened the state store in a different path (#303, still open).

There’s more. I wrote it all up here in my research repo. The author is responsive, the repo has 15.7K stars, and even so the architecture chosen (TypeScript MCP + separate iii-engine Rust binary + 4 ports, 3 processes, in-memory indexes persisted via remote KV) accumulates a class of bug you can’t close without rewriting half the system. The shape of the problem is structural, not a lack of effort from the maintainer.

Same story with every other solution I tried: either it’s incomplete, or too fixated on some specific technology (proprietary vector DB, a knowledge graph that needs Neo4j, an elaborate LLM pipeline), or it demands that the user yell write_note every time something’s worth saving. None of them “stay out of the way” enough for me to trust them in long sessions.

What I wanted from day one

When I started my 37-day vibe coding marathon back in February, I knew I needed some kind of knowledge organizer. It took more than 500 hours of experimentation to crystallize what I actually wanted.

If you use just one of the three (only Claude Code, or only Codex, or only opencode) and stay there, you probably don’t need anything extra. The three of them already do a reasonable job of managing memory within the session. Claude Code has three levels of compaction (time-gap microcompact, token-threshold autocompact, experimental sessionMemoryCompact). Codex has per-model auto_compact_token_limit. opencode has anchored compaction with a 20K buffer. I covered this in detail in the previous post.

The one extra discipline worth adopting in that scenario is to keep a docs/ folder in the project with markdown files organized by topic, and ask the agent to save there when something important happens. Research you don’t want to redo, known gotchas, why you picked option A over B. Works. Takes discipline.

The problem shows up for people like me, jumping between agents in the same project. I use Claude Code by default (I find the harness, the subagent orchestrator, and the long-task planning superior). But when Claude gets stuck, I fire up Codex in the same directory just to “stir things up.” Codex thinks more “outside the box” and sometimes finds a solution Claude didn’t see. Then I go back to Claude to implement carefully.

This back-and-forth between agents is where external memory really matters. Without it:

• You close Claude Code, open Codex in the same directory, and Codex knows nothing about the last 4 hours of discussion.
• You have to manually ask Claude to write a handoff note to ./HANDOFF.md, then ask Codex to read it. Every time.
• Projects you left untouched for weeks: you open them again, forgot why you decided against Redis, forgot what the bug in library X was.

Karpathy nailed the concept in his LLM Wiki, which I went deep on in the previous post. But there’s one specific line from the gist that stuck in my head:

index.md is “surprisingly good at ~100 sources, a few hundred pages, no embeddings needed”.

That line summed up what I wanted. You don’t need complicated technology. Simple storage (markdown in git), simple index (SQLite with FTS5 and links), simple install (a binary or container), automatic use (hooks that fire on their own), zero maintenance (memory decays without the user touching anything).

That’s why I started ai-memory.

Research before code

Instead of just diving into code, we dug through the source and issues of the relevant projects to understand what each one got right and wrong. The research lives in the repo itself:

• research-karpathy-llm-wiki.md — what Karpathy literally wrote, separated from what the community attributes (paraphrasing) to him. Three core principles: compile instead of retrieve, three layers (raw / wiki / schema), three operations (ingest / query / lint). The conceptual blueprint.
• research-agentmemory.md — technical breakdown of agentmemory: four consolidation tiers (working → episodic → semantic → procedural), supersession with is_latest=false instead of delete, exponential decay, cluster reflection. I kept agentmemory’s ideas; I changed the implementation.
• research-basic-memory.md — Python, MCP-native, plain markdown on disk. The model is explicitly manual: the agent calls write_note when it decides to save. Good storage model, terrible capture model (it depends on the agent remembering to call).
• research-cognee.md — cognify pipeline (extract → chunk → graph + summarize → embed → persist) with a triple knowledge graph + vector + relational store. Excellent for a well-funded enterprise agent that wants semantic relationships between entities. Way too heavy for “coding session memory.”

The synthesis I took away: agentmemory has the right ideas. The rest is execution.

The idea I like most from agentmemory, which it inherited partially from LLM Wiki v2, is the sleep-style consolidation: short memory keeps raw detail, long memory keeps consolidating and summarizing, and long-term memory that nobody touches eventually gets forgotten. It doesn’t pile up cruft. There’s accessCount, geometric exponential decay, spaced-repetition reinforcement. It’s similar to (and inspired by) what a human does while sleeping.

In ai-memory I kept that structure but swapped the engineering underneath:

• TypeScript → single Rust binary. No separate remote KV. No 3 processes. One Rust binary, with a data directory and an Axum server.
• Persistent index in SQLite + FTS5. Native. No reindex on every restart. WAL mode, 5s busy_timeout.
• Single writer in a dedicated thread via mpsc. No 5s loss window, no 30s timeout blowing up.
• Plain markdown on disk as source of truth. SQLite is just a derived index. You can open the wiki in Obsidian. You can grep it. You can version it with git (and it versions automatically).
• Per-project isolation in the physical layout on disk. <wiki_root>/<workspace_id>/<project_id>/... keyed by stable UUIDs. Renaming a project is a column update. Deleting a project is rm -rf on a subdir. Same page name in two projects doesn’t collide.
• Embedding and LLM are optional. Without a provider key, the system still works with FTS5, link expansion, and raw-observation fallback. Add embeddings when you want vector re-ranking, and Claude Haiku or GPT-5.4-mini when you want quality consolidated pages.

How it works day to day

Interaction with the agents happens through two mechanisms: hooks/extensions (automatic capture) and MCP (on-demand query).

Claude Code and Codex use shell hooks. OpenCode uses a TypeScript plugin. OMP/Pi uses a TypeScript extension. Cursor and Gemini CLI use JSON lifecycle config. They all emit equivalent events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd) as fire-and-forget POSTs to ai-memory’s HTTP server (running at 127.0.0.1:49374 by default). The agent never waits. If ai-memory is down, the session continues normally, just without capture. Claude Desktop and OpenClaw are MCP-only: they can query memory, but they don’t automatically capture lifecycle events.

On the agent side, the MCP server exposes tools the LLM can call when it sees fit:

The routing snippet that lands in CLAUDE.md (or AGENTS.md for Codex/OpenCode/Cursor/Gemini/OMP) is what teaches the agent when to call which tool. You install it with one command: ask the agent “install the ai-memory routing in this project” and it invokes the MCP tool memory_install_self_routing, gets back the canonical snippet, and writes it to the right file. Idempotent.

Handoff between agents in action

Here’s the concrete scenario that motivated the project:

$ claude
> "Refactoring auth. JWT rotation is broken; I'm going to try
   session cookies as an alternative."
[works for an hour]
> /exit

$ codex   # same directory, hours or days later
[ai-memory's SessionStart hook fetches the handoff and prepends it to context]
> "Picking up: you were investigating session cookies as an
   alternative to broken JWT rotation. Continue?"

You did nothing special. At Claude Code’s SessionEnd, ai-memory consolidated the session’s observations into a sessions/<uuid>.md page, created a typed handoff with open_questions + next_steps, and marked it “pending.” At Codex’s SessionStart, the server saw the pending handoff, fetched it, and injected it into the initial context. The agent reads and continues.

Same scenario if you abandon the project for two months and come back. memory_explore auto-tunes verbosity: less than an hour since the last session, it returns one line. More than 30 days, it returns a full catch-up of what happened.

Adopting ai-memory on an existing project

If you install ai-memory on a project with months of history, the wiki starts empty and the first sessions break even — you’re populating, not retrieving. ai-memory bootstrap solves this. It collects your git log, README, docs/, module headers, and project-rules files (CLAUDE.md / AGENTS.md), then sends them to the server which uses the LLM to generate seed wiki pages:

cd ~/Projects/my-project
ai-memory bootstrap

Costs about $0.05 with Claude Haiku 4.5 (budget capped at 50K input tokens). Run with --dry-run first to see what would be sent without paying. From there the wiki starts with real context, and every session builds on top.

Install: three commands

I reduced the install to the bare essentials. The recommended path is Docker, because the server stays isolated and updates are one line. Nothing else needed:

# 1. Wrapper script (~3KB) that runs the binary inside the container
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory \
    -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory

# 2. Start the server (loopback-only, no auth — single-user laptop)
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    akitaonrails/ai-memory:latest

# 3. Wire up your agent
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

Done. Open Claude Code as usual. Every prompt and tool call now lands in ai-memory, and the next session you open in this project will see a handoff with where you left off.

Repeat step 3 with --agent codex, --agent opencode, --agent omp/pi, --client cursor, --client gemini-cli, --client pi/omp, etc. for other agents. Claude Desktop and OpenClaw are MCP-only. Idempotent: re-running replaces only the ai-memory entry, preserving any other hooks/MCP servers you have. It writes a .bak-<timestamp> backup before every modifying write.

The project README covers the variations (Docker compose, homelab on the LAN with a bearer token, no-Docker install, source build). Follow docs/install.md if your setup wanders off the happy path.

Useful commands worth knowing

Once installed, the day-to-day is just using the agents. But it’s worth knowing a handful of commands for when you need them:

• ai-memory upgrade — self-upgrades the wrapper + docker pulls the new image + re-stages hook scripts/plugins/extensions. Idempotent. If you have a separate remote server, this only refreshes the local client; you update the server separately.
• ai-memory bootstrap — seeds the wiki from git log + README + docs/ + project rules. For projects that existed before ai-memory came along.
• ai-memory purge-project --project <name> --confirm — wipes an entire project. Atomic: SQLite rows, the wiki subdir, neighbors untouched.
• ai-memory rename-project --from <name> --to <new> — renames. One column in the DB, no file moves on disk. No side effects.
• ai-memory backup — snapshot of the data directory (wiki + SQLite). ai-memory restore undoes it.
• ai-memory lint / ai-memory forget-sweep / ai-memory embed — manual maintenance. Lint and forget-sweep also run on the server schedule by default; embedding backfill exists but stays off by default because it may call a paid provider.
• ai-memory generate-auth-token — when you’re about to expose the server beyond loopback (see docs/deploy.md).

Spelunking the wiki in the browser

The server can also mount a read-only web UI at http://127.0.0.1:49374/web when started with --enable-web. Same binary, same port, no extra process. It’s handy for three practical things: auditing what the agent’s been saving, checking whether the consolidated pages still look coherent, and sharing a single page with a teammate without giving them access to the agent.

The homepage lists detected projects, each with a page count and time since last activity:

Notice the orange warning at the top: the wiki is optimised for LLM consumption, with pages compiled from session observations by the LLM consolidator. For human-curated canonical documentation, use the project’s own docs/. The /web UI is for spelunking.

Each project is isolated by UUID in the physical layout on disk. Two pages with the same path in different projects don’t collide. Click a card and you land in the project’s page tree:

The sidebar groups the tree by kind: concepts/ (durable knowledge), decisions/ (architectural calls), gotchas/ (footguns), _rules/ (project rules suggested for promotion into CLAUDE.md), sessions/ (per-session logs), and bootstrap.md (the manifest generated by ai-memory bootstrap). The right column shows recent activity.

Click any page and you land in rendered markdown:

The rendering has syntax highlighting, tier badges (working/episodic/semantic/procedural) and kind badges (decision/gotcha/rule/fact), breadcrumbs, the supersession chain visible. Search combines FTS5, link expansion, and embeddings when configured; light/dark mode follows the OS preference via prefers-color-scheme.

To edit the wiki you open the files directly in any markdown editor (Obsidian works great). The web UI is read-only by design: the LLM consolidator is the one writing, humans just read.

Why Docker

Picking Docker as the recommended path was deliberate. A few practical wins:

• Updates are one line. ai-memory upgrade pulls the new image, refreshes the wrapper, re-stages hooks/plugins/extensions. You don’t compile Rust, don’t manage libsqlite versions, don’t fight with mise/Node version churn the way Node-based solutions force you to.
• Real isolation. The server runs in the container, reads only /data (named volume), doesn’t pollute your system. To clean up, it’s docker volume rm.
• Same image across setups. Laptop, desktop, homelab. Same amd64 or arm64 image.
• Auto restart. --restart unless-stopped brings the server back when you restart Docker, or when the machine boots (assuming systemctl enable docker).
• No source build needed. Compiling the Rust 1.95+ toolchain takes about 3 minutes in release. For end users, that’s unnecessary ceremony. Docker abstracts it away.

There’s a no-Docker path in docs/install.md for anyone who prefers it. But Docker is where the UX is best.

Which LLM for consolidation

This is a case where you don’t need a heavy model. Consolidation is text in, text out: the agent records raw observations during the session, on SessionEnd the LLM compiles 1-5 wiki pages classified as concept / decision / gotcha / rule. No complex reasoning, no code. Opus 4.7 or GPT-5.5 thinking are overkill — expensive and slow for a task that accepts a light model.

To pick the default we ran serious A/B testing across 6 different providers against 5 synthetic fixtures, each designed to stress a specific failure mode: multi-page extraction, restraint (resisting the urge to fabricate a page when the session is trivial), correct classification of rule vs gotcha vs decision, and topic separation. Full writeup with parse-rate, latency, and quality tables per fixture is at docs/llm-provider-comparison.md. The summary table:

Why Haiku ended up as default: hosted (always available), best at restraint (resists fabricating pages when the session is trivial, crucial for the wiki not to turn into a pile of empty pages), and best at classification (consistently gets kind: rule right, which is what makes auto-routing to _rules/<slug>.md work). $0.02 per consolidation is negligible for personal use.

But the user has legitimate alternatives:

• GPT-5.4-mini if budget is tight (5× cheaper than Haiku, 2× faster). The only measurable defect was fabricating a decisions/docs-spelling.md page on a typo-fix session. Over-classification, but mild.
• qwen3:32b on Ollama if you have a local server with ~20GB of RAM/VRAM. Zero cost per consolidation, fidelity comparable to the top hosted models. The ~92s latency doesn’t matter because consolidation runs in the background.
• DeepSeek V4 Flash works, but GPT-mini matches it on quality and beats it on speed.

If you want to test other models, the eval harness is at evals/ as a separate Rust crate. Add a JSON fixture, run cargo run -p ai-memory-eval --release, compare two providers side by side. Outputs land in evals/runs/<timestamp>/{baseline,candidate}/ with the exact .raw.txt the model answered plus .meta.json for latency and parse rate. PRs with new models tested are very welcome.

Status: beta, needs users

ai-memory is at the v0.2-complete tag on GitHub. The main features work: automatic capture, MCP, optional web UI, bootstrap, purge/rename/backup, bearer auth, browsing, FTS5 + graph/link-neighbour RRF search, optional embeddings, consolidation, decay, scheduled maintenance, and handoff across Claude Code / Codex / OpenCode / Cursor / Gemini CLI / OMP-Pi. I’ve been running it in personal production for a few weeks.

But it’s beta. It needs many more users banging on it for me to find the bugs that don’t show up on my machine. Claude Desktop and OpenClaw work as MCP-only clients; some exotic MCP clients still need real testing. The most polished integration today is Claude Code, followed by Codex, OpenCode, and OMP/Pi.

If you’ve made it this far, consider installing and sending feedback. Issues at github.com/akitaonrails/ai-memory/issues. PRs are very welcome — the code is Rust, MIT licensed, and the architecture is documented in docs/ARCHITECTURE.md and docs/design-decisions.md. Even a bug report of “I installed it, it didn’t run on my setup” helps — it means I assumed something about environments that doesn’t match yours.

The core motivation stays the Karpathy line. Agent memory is text. Text lives on disk. You index it with SQLite. You compile with an LLM when the work is worth it. You forget what nobody looks at anymore. You stay out of the way. And when you switch agents in the middle of a project, the next one already knows where you left off.

That’s what ai-memory tries to deliver.

It “works,” but this project was more about the exercise. With that out of the way, let me tell you why I did it.

The problem with OpenClaw

OpenClaw is a gateway that connects messaging channels (Telegram, Discord, Slack, WhatsApp, etc.) to AI providers (OpenAI, Anthropic, Ollama). You configure it, bring up the server, and you can chat with LLMs straight from Telegram or any other channel. It’s a popular project with plenty of activity.

Too much activity, actually.

I did a depth-1 clone of the repo and ran tokei:

Over a million lines of TypeScript. The 2,799 test files sound like a lot in absolute numbers, but proportional to the codebase size, the coverage is low. Most of the code lives in 29 packages of a monorepo with 21 channel extensions.

I went looking for more commits to understand the development pace. In the 100 commits I managed to pull, all of them landed in just 2 days (March 9 and 10). ~50 commits per day, from 42 different contributors. Vibe coding to the extreme.

The conclusion is the one you’re imagining: enormous volumes of AI-generated code being dumped into a repository at a speed that makes serious human review impossible. And that bothered me enough to go investigate further.

The security audit

I asked Claude to do a complete security audit of OpenClaw’s code. The report found:

Seven critical vulnerabilities. Let me list a few:

• Timing side-channel in token comparison — safeEqualSecret() does an early return on the type-check, letting an attacker distinguish malformed tokens from wrong tokens by measuring latency.
• eval() in the browser tool — arbitrary JavaScript execution with no sandbox.
• Shell with no allowlist — any tool can run any command on the system.
• Slack webhooks with no signature verification at all.
• Transcripts and config in plaintext on disk, no encryption.
• No effective rate limiting — IPs can be spoofed if the operator configures trusted proxies broadly.

Those are just the ones Claude found in an automated scan. There are probably more.

I’m not going to run that on my machine. Not even inside a Docker container. A gateway that receives webhooks from the internet, executes shell commands, connects to AI APIs with your keys, and stores conversation history, all of it with 7 known critical vulnerabilities? No, thanks.

So I did what any rational developer would do: I decided to build my own.

The first attempt: Claude Code

I started the most direct way. Cloned OpenClaw, pointed Claude Code at the code, and asked: “rewrite this in Rust.”

Didn’t work. The codebase is too big. Over a million lines of TypeScript spread across 29 packages. Claude can’t keep all of it in context. The initial result was very incomplete: lots of types created but no implementation, todo!() everywhere, too much boilerplate and not enough functionality.

I switched to Codex 5.4 to test. Same thing: I asked it to analyze and rewrite. It improved a bit in certain aspects, but the fundamental problem is the same. No AI today takes a project of that size and rewrites it in one go. The context doesn’t fit.

The technique that actually works

What works is going slowly. One step at a time.

Ask Claude (or Codex) to analyze the original code in stages. Make a long plan detailing each feature. Then implement one feature at a time in Rust, with tests, commit, and repeat. It’s tedious, but it produces code that compiles and actually works.

The reason is simple: the original code is so massive that no AI agent (and not even several in parallel) can keep all of it in context at the same time. You have to decide what matters, implement that, validate, and move on to the next thing.

And you have to decide what to cut. OpenClaw has 21 channel extensions: Google Chat, iMessage, IRC, Teams, Matrix, Mattermost, Nostr, Twitch… I don’t need any of those. I kept the mainstream channels: Web, Telegram, Discord, Slack, Signal, WhatsApp and Email. TTS? Out. Polls? Out. WhatsApp Web through Baileys? Out, I use the official Cloud API. They’re features that add complexity without proportional value.

Discovering IronClaw

In the middle of development, I came across IronClaw, which presents itself as “OpenClaw in Rust.” Great, I thought. Let me see what they did.

I cloned the repo and asked Claude to write a comparison report. IronClaw has good things. I adopted 12 features:

Circuit breaker with retry and exponential backoff for LLM provider resilience. Credential leak detection in the output. LLM response cache with SHA-256 of the prompt. Cost tracking with budget guards (warning at 80%, block at 100%). Extended thinking for Claude 3.7+ and o1. MCP client for external tool servers. Lifecycle hooks on inbound, tool calls and outbound. Smart model routing that sends simple queries to cheaper models. Tunnel support (cloudflared, ngrok, tailscale). Interactive REPL (frankclaw chat). Routines with event triggers beyond cron. Job state machine with auto-repair.

But IronClaw depends on PostgreSQL + pgvector, has a WASM sandbox (wasmtime adds ~10MB), and is part of the NEAR AI ecosystem. I want a single binary with embedded SQLite and zero external dependencies.

What FrankClaw brings from OpenClaw

The OpenClaw core is there: 7 messaging channels, multi-provider with failover, agent runtime, command system, skills, subagents, browser automation through CDP, bash tool with allowlist, cron jobs, interactive REPL. Plus the 12 IronClaw features I listed above.

But several pieces had to be rewritten in a way the original didn’t. Context compaction, for example, uses a sliding window with token estimation, message pruning and automatic repair of tool pairs that get orphaned when the context is cut. Provider failover is now model-aware: if you ask for a Claude model and the current provider is OpenAI, it skips automatically instead of erroring out. The canvas renders SVG, HTML and Markdown with revision conflict detection. Things that in OpenClaw either didn’t exist or were half-built.

Then came the phase of adding what was missing for parity. FrankClaw today has 30+ LLM tools: web_fetch (SSRF-safe with HTML-to-text), web_search (Brave API), file_read/file_write/file_edit (sandboxed in the workspace with path traversal protection), pdf_read, image_describe (through vision models), audio_transcribe, sessions_list/sessions_history/sessions_delete, message_send/message_react, cron_list/cron_add/cron_remove, config_get (auto-redacts secrets), agents_list, memory_get/memory_search, plus the browser tools (browser_open, browser_extract, browser_snapshot, browser_click, browser_type, browser_wait, browser_press, browser_sessions, browser_close, browser_aria).

Some additions that don’t exist in the original OpenClaw: a memory/RAG system with SQLite FTS5 and embeddings (OpenAI, Gemini, Voyage) that automatically syncs workspace files. An OpenAI-compatible API (/v1/chat/completions and /v1/models), so any client that speaks that protocol (Cursor, Continue, Open WebUI) can use FrankClaw as a backend with no adaptation. A ratatui TUI for people who prefer the terminal. Interactive approval of destructive tools before execution.

Smaller things that make a difference in practice. You can configure multiple API keys per provider with round-robin and automatic backoff, so if one key hits the rate limit, the next one takes over. The model catalog already knows context windows and costs of OpenAI and Anthropic models without you having to configure them. URL extraction from messages has a private IP blocklist against SSRF. The command system accepts inline directives (/think, /model) in addition to aliases.

On the operational side: ACP (Agent Client Protocol) over JSON-RPC 2.0 on top of NDJSON for people who want to integrate programmatically. Plugin system with manifests and enable/disable lifecycle. i18n with 9 locales via FRANKCLAW_LANG. Workspace identity files (SOUL.md, IDENTITY.md) to define the bot’s personality per project. Channel health monitor with auto-restart. WebSocket with ping keepalive that survives proxy and tunnel timeouts. frankclaw start/stop/status for people who want to run it as a daemon with PID tracking. And the entire configuration migrated from JSON to TOML.

Hardening: where the real difference is

The audit report we ran on OpenClaw found 7 critical and 9 high vulnerabilities. FrankClaw fixes all of them:

FrankClaw compiles with #![forbid(unsafe_code)] in all 13 crates. Zero unsafe blocks.

And the audit didn’t stop at OpenClaw. We did a per-component audit in 14 phases comparing each part of FrankClaw against the original: channels, providers, runtime, tools, sessions, crypto, cron, webhooks. All documented.

Deploy: how to install

FrankClaw runs with Docker Compose. Three containers: gateway, headless Chromium (for browser tools), and Cloudflare tunnel (to receive webhooks).

1. Clone and configure

git clone https://github.com/akitaonrails/frankclaw.git
cd frankclaw
cp .env.docker.example .env.docker

Edit .env.docker with your keys:

# Providers de IA (preencha os que usar)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

# Canais (preencha os que quiser usar)
TELEGRAM_BOT_TOKEN=         # via @BotFather
WHATSAPP_TOKEN=             # Meta Business Platform
WHATSAPP_PHONE_ID=
WHATSAPP_VERIFY_TOKEN=
DISCORD_BOT_TOKEN=
SLACK_BOT_TOKEN=
SLACK_APP_TOKEN=

# Embedding providers (só se usar memória/RAG)
# GEMINI_API_KEY=
# VOYAGE_API_KEY=

# Opcional: criptografia de sessions (recomendado)
# Gere com: openssl rand -base64 32
FRANKCLAW_MASTER_KEY=

# Opcional: scan de malware em uploads
VIRUSTOTAL_API_KEY=

2. Configure the gateway

The frankclaw.toml file defines agents, models and channels. Use the wizard or the examples:

# Generate a base config with the web channel
cargo run -- onboard --channel web

# Or copy from the examples
ls examples/channels/

For each channel, the CLI has ready-made templates:

cargo run -- config-example --channel telegram
cargo run -- config-example --channel whatsapp

3. Cloudflare Tunnel (to receive webhooks)

If you’re going to use channels that need a webhook (Telegram, Discord, Slack, WhatsApp), you need a public tunnel. The Docker Compose already includes cloudflared:

# Copy your Cloudflare credentials
cp docker/cloudflared/config.yml.example docker/cloudflared/config.yml
cp ~/.cloudflared/<tunnel-id>.json docker/cloudflared/credentials.json
cp ~/.cloudflared/cert.pem docker/cloudflared/cert.pem
# Edit config.yml with your hostname

4. Bring it up

docker compose up -d

The gateway comes up on port 18789 (internal to Docker). cloudflared routes external traffic. Chromium stays on the internal network for browser tools.

To test locally without Docker:

cargo run -- chat

Opens the interactive REPL straight in the terminal (it now also has a ratatui TUI with dark mode and tabs). No gateway, no webhook. Good for validating that the AI provider is responding before configuring channels.

Validation

cargo run -- check     # validates config
cargo run -- doctor    # full diagnostic
cargo run -- audit     # security audit with severity ratings

audit is the one I like the most. It checks whether you have encryption enabled, whether file permissions are correct, whether webhooks have signature verification, whether the bash tool is in deny-all. It exits with a non-zero exit code when it finds critical issues, so you can drop it in CI.

The development process

The project has 178 commits in ~5 days of work (March 10-16). Almost 57 thousand lines of Rust in 120 files, organized in 13 crates.

The commits tell the story. The first few dozens were scaffolding: workspace structure, basic types, the HTTP/WebSocket gateway, first version of the channel adapters. Mass-generated code, lots of incomplete pieces.

Then the channel adapters started, one by one:

236aa1c - Minimal Discord channel adapter
fd67017 - Minimal Slack channel adapter
9f51373 - Minimal Signal channel adapter
1052e47 - WhatsApp channel webhook adapter
035f86e - Email channel adapter (IMAP inbound, SMTP outbound)

When the basic channels were in place, the IronClaw integration came in one big commit:

c87ab32 - IronClaw-derived features: circuit breaker, retry, leak detection, cache, cost tracking, extended thinking

And then came the hardening. That was the phase where I had to step in manually the most, because Claude generates functional code but doesn’t think about attack vectors on its own:

db34198 - Prompt injection sanitization, external content wrapping, prompt size limit
5719b34 - Optional VirusTotal malware scanning for file uploads
ccd2b2b - Harden input validation across all user-facing entry points
aa918ee - Optional ai-jail sandbox for bash tool
2d7b1df - Security audit command with severity-rated findings
d12cc97 - 3-tier ToolRiskLevel system replacing binary browser mutation flag
21e0c91 - Timing-safe token comparison in WhatsApp, crypto audit tests
e240c1b - Webhook replay prevention with timestamp verification
876a78c - Gateway & media: SSRF redirect validation, filename hardening

22 security hardening commits. Plus 10 more component audits. Each finding became a commit with a fix.

Then came the per-channel audits, each one uncovering different edge cases:

43b085f - Discord audit: HELLO timeout, fatal close codes, message chunking
12c7cff - Telegram audit: caption overflow, parse fallback, edit idempotency
f515062 - WhatsApp audit: message type filtering, send error classification
3c42aff - Slack audit: fatal auth errors, send error classification

Browser tools needed extra attention. A headless Chrome that gets URLs from an LLM is an obvious attack vector:

3217a96 - Browser automation: CDP timeout, SSRF guard, session limits, crash recovery
d98a803 - Gate mutating browser tools behind operator approval
014f56e - Browser screenshot/ARIA tools for accessibility tree inspection

In the more recent commits, the project started diverging from OpenClaw:

5d73c4d - OpenAI-compatible HTTP API (/v1/chat/completions, /v1/models)
d832c36 - Memory/RAG system with SQLite FTS5, embeddings, and file sync
2b05f47 - Interactive tool approval for mutating/destructive tools
49034eb - Web console: dark mode, 8 tabs, focus mode, tool sidebar
9f51a18 - TUI, Gemini/Voyage embeddings, plugin management, ACP protocol
3c0703b - Config migration from JSON to TOML
eb130ad - Channel health monitor with auto-restart and rate limiting
2c3ea7e - Workspace bootstrap files (SOUL.md, IDENTITY.md) to system prompt
9df61bf - Model-aware failover routing, canvas SVG rendering
c7ba108 - WebSocket ping keepalive and auto-reconnect to web console

The OpenAI-compatible API is the one I use the most day to day. Cursor, Continue, Open WebUI, anything that speaks the OpenAI protocol can use FrankClaw as a backend without touching anything on the client side.

The numbers

Compared to OpenClaw:

The numbers aren’t directly comparable. OpenClaw has 21 channel extensions I cut, a more complete web UI, and niche features I didn’t port. But the core (gateway, mainstream channels, providers, runtime, sessions, tools, memory) is there with 22x less code.

How to help (beta testing)

FrankClaw works for basic conversation through Web and Telegram (I tested both). WhatsApp works for simple messages. Discord, Slack, Signal and Email are implemented but haven’t had extensive testing. We haven’t done any complex workflows yet.

If you want to test it: clone the repository, bring it up with Docker Compose, configure at least one channel (Telegram is the easiest) and try to use it normally. Send messages, test tool calls, try to break the system. Open Issues on GitHub with whatever you find.

What I know needs more eyes: workflows with tools (browser, bash, MCP), subagent orchestration, failover between providers, session persistence with encryption, smart routing between models, scheduled jobs, the memory/RAG system, and the OpenAI-compatible API. Basically everything that goes beyond “send a message, get a reply.”

You don’t have to be a Rust developer. The bigger value is in using the system in ways I didn’t think of and finding the edge cases that only show up under real use.

FrankClaw doesn’t replace OpenClaw today. OpenClaw has more channels, more features, more people working on it. But it carries the weight of over a million lines of TypeScript generated at 50 commits per day by dozens of contributors, with documented critical vulnerabilities. FrankClaw is the alternative for anyone who looks at that and thinks “I’m not running this code on my machine.”

But I’ll be honest: as fun as it was to build, I personally don’t know if I need this. FrankClaw is a generic gateway, designed to be flexible, to connect any channel to any provider, with an agent runtime, tools, subagents, jobs, hooks. It’s a lot of infrastructure.

What I’ve discovered over the last few months is that I can build custom bots for specific tasks much faster. In 1 day I have a bot working, focused on what I need, without carrying the weight of a generic framework. That’s what I did with Marvin on the newsletter project, for instance. A custom-built Discord bot that does exactly what I need and nothing else.

A generic gateway like FrankClaw makes more sense for someone who wants a unified interface between several chat channels and several AI models without coding. If that’s your case, give it a shot. If you’re a developer and you know what you want, maybe a custom bot will serve you better. Up to you.

The repository is here. AGPL-3.0.

–

In January I published a ~170-line shell script that built a sandbox with bubblewrap to run Claude Code, OpenCode, Crush and any other AI agent. It worked. It solved the problem. But it was a bash script dropped in ~/.local/bin/ that you had to copy, paste, and pray you wouldn’t need to customize too much.

Two months of using that script every day showed me its limits. I wanted per-project configuration. I wanted macOS support for the devs on my team. I wanted to stop editing bash arrays every time I needed an extra directory. And I wanted something someone could install with brew install or cargo install in 10 seconds, without reading 170 lines of script.

Result: ai-jail. A Rust tool, ~880KB, 4 dependencies, 124 tests, that does exactly what that script did and more. I’ll explain what changed and why you should be using it.

The Problem (again, for those who skipped the previous post)

AI coding agents need access to your filesystem. They need to run compilers, linters, grep, ls, make, cargo, npm. The minimum to be useful. The problem is that along with that access comes the ability to read ~/.aws/credentials, exfiltrate your SSH keys, or run an rm -rf outside the project directory.

It isn’t paranoia. Supply-chain attacks are real. Every other week some NPM, PyPI or RubyGems lib gets compromised. If the agent runs npm install and a malicious post-install script tries to exfiltrate your data, the only thing between the attacker and your credentials is whatever barrier you set up beforehand.

The answer is a sandbox. Specifically, one that lets the agent work in the project directory with the tools it needs, but makes the entire rest of the system invisible.

From Script to Tool

The shell script from the previous post already solved this with bubblewrap. ai-jail solves the same problem, but addresses the limitations that two months of daily use revealed:

The core logic is the same: bubblewrap creates isolated PID, UTS and IPC namespaces, mounts $HOME as an ephemeral tmpfs, and only mounts the project directory with write access. The difference is that all of that is now configurable without editing code.

Installation

Four ways:

# Homebrew (macOS and Linux)
brew tap akitaonrails/tap && brew install ai-jail

# Cargo
cargo install ai-jail

# Mise
mise use -g ubi:akitaonrails/ai-jail

# Direct binary from GitHub Releases
curl -fsSL https://github.com/akitaonrails/ai-jail/releases/latest/download/ai-jail-linux-x86_64.tar.gz | tar xz
sudo mv ai-jail /usr/local/bin/

On Linux, bubblewrap needs to be installed separately: pacman -S bubblewrap (Arch), apt install bubblewrap (Debian/Ubuntu), dnf install bubblewrap (Fedora). On macOS no extra dependency is needed.

Basic Usage

cd ~/Projects/my-app

# Run Claude Code inside the sandbox
ai-jail claude

# Run Codex
ai-jail codex

# Run OpenCode
ai-jail opencode

# Plain bash for debugging
ai-jail bash

# Any command
ai-jail -- python script.py

On the first run, it creates an .ai-jail file in the project directory:

# ai-jail sandbox configuration
# Edit freely. Regenerate with: ai-jail --clean --init

command = ["claude"]
rw_maps = []
ro_maps = []

This file is committable to the repo. When another dev on your team clones the project and runs ai-jail, the same configuration applies.

If you want to add extra directories, you can do it from the CLI or directly in the TOML:

# Extra directory with write access
ai-jail --rw-map ~/Projects/shared-lib claude

# Extra read-only directory
ai-jail --map /opt/datasets claude

Want to see what the sandbox is going to do without running anything?

ai-jail --dry-run --verbose claude

It shows every mount point, every isolation flag, the full bubblewrap command. No surprises.

Why Bubblewrap on Linux

I evaluated the alternatives before deciding. The full analysis document is in the repository, but the short version is:

Bubblewrap (bwrap) is the sandbox Flatpak uses to isolate every desktop app. ~50KB binary, ~4000 lines of C, maintained by the GNOME team. It runs without root using CLONE_NEWUSER to create namespaces without elevated privileges. It’s packaged in every relevant Linux distro and tested at scale by millions of Flatpak installations.

I considered and rejected the alternatives. Firejail requires setuid root, and trusting setuid to protect against agents already running on your system is contradictory. nsjail and minijail are designed for production environments (Google uses them internally), too complex for a dev workstation. systemd-nspawn requires root and is meant for system containers, not for isolating a single process.

Landlock is a different case. It doesn’t replace bubblewrap — it has nothing to do with namespaces or mount isolation. But it complements. Landlock is a Linux Security Module that controls access at the VFS level, independent of mount namespaces. That closes vectors bwrap alone doesn’t cover: escape paths through /proc, symlink tricks inside permitted mounts, and it serves as a safety net against bugs in the namespace machinery itself. As of v0.4.0, ai-jail applies Landlock automatically on kernels 5.13+ as defense-in-depth. It uses ABI V3 (Linux 6.2+) with graceful degradation to V1 on older kernels, and turns into a silent no-op if the kernel doesn’t support it. If it causes problems with some specific tool, --no-landlock turns it off.

Bubblewrap hits the exact sweet spot: real isolation without root, on every distro, and simple enough to wrap in an 880KB binary.

What the Sandbox Does on Linux

When you run ai-jail claude, this is what happens:

The agent runs in isolated PID, UTS and IPC namespaces, with hostname ai-sandbox, and dies automatically if the parent dies (--die-with-parent).

The filesystem is mounted in a specific sequence (bubblewrap is order-dependent). /usr, /etc, /opt, /sys come in read-only for system tools. /dev and /proc are mounted for device and process access. /tmp and /run come in as fresh tmpfs. GPUs auto-detected (/dev/nvidia*, /dev/dri). Docker socket, X11/Wayland, /dev/shm, all auto-detected and mounted if they exist.

The most important part is how the home directory is handled. $HOME is mounted as an empty tmpfs. Then, selectively, dotfiles get layered on top. .gnupg, .aws, .ssh, .mozilla, .sparrow are never mounted (sensitive data). .claude, .crush, .codex, .aider, .config, .cargo, .cache, .docker come in as read-write because the agents need to write here. Everything else comes in read-only. Inside ~/.config, browser subdirectories are hidden behind tmpfs: BraveSoftware, Bitwarden. Same in ~/.cache: BraveSoftware, chromium, spotify, nvidia. The agent can’t even see those directories exist.

The current project directory is the only place with write permission (besides the tool dotdirs). The agent modifies the code, but doesn’t touch anything else.

macOS: sandbox-exec

On macOS, the backend is sandbox-exec with SBPL (Sandbox Profile Language) profiles. It’s a legacy Apple API, officially deprecated but with no public replacement. It works today, but Apple may remove it in the future.

ai-jail generates an SBPL profile at runtime that mirrors the same logic as Linux:

• Default deny on everything
• Allows process operations (exec, fork, signal)
• Allows network (except in lockdown)
• Allows global reads, denies sensitive paths (.gnupg, .aws, .ssh, ~/Library/Keychains, ~/Library/Mail)
• Allows writes only in the project directory, tool dotfiles, and /tmp

The limitations are real. GPU (Metal) and Display (Cocoa) are system-level on macOS, sandbox-exec can’t restrict them. The --no-gpu and --no-display flags simply have no effect on macOS. Cross-platform parity is approximate, not exact.

Even with those limitations, it’s better than running the agent completely open. sandbox-exec protects against access to sensitive filesystem areas and, in lockdown, removes write and network permissions.

Windows: Not Supported (And Probably Never Will Be)

It’s not for lack of interest, it’s lack of primitives. Windows has no userspace equivalent to Linux namespaces. No mount API like bubblewrap. AppContainers exist but use a completely different security model, require admin privileges, and mapping bwrap functionality to AppContainers would effectively mean writing another project from scratch.

The Windows answer is WSL 2:

# Inside WSL 2 (real Linux kernel)
sudo apt install bubblewrap
cargo install ai-jail
# or: mise use -g ubi:akitaonrails/ai-jail

cd /mnt/c/Users/you/Projects/my-app
ai-jail claude

WSL 2 runs an actual Linux kernel. Bubblewrap works normally. Windows files are accessible at /mnt/c/. I/O performance is slower across the 9p mount, but it works. For large projects, cloning inside ~/Projects/ on the Linux side improves performance considerably.

Lockdown Mode

For workloads you really don’t trust, there’s --lockdown:

ai-jail --lockdown bash

Lockdown does everything normal mode does, but goes further. The project gets mounted read-only (not read-write). GPU, Docker, Display and mise are disabled. --rw-map and --map flags are ignored. $HOME becomes pure tmpfs, no host dotfiles. On Linux, the network is cut with --unshare-net and the environment is wiped with --clearenv. On macOS, environment variables are wiped and write and network rules are removed from the SBPL.

It’s the most restrictive sandbox you can build short of using a VM. Useful for auditing third-party code or running agents on projects you don’t know.

Bootstrap: Automatic Permission Configuration

ai-jail --bootstrap generates permission configurations for the tools you use:

ai-jail --bootstrap

For Claude Code, it generates ~/.claude/settings.json with allow/deny/ask lists. Allows git status, diff, log, ls, grep, cargo, npm, python, docker compose. Blocks rm -rf, sudo, chmod 777, git push –force. Asks before git push, rm, docker run.

For Codex, it generates ~/.codex/config.toml with approval_policy = "on-request".

For OpenCode, it generates ~/.config/opencode/opencode.json with bash, edit, write permissions.

Before overwriting any file, it makes an automatic backup (settings.json.bak). And it rejects operations if the target is a symlink, to avoid path traversal.

It’s exactly the content I put in manually in the previous post, but automated and tested.

But Claude Code Already Has Its Own Sandbox

It does. Since October 2025, Claude Code has offered a runtime sandbox via the /sandbox command. And guess what it uses underneath? Bubblewrap on Linux and sandbox-exec on macOS. The same stack.

But the differences matter.

ai-jail is tool-agnostic. It works with Claude, Codex, OpenCode, Crush, and any command. Claude’s sandbox only protects Claude. If tomorrow you switch agents, ai-jail keeps working the same.

The thing that bothers me most is the escape hatch. When a command fails because of a sandbox restriction, Claude can retry with dangerouslyDisableSandbox, falling back to the normal permission flow. You can disable that ("allowUnsandboxedCommands": false), but it’s opt-out, not opt-in. In ai-jail, there is no escape hatch. The process runs inside bwrap or sandbox-exec, period. There’s no way for the agent to decide on its own to leave the sandbox.

Another practical difference: .ai-jail lives in the project directory and can be committed to the repo. Any dev who clones the project inherits the same sandbox policy. Claude’s sandbox depends on a global settings.json.

When run inside Docker, Claude’s sandbox falls back to an enableWeakerNestedSandbox mode that, in the words of its own documentation, “considerably weakens security”. ai-jail wasn’t designed to run inside Docker (it runs directly on the dev’s workstation), so this problem doesn’t exist.

About the network: Claude’s sandbox routes traffic through a proxy and allows/blocks by domain. ai-jail in normal mode inherits the host network; in lockdown, it cuts the entire network with --unshare-net. Claude’s approach is more granular; ai-jail’s is simpler and harder to circumvent.

The two aren’t mutually exclusive. You can run Claude’s sandbox inside ai-jail. ai-jail handles filesystem isolation; Claude’s sandbox adds per-domain network filtering. Security layers stack.

Why Not Use –dangerously-skip-permissions Without a Jail

I’ll be blunt: if you run Claude Code with --dangerously-skip-permissions without any sandbox, you’re trusting blindly that the LLM will never execute anything destructive. And you’re trusting that none of your project’s dependencies has been compromised in a supply-chain attack.

Every --dangerously flag has that name for a reason. Claude Code is explicit: that mode exists for CI/CD and automation in environments that are already isolated (containers, throwaway VMs). Not for your personal workstation with ~/.aws/credentials, ~/.gnupg/, SSH keys, and your browser’s password vault.

With ai-jail, the agent has total autonomy inside the sandbox. It does whatever it wants in the project directory, uses the tools it needs, and can’t access anything outside what was explicitly permitted.

ai-jail + Git: The Safety Net You Already Have

There’s something I haven’t mentioned yet that changes the risk calculus: if your project is in a Git repo, with a remote on GitHub/GitLab, and the agent doesn’t have permission to git push, the damage it can cause is limited to the local directory.

Think about it. The worst-case scenario inside ai-jail is the agent corrupting every file in the project. Annoying? Sure. Catastrophic? No. You run git checkout . and you’re back to the last commit. If it corrupts .git somehow (unlikely, but possible), you delete the directory and clone again. The remote was never touched.

That’s why ai-jail’s --bootstrap puts git push on the “ask” list (ask before running), not the “allow” list. And git push --force goes straight to “deny”. The agent can commit locally all it wants, can create branches, can rebase. None of that affects the remote. When it comes time to push, you review what it did and decide whether it goes live.

That combination, sandbox for the filesystem + Git for the code + manual push, already gives you a very reasonable security level for daily use. ai-jail protects your personal data and the system. Git protects your code. And the decision to publish stays yours.

If you want to go further, the next two sections cover additional layers.

ai-jail vs Dev Containers

Since I wrote ai-jail, the most frequent question is: “why not use Dev Containers?”. The short answer is that one doesn’t replace the other. They solve different problems.

Dev Containers (the containers.dev spec) define a complete development environment in a devcontainer.json. You specify base image, tools, VS Code extensions, environment variables, and the editor mounts everything for you in a Docker container. Docker also recently launched Docker Sandboxes, which go further and run each agent in a microVM with Firecracker, with hardware isolation.

ai-jail does none of that. It doesn’t define an environment. It doesn’t install tools. It doesn’t run a Docker image. It takes the environment that already exists on your machine and restricts what the process can access.

In practice, the difference is:

Dev Container makes more sense when you need the whole team to have exactly the same environment, or when the project has dependencies nobody wants to install on the host, or for running non-interactive agents in CI/CD. Docker Sandboxes with microVM are the strongest isolation that exists outside a dedicated VM.

ai-jail makes more sense when you already have the environment configured and want instant startup with no Docker daemon. Or when you use tools that are annoying to run inside a container (CUDA, Wayland, mise). Or simply when you want the same protection for any agent, not just the ones with devcontainer integration.

And you can combine them. I know people who run ai-jail inside a Dev Container to get environment reproducibility + filesystem restriction. Security layers stack.

Immutable Operating Systems: The Last Layer

If you want to take security seriously, the third layer is the operating system itself.

Immutable systems like Fedora Silverblue, NixOS, and openSUSE Aeon have a read-only root filesystem. The base system can’t be modified by any process, even with root. Updates are atomic: they either apply completely or not at all. And if something goes wrong, you roll back to the previous image in one reboot.

In practice, that means even if an AI agent escaped the sandbox (exploiting a kernel vulnerability, for example), it couldn’t modify the system persistently. On the next reboot, the system returns to the declared state. On NixOS, the entire system is defined by a configuration file (configuration.nix). On Silverblue, the base is an OSTree image that gets atomic updates via rpm-ostree.

For developers, the catch is: your dev tools run in containers (Toolbox/Distrobox on Silverblue, nix-shell on NixOS). The base system stays untouched. Desktop apps come via Flatpak, which already runs in a sandbox. The result is that the host’s attack surface is minimal.

Fedora Silverblue is probably the most accessible entry point. It’s already Fedora underneath, with GNOME, works with hardware Fedora supports, and Toolbox gives you a containerized Fedora Server where you install whatever you want without touching the host. NixOS is more powerful (full reproducibility, declarative rollback), but the learning curve is real.

The full combination looks like this: the immutable OS handles the system (read-only filesystem, atomic updates, one-reboot rollback). ai-jail handles the session (isolated namespace, ephemeral home, sensitive data invisible). And Git handles the code (remote untouched as long as the agent doesn’t have push).

None of those layers is perfect on its own. But the attack that punches through all three at the same time — escaping the namespace, persisting on a read-only filesystem, and corrupting a Git remote — is a scenario I’d be comfortable calling unlikely.

The best part is that none of them requires changing how you work. ai-jail is one command before your agent. Git you already use. And an immutable OS is an installation, not a workflow change.

Technical Details (For Those Who Care)

Written in Rust with 124 tests and 4 dependencies: lexopt (CLI parsing without clap), serde + toml (config), nix (Unix syscalls). No async runtime, no color framework (raw ANSI), ~880KB binary with LTO and strip.

Signal handling is done correctly: SIGINT, SIGTERM, and SIGHUP are forwarded to the child process. The handler only calls libc::kill, which is async-signal-safe. Process reaping uses waitpid in a loop with retry on EINTR.

Temporary files (like the custom /etc/hosts the sandbox mounts) use RAII: a SandboxGuard that implements Drop in Rust. If the parent process dies for any reason, cleanup happens.

Configuration compatibility is guaranteed by development policy: never remove fields, never rename, new fields always with #[serde(default)], unknown fields are silently ignored. Regression tests for old .ai-jail formats guarantee that updating the binary never breaks existing configs. There are 32 tests just for config.

Roadmap

What’s left:

• More tool backends in bootstrap: Aider, Cursor, Windsurf. As more agents standardize permission configuration files.
• Profile sharing for monorepos, so you don’t have to configure each service separately.

Installation and First Use (Quick Recap)

# 1. Install
brew tap akitaonrails/tap && brew install ai-jail
# or: cargo install ai-jail

# 2. On Linux, install bubblewrap
sudo pacman -S bubblewrap  # Arch
# sudo apt install bubblewrap  # Debian/Ubuntu

# 3. Enter the project and run
cd ~/Projects/my-app
ai-jail claude

# 4. (Optional) Generate permission configs
ai-jail --bootstrap

# 5. (Optional) See what the sandbox does
ai-jail --dry-run --verbose claude

The .ai-jail file it creates can be committed to your repo. From then on, any dev who clones the project runs ai-jail claude and gets the same sandbox.

Conclusion

January’s shell script solved the problem. ai-jail solves the problem properly. Per-project config, macOS support, lockdown mode, permission bootstrap, dry-run for auditing, and an 880KB binary that installs in 10 seconds.

If you use AI agents to code, run them in a sandbox. The LLM’s good intentions are no guarantee of anything, and supply-chain attacks don’t pick their victims. Process isolation is the barrier that works.

The project is GPL-3.0 and is on GitHub: github.com/akitaonrails/ai-jail

Issues and PRs are welcome.