tbdflow needed structured JSON output first, otherwise IPC would have meant brittle string parsing. Adding --json also improved the overall developer experience: if you use tbdflow in scripts or have a Genie committing code through it, you get machine-readable output instead of human-readable text. Supported by info, status, radar, sync, recover --list, task show, and note --show.

The commands work great in the terminal. But sometimes you just want to glance at a repository’s health without switching context, a quick ambient read. That peripheral awareness is important for comprehension, especially across multiple repos (teams should really be on a monorepo, but that’s a separate post).

The result is tbdflow-ui: a persistent three-panel desktop window that sits alongside your editor and keeps the workflow visible.

What it does

The window is organised into three panels.

The left panel is your context: which repo you’re in, which branch, whether CI is enabled, whether radar is active. A quick glance tells you where you are and whether the trunk is healthy.

The centre panel is where the work happens. Sync with one click. The Intent Log is right in front: type a note, press Add Note, it calls tbdflow note "<text>" and the log refreshes immediately. The breadcrumb is the point: reasoning is sharpest at the moment you write the code, and a field sitting in front of you captures it before the next context switch. Rules that rely on documenting something later don’t have the same pull. I wrote about the underlying risk in The Comprehension Crisis. Below that is the commit form: a type dropdown populated from your repo’s tbdflow --json info config and a message. There is an Advanced toggle for the rest of the supported options.

The right panel provides Awareness: trunk status with a colour-coded signal (green, pending, red), churn hotspots from the last three days highlighted on a red-to-yellow scale, and an overlap count across active branches.

It also supports multiple repos. Click Browse, pick a directory, all panels reload. Handy if you’re switching between a few repos throughout the day.

The design rule

There’s one rule the UI follows strictly: the CLI is the source of truth.

tbdflow-ui never touches Git directly. Every piece of data comes from tbdflow --json <command>. The commit button constructs a full tbdflow commit -t <type> -m "<message>" command string and executes it. The intent log reads from tbdflow --json notes. Radar reads from tbdflow --json radar.

This matters because it means the UI can never drift out of sync with the CLI’s logic. If tbdflow adds a new commit flag tomorrow, the UI gets it by passing through the JSON output, not by reimplementing the logic.

Why a desktop app?

A terminal is perfect when you’re actively working. A desktop window serves a different purpose. It provides ambient awareness: trunk health, overlaps, hotspots, and your current intent are visible without interrupting your flow. The goal wasn’t to replace the CLI, but to complement it.

Built with hica

This is the part that interests me most, because tbdflow-ui is written in hica, my own functional, expression-based language.

hica transpiles to Koka, and Koka compiles to C. So the pipeline for tbdflow-ui is:

.hc → hica → .kk → Koka → C → native binary

For a CLI tool, that pipeline is fairly unremarkable. For a GUI app with Dear ImGui, it gets more interesting. ImGui is a C++ immediate-mode GUI library. Getting hica to talk to it meant building a thin C FFI layer that exposes ImGui’s widgets as plain C functions, then wrapping those in a hica imgui library.

The result is that the hica source looks like this:

fun render_sidebar_context(c: Config, s: Status) {
  label("Branch")
  gui_text(s.current_branch)
  gui_spacing()

  label("Mode")
  gui_text(c.mode)
  gui_spacing()

  label("CI Status:")
  gui_same_line()
  if c.ci_check_enabled {
    gui_text_colored("- Enabled", 0.06, 0.71, 0.65, 1.0)
  } else {
    gui_text_colored("o Disabled", 0.94, 0.33, 0.31, 1.0)
  }
}

No FFI boilerplate in application code. No pointer management, no widget IDs, no frame-begin/frame-end ceremony. hica’s effect system means the rendering context flows implicitly; IO effects are tracked at the type level without being specified on every function.

The commit command builder is a good example of how hica code reads. It’s purely functional: a chain of string conditionals that assembles the final shell command:

pub fun build_commit_cmd(ctype: string, msg: string, scope: string, body: string, 
                         tag: string, issue: string, breaking: bool, no_verify: bool) {
  let base = "tbdflow commit -t " + ctype + " -m \"" + msg + "\""
  let s1 = if scope != ""   { base + " -s " + scope }             else { base }
  let s2 = if body  != ""   { s1   + " --body \"" + body + "\"" } else { s1 }
  let s3 = if tag   != ""   { s2   + " --tag " + tag }            else { s2 }
  let s4 = if issue != ""   { s3   + " --issue " + issue }        else { s3 }
  let s5 = if breaking      { s4   + " --breaking" }              else { s4 }
  let s6 = if no_verify     { s5   + " --no-verify" }             else { s5 }
  s6
}

Pure functions with clear data flow and no side effects until exec() is called.

The hica imgui library

One thing I really like is the theming. Since the entire rendering surface is a hica module, I can write themes as plain hica files:

pub fun apply_theme() {
  gui_set_color_text(0.9333, 0.9411, 0.9529)
  gui_set_color_bg(0.0941, 0.1098, 0.1451)
  gui_set_color_accent(0.2314, 0.5098, 0.9647)
  gui_set_color_plot(0.0588, 0.7098, 0.6549)
  gui_set_style_rounding(4.0, 4.0, 4.0)
  gui_set_style_spacing(8.0, 6.0, 16.0)
}

Drop a different theme file in, call a different function. The app ships with a “Stillness Dark / Nordic Blue” theme and a One Dark Pro theme. Switching is one function call. The imgui library has a theme-editor if you want to create your own themes.

What this means for hica

tbdflow-ui is the most complete application I’ve built with hica so far, and hica itself didn’t require any language changes to build it. The language was already capable. What did evolve was the imgui FFI library: tbdflow-ui had requirements the earlier layer didn’t cover, so those gaps got filled as the application needed them.

That’s a healthy feedback loop. A real program with real requirements is a better driver for a library than designing the API in the abstract.

The takeaway is that hica can build real desktop GUI applications. A tool with multiple data sources, reactive panels, live CLI integration, clipboard access, hyperlinks, and two polished themes. The C FFI story works. The linking story works (Koka link flags for C++ static libs with --cclinkopts=-lc++). It compiles to a single native binary.

Try it

curl -fsSL https://github.com/cladam/tbdflow-ui/releases/latest/download/install.sh | sh

Pre-built for macOS ARM64 and Linux x86_64. Requires tbdflow v0.33.0+ and SDL2 on your system.

If you want to build from source, install hica and run hica run in the repo root.

• tbdflow-ui source - MIT licensed
• tbdflow - the CLI this wraps
• hica - the language it’s written in

This is an early release. tbdflow-ui will be improved continuously.

Throughput is a safety feature!

I find myself sceptical, and not because of the AI part.

A pattern that feels familiar

The workflow looks like this:

1. Design a large batch of features upfront.
2. Generate a large body of code from that design.
3. Review, test, and debug the output.
4. Ship it in a single release.

In DevOps, this is Big Batch Delivery. We have decades of evidence for why it struggles. Large batches amplify risk at every stage. A single flawed assumption early in the design doesn’t just invalidate one feature; it invalidates everything built on top of it.

Software requirements aren’t facts. They are a network of unverified hypotheses.

The entire purpose of iterative delivery is to test those hypotheses as cheaply and as early as possible, long before you have built an ecosystem on top of them.

AI doesn’t change this. The bottleneck was never how fast code gets written. It is the feedback loop.

The review problem

When an AI agent produces a large, multi-thousand-line output from a single specification, that code still has to be integrated, understood, and maintained by a human team. In practice, it lands in a review gate.

I explored this in The Pull Request Trap. Human comprehension doesn’t scale with line count. A team reviewing a two-thousand-line AI-generated diff faces the same cognitive limits as a team reviewing a two-thousand-line human-generated one. Under time pressure, reviews go superficial. The gate exists, but the signal is weak.

Slower integration is the obvious problem. The less obvious one is structural debt introduced without anyone understanding it well enough to manage it.

The comprehension dimension

There is also a subtler problem. When you optimise purely for generation speed, delivery and understanding come apart.

I wrote about this in The Comprehension Crisis. If a model generates the spec, the code, and the explanation, it is easy to ship without ever owning the reasoning behind it. The system looks faster but the team’s capability quietly degrades.

Human comprehension must scale with delivery, or ownership evaporates.

With large, spec-driven outputs, the team inherits a codebase they didn’t reason through. When something breaks, and it will, debugging starts from a much weaker position.

What Elephant Carpaccio teaches us

The practice of slicing work into the smallest provable unit has a name: Elephant Carpaccio. The goal isn’t smaller work for its own sake. It is to shorten the distance between a decision and its validation.

This doesn’t change when an AI is doing the coding. Fast generation only helps if you can confirm assumptions just as fast. That speed advantage disappears the moment you batch everything back up into a slow, uncertain release.

Some things stay true regardless of who writes the code:

• Feed the smallest useful slice to the agent. A tightly scoped prompt produces output that is easier to review, test, and validate in production.
• Prefer continuous integration over gates. Trunk-based development with non-blocking reviews keeps changes flowing and keeps comprehension distributed across the team.
• Treat telemetry as the ground truth. Real user behaviour, not the initial spec, is where value is confirmed or refuted.
• Throughput and comprehension are not in tension. High throughput with deep understanding lets you isolate variables and adapt quickly. High throughput without understanding is how you accumulate hidden debt.

The underlying question

Spec-Driven Development probably has a place: where requirements are stable, well-understood, and easy to verify in bulk. Most product work isn’t like that.

Writing a complete spec and getting a complete codebase back feels productive. Feeling productive and being productive are different things. If a core assumption in the spec is wrong, the cost scales with how much was built before anyone found out.

Micro-sized batches and tight feedback loops aren’t a constraint on what AI can do. They’re how you find out if what the agent produced was worth building.

Throughput is a safety feature!

A better-informed model beats a smarter one.

The idea

Ollama lets you create custom models with a Modelfile: base LLM, parameters, and a system prompt. That prompt is permanent context the model reads before every message.

hica-assistant is built on qwen3.6:35b-a3b (a mixture-of-experts model, fast on a Mac) with a system prompt covering the compiler pipeline, syntax rules, the prelude API with types, the stdlib, and a table of pitfalls from real bugs I’ve encountered during development.

ollama create hica-assistant -f Modelfile
ollama run hica-assistant

No API key needed, no data leaving the machine (works offline) and no rate limits.

The verify part

Every snippet the model generates gets checked with the hica compiler:

hica check generated.hc
hica run generated.hc
hica test generated.hc

When it fails, I find the gap in the Modelfile, add the rule, and rebuild. The system prompt is the ground truth and very updateable. My chat history is throwaway.

Let’s look at a concrete example: the model kept writing is_empty(list) to check whether a list is empty, that’s wrong as is_empty takes a string. I added a row to the pitfalls table, ran ollama create hica-assistant -f Modelfile, and the next response used match xs { [] => ... } correctly.

The loop: prompt, generate, compile, fix Modelfile, rebuild.

It works for real code

I asked it to write a filter-map-fold pipeline. First try, both styles:

fun main() {
  // pipe style
  let a = [1, 2, 3, 4, 5]
    |> filter((x) => x % 2 == 0)
    |> map((x) => x * 10)
    |> fold(0, (acc, x) => acc + x)
  println(a)   // 60

  // dot-call style, same result
  let b = [1, 2, 3, 4, 5]
    .filter((x) => x % 2 == 0)
    .map((x) => x * 10)
    .fold(0, (acc, x) => acc + x)
  println(b)   // 60
}

Both compile. Both produce 60. a |> f and a.f() are the same thing and the model knows when to reach for each.

Bounded knowledge is a feature

The model only knows what’s in the Modelfile. Ask it about get_cwd(), which doesn’t exist in hica yet, and it says so and gives the real workaround (get_env("PWD")). A generic model would invent get_cwd() confidently and leave you debugging a compile error.

When something is missing from the Modelfile, I add it. Right now it covers the prelude, std/io, std/list, std/datetime, and the main pitfall patterns. The file grows with the language.

The Modelfile is in the repo

The Modelfile is in the hica repo, Apache 2.0 licensed.

The approach works for any language, framework, or internal API a generic model hasn’t seen. Write down what it needs to know, verify with real tooling, iterate.

HiLisp is now live and ready for tinkering.

Why a Lisp?

Many developers write a Lisp at some point. Same thing here really.

The useful part is that maintaining HiLisp is hica development. Every script and example exercises the compiler and provides feedback. I ended up fixing several bugs in hica while building HiLisp.

The main inspiration was Carp, a Lisp with ML/Rust-like semantics. HiLisp borrows its vocabulary of special forms: defn, def, fn, let, do, cond, quote.

Also, there is objective beauty in parentheses.

What it looks like

(defn factorial (n)
  (if (<= n 1) 1 (* n (factorial (- n 1)))))

(println (factorial 10))   ; 3628800

Closures work:

(defn make_adder (n) (fn (x) (+ x n)))
(def add10 (make_adder 10))
(println (add10 32))   ; 42

And higher-order functions:

(defn map (f lst)
  (if (= lst '()) '()
    (cons (f (car lst)) (map f (cdr lst)))))

(println (map (fn (x) (* x x)) '(1 2 3 4 5)))
; (1 4 9 16 25)

The pipeline

HiLisp is a classic tree-walker interpreter:

source text → tokenise → parse → eval

Each phase lives in its own hica module: tokeniser.hc, parser.hc, eval.hc. The AST is a recursive LVal enum representing numbers, booleans, strings, symbols, lists, lambdas, and nil. Pattern matching over that enum drives the evaluator.

The interesting bit was environments. Each lambda captures a reference to its defining environment for proper lexical scoping. I expected that to need some gymnastics, but structs and recursive types in hica made it pretty straightforward.

Try it

./hilisp                         # REPL
./hilisp examples/recursion.hl   # run a file

# Build from source (needs hica ≥ 0.29.3 and Koka 3.2.3)
hica build -o hilisp

The examples/ folder contains runnable .hl files covering arithmetic, closures, recursion, lists, and sorting. There’s also a lib/prelude.hl with helpers like map, filter, and fold.

• Source, MIT license.
• Lisp primer, start here if you’ve never worked with a Lisp.

Going forward, I’ll definitely be using HiLisp as part of hica development itself, both as a playground and as a way to continuously exercise the compiler with real code.

Early on in hica’s design I wanted the simplest possible testing workflow, and I think I succeeded (IMHO)

This post walks through how TDD works in hica and why the compiler changes what you need to test.

TDD isn’t new

TDD has a reputation as a methodology someone invented. It’s most definitely not. Kent Beck has said he “rediscovered” it by studying older literature and watching what good programmers already did. Dijkstra argued in 1972 that correctness proof and programs should “grow hand in hand.”

Andrea Laforgia captures this well in his T*D piece. TDD, trunk-based development, and collaborative programming are patterns that keep emerging when teams care about quality and fast delivery. When you remove friction from testing, people test first. That’s what happened with hica.

The compiler does half the work

hica has Hindley-Milner inference and exhaustive pattern matching. A lot of the defensive tests I’d write in other languages aren’t needed:

type Direction {
  North, South, East, West
}

fun move(pos, dir) {
  match dir {
    North => (pos.0, pos.1 + 1),
    South => (pos.0, pos.1 - 1),
    East  => (pos.0 + 1, pos.1),
    West  => (pos.0 - 1, pos.1)
  }
}

Forget the null case (there’s no null). Pass a string where a Direction is expected? It won’t compile. Leave out West? Compile error. The type checker handles structural correctness. What’s left for tests is whether the function does the right thing.

Rule of thumb: if the compiler can’t distinguish a correct implementation from an incorrect one, write a test.

Red-green-refactor

Let’s build a simple password validator from scratch.

Red. Stub the interface, assert what you want:

fun validate(password) => false

test "valid password has 6+ characters" {
  assert(validate("secret123"))
}

hica test password.hc fails. Good, that’s expected.

Green. Minimum code to pass:

fun validate(password) => str_length(password) >= 6

Passes.

Red again. New requirement: passwords need at least one digit. Add a test for it. It should fail against the current validate implementation:

test "rejects password without digit" {
  assert_false(validate("noNumbersHere"))
}

Green. Update the implementation to pass all tests:

fun has_digit(s) => any(chars(s), (c) => is_digit(c))

fun validate(password) {
  let long_enough = str_length(password) >= 6
  long_enough && has_digit(password)
}

test "valid password has 6+ characters" {
  assert(validate("secret123"))
}

test "rejects password without digit" {
  assert_false(validate("noNumbersHere"))
}

test "rejects short password" {
  assert_false(validate("ab1"))
}

All three pass. Refactor whenever, the tests catch regressions.

No context switch

Tests live next to the code:

fun double(x) => x * 2

test "double works" {
  assert_eq(double(3), 6)
  assert_eq(double(0), 0)
}

running 1 test(s)...

  ✓ double works

1 test(s) passed

When something breaks:

  ✗ double works
    assertion failed: assert_eq(double(3), 5)
      expected: 5
      actually: 6

Use assert_eq over assert. “expected 5, got 6” tells you what happened, assert just says “false”.

A typical session

hica repl                # explore an API before writing tests
nvim password.hc         # write a failing test
hica test password.hc    # see it fail
nvim password.hc         # make it pass
hica test password.hc    # see it pass
hica check password.hc   # fast type-check between edits
tbdflow commit -t feat -m "add password validation"

hica check only type-checks, no compilation and near instant. I run it between almost every edit, like a spellchecker for logic 🙂 hica repl is useful when you’re not sure what a function returns. Try it interactively first, then write the test.

One test per behaviour

“Validates length” and “requires digit” are separate tests. If a test name needs “and” in it, split it.

Happy testing!

Throughput is a safety feature! (now with tests)

The itch

hica is a statically typed, expression-oriented language. It compiles .hc source files through a Pratt parser and Hindley-Milner type checker, emits Koka .kk source, and lets Koka handle the rest.

I’ve wanted to design my own language for years. Every attempt fizzled out in the same place: the plumbing… Lexers, type systems, backends, memory management – the mountain of infrastructure you need before you can even think about syntax. It felt like building a house by first inventing concrete in a way…

But then it occurred to me, if I target Koka, I skip all those parts. Koka already has Perceus for memory, C/JS/WASM backends, a standard library, optimisation passes, and the effect runtime. I just need to build the front half: syntax, type checker, diagnostics, and an emitter that spits out .kk files. Koka handles the rest.

The constraint is that hica can only express what Koka can express, but given that hica’s design pillars (algebraic effects, Perceus memory, expression-oriented, strong inference) are exactly what Koka already provides, that costs almost nothing.

What it looks like

fun fizzbuzz(n) =>
  if n % 15 == 0 { "fizzbuzz" }
  else if n % 3 == 0 { "fizz" }
  else if n % 5 == 0 { "buzz" }
  else { "{n}" }

fun main() {
  for i in 1..100 {
    println(fizzbuzz(i))
  }
}

Everything is an expression: if, match, blocks all return values. No return keyword. "{n}" is string interpolation. The name stands for Hindley-milner Inference Compiler with Algebraic effects.

The pipeline is straightforward:

.hc source → Lex → Parse → Desugar → Type Check → Emit Koka (.kk) → Koka Compiler → C/JS/WASM

Each compiler phase uses algebraic effects for its state: diagnostics, type variables and symbol scopes are all effect-tracked. Compilers in Koka are surprisingly natural. The type checker runs Hindley-Milner unification and the emitter annotates the Koka output with the inferred types.

The tooling

I really enjoy building CLI tools, hica comes with hica run, hica build, hica check (which reports effects!), hica test, hica fmt, hica new, hica clean. The CLI is using my Clap inspired klap library, which handles flags, subcommands, and help generation.

I needed to test hica properly and have reused kunit to validate and verify its functionality, hundreds of tests across lexer, parser, checker, codegen, and CLI.

Built with help of a Genie

I used a Genie (what I call my GenAI model – thanks Kent Beck for the term) as a pair-programming partner throughout. I maintain the backlog and iterate until it’s right. It lets me focus on the design decisions; the Genie handles the mechanical parts. It’s been superfun, and a breath of fresh air compared to grinding through boilerplate alone.

Try it

The language is fun to use, and really usable with structs, enums, full pattern matching, modules, closures, UFCS, built-in testing.

I have tried to document along the way, and to be honest, I think I did a good job with it, take a look:

• Playground: try hica in the browser, no installation needed.
• Docs: language reference, quick start, and style guide.
• Source: Apache-2.0 licensed.

Thank you, Koka

hica wouldn’t exist without Koka. The effect system, Perceus, the C backend is all inherited. Huge thanks to everyone working on Koka for making it possible for someone like me to build a real language.

I stumbled onto Koka in my GitHub feed and it immediately got me hooked. This sentance alone is golden – “Koka is a strongly typed functional-style language with effect types and handlers that transpiles to C11”.

Right around then, I saw a LinkedIn post where someone had built a parallel ls in modern C++ and tagged John Cricket, which led me to his coding challenges.

If you really want to learn a language you should be hands-on and do exercises, John has listed several fun and challenging exercises but ls wasn’t on the list, so that was the one I picked 🙂

The Ambition

The goal: Rebuild GNU ls in Koka. 100% byte-for-byte compatible output.

That sounded like “a weekend project, maybe two” until I opened ls.c… The quick command I run hundred times a day is a 5,000-line beast of C, 83 CLI flags, and decades of accumulated edge cases. It’s a masterpiece of over-engineering, and it’s rock solid.

Getting Into the Guts

I’m working against the 9.10 codebase, and the architecture is a four-stage gauntlet: Setup → Parsing → Execution → Output.

The setup alone is a 1,000-line jungle of globals and structs. decode_switches(), the monster that parses options, is nearly 600 lines long!

I have created a couple of notes if people want to learn more about the internals and tips on how to use GNU ls (and my version of course):

• Decoded GNU ls – The architecture walkthrough.
• Column Layout – The math behind -C.
• Exit Codes – The three states of “oops.”
• Usage Guide – Practical tips for GNU ls.
• Recursive Listing – How -R traverses the tree.

The official docs and the man page are fine for users, but studying the source code is the only way to see how it really works.

The Roadmap

I drafted a plan of 6 phases + the infrastructure needed like a testing framwork and proper CI using GitHub Actions.

1. Phase 1 — Foundation
2. Phase 2 — Which files are listed
3. Phase 3 — What information is listed
4. Phase 4 — Sorting the output
5. Phase 5 — General output formatting
6. Phase 6 — Formatting the file names

To keep myself in check, I have built a test framework (kunit) that diffs my output against the original GNU binary. CI fails immediatly if I’m out of line…

Why Koka?

ls is actually a perfect stress test for Koka’s unique features:

• The Effect System: ls is a mix of pure logic (sorting/formatting) and messy side effects (disk I/O, stat() calls). Koka’s effects make that boundary visible in the types.
• Data Modelling: File types, sort modes, format styles, indicator kinds. The enums in ls.c map naturally to Koka’s algebraic types.
• Perceus: This is Koka’s secret weapon. It’s a reference-counting system that allows functional code to perform like C.
• The FFI: Koka’s standard library is still growing, so I’ve had to write C shims for things like symlink detection. The FFI (Foreign Function Interface) has been surprisingly painless and fun.

Learning in Public

I’ll be the first to admit: I’m a decent but not pro programmer and a total Koka novice. GNU ls is not “beginner friendly” territory. The C is dense and Koka’s documentation is still thin compared to other mainstream languages.

I’ve spent a lot of time “rubber-ducking” with a Genie to get through the nuts and bolts, figuring out why stat() and lstat() treat symlinks differently, or how -l is supposed to silently override -C.

This project doesn’t have a delivery-date. It’s just me, a 40-year-old C program, and a language that really got me hooked. It’s been a blast.

I’m not going to rebuild all of Coreutils, no way. ls is more than enough. But the process has triggered a different curiosity: I want to build a small language that transpiles to Koka. 🤓 Follow along at koka-labs.

In Trunk-Based Development, you sync with the remote constantly. That’s the whole point. tbdflow is running git fetch and git rebase --autostash under the hood and originally I had trust that uncommitted files would stay untouched but there are occasions when this assumption breaks. If a genie (or even you) runs a git pull then the work would be gone unless you do the git stash-pull-stash pop loop.

I’ve been building a feature I’m calling WIP Guard, a (semi-)continuous, invisible safety snapshots that give you a time machine for your working directory.

The three ways work gets lost

There are three scenarios that keep developers anxious in a high-frequency integration workflow:

1. The buried stash. A rebase fails. Git auto-stashed your changes, but the stash is now tangled in a half-applied rebase. Less experienced developers might panic and even experienced ones will lose minutes untangling it.

2. The accidental overwrite. A developer runs git stash pop or git pull manually after a failed tbdflow sync. The previous working state is gone.

3. The context gap. You wrote a breadcrumb with tbdflow + "trying trait-based approach" twenty minutes ago. But the code that inspired that thought? It only exists in your working directory, which has since moved on. The note is orphaned from the state it describes.

WIP Guard solves all three.

How it works: git stash create

The key insight is that Git already has a mechanism for creating immutable snapshots of your working directory: git stash create. Unlike a regular git stash, this command:

• Creates a commit object representing your index and working tree
• Does not add it to the stash reflog (so it can’t interfere with your manual stashes)
• Produces an immutable hash that stays in the Git object store until garbage collection (typically 14–30 days)

WIP Guard calls git stash create silently at strategic moments and stores the resulting hash in the Intent Log. It doesn’t introduce any new concepts, just using standard Git and much more manageable.

The four hooks

WIP Guard is “continuous” because it hooks into commands you’re already running. I didn’t want to add a new command, rather integrate it as helpful magic.

Hook A: The Intent Hook

Every time you record a breadcrumb with tbdflow +, the CLI now captures a snapshot alongside the note:

$ tbdflow + "factory pattern is too complex, switching to traits"
Note recorded: "factory pattern is too complex, switching to traits"
WIP snapshot: a7b8c9d0e1

That hash is stored inside the note object in .tbdflow-intent.json. The breadcrumb is a thought linked to the exact code that inspired it. You can go back to the code as it was at the moment of realisation.

Hook B: The Sync Hook

Before tbdflow sync initiates a rebase, it now does two things:

1. Anti-collision check. It verifies that .git/REBASE_HEAD, .git/MERGE_HEAD, and .git/CHERRY_PICK_HEAD don’t exist. If a git operation is already in progress, tbdflow halts and tells you to resolve it first. This alone prevents a whole class of “Git ghost” states.

2. Pre-sync snapshot. Regardless of whether you’ve added notes, tbdflow captures a safety snapshot and stores it as last_sync_snapshot in the intent log. If the rebase goes sideways, your pre-rebase state is one command away.

Hook C: The Radar Hook

tbdflow radar already scans for overlapping work on remote branches. Now it also silently captures a snapshot if your working directory is dirty and the last snapshot is more than 30 minutes old. This catches the case where a developer is heads-down coding and hours pass between syncs.

Hook D: The Undo Hook

This one is easy to overlook. tbdflow undo is the “panic button”. It checks out main, fast-forwards, and reverts a commit. That’s a destructive sequence for your working directory. If you had uncommitted changes on a feature branch when you hit the panic button, they’d be gone.

Now, tbdflow undo captures a snapshot and runs the same anti-collision check before doing anything. The panic button has its own safety catch.

The escape hatch: tbdflow recover

All of this snapshotting would be pointless without a clean recovery path. That’s tbdflow recover:

$ tbdflow recover --list
Available WIP snapshots:
  #     Type       Timestamp              Note                                     Hash
  ------------------------------------------------------------------------------------------
  1     intent     2026-04-18T14:15:00     trying trait-based approach              a7b8c9d0e1
  2     intent     2026-04-18T14:42:00     added error variants                     f2e3d4c5b6
  3     pre-sync   2026-04-18T15:01:00     Pre-sync safety snapshot                 e1f2g3h4i5

To restore:

$ tbdflow recover 1
Warning: This will apply the snapshot over your current working directory.
Snapshot applied successfully.
The snapshot remains available for future recovery.

Note that we use git stash apply, not git stash pop. The snapshot commit stays in the Git store. You can apply it again if needed. The snapshot is immutable which means you can’t accidentally destroy your safety net.

The lifecycle: what happens when you commit?

So what happens when you commit? If snapshots live in the Intent Log, and the Intent Log gets consumed by tbdflow commit, don’t the snapshots disappear?

Yes they do, and that’s by design. The commit is the lifecycle boundary. Once your work is committed and pushed to trunk, it’s in git history. The snapshots have served their purpose. When tbdflow clears the intent log after a successful push, it tells you:

Releasing 3 WIP snapshot(s) — your work is now in git history.
Intent log consumed and cleared.

The Git objects themselves aren’t deleted, they linger in the object store until garbage collection. But the references are gone, and that’s fine. Your work is safe in a commit now.

There’s an important subtlety here: this only happens on trunk commits. If you’re committing to a feature branch, the intent log (and all its snapshots) are preserved. The safety net stays up until your work reaches main.

The stale-branch guard

One important safety detail: if you switch branches and try to recover a snapshot from a different branch context, tbdflow warns you:

Stale intent log detected: notes were captured on 'feat/auth', but you are now on 'main'.

This prevents the subtle mistake of applying a snapshot from one feature’s context onto another feature’s working directory.

Why this matters for TBD adoption

The number one objection I hear when advocating for Trunk-Based Development is: “What if I lose my work?”

It’s a fair concern. In a branch-heavy workflow, your feature branch is your safety net. You can push half-finished work to a remote branch and it’s backed up. In TBD, your work-in-progress lives locally until it’s ready for trunk. That’s a trust gap.

WIP Guard closes that gap. Every breadcrumb you drop, every sync you run, every radar scan — they all leave behind an immutable snapshot of your working directory. Your work is preserved automatically, without you doing anything different from what you’d normally do.

The recovery path is one command, not a Stack Overflow deep-dive into git reflog and git fsck.

Try it

WIP Guard is available now. If you’re already using the Intent Log, you get snapshots for free — just keep using tbdflow + as you work. If something goes wrong, tbdflow recover --list shows you what’s available.

Give it a try: tbdflow on GitHub.

Throughput is a safety feature!

I’ve been exploring a new feature in tbdflow to bridge that gap: the Intent Log.

The goal is pretty simple (but ambitious). I want to capture the developer’s (or agent’s) reasoning while it’s fresh, without adding the documentation tax that usually kills these efforts.

Low friction breadcrumbs

For many of us, jotting things down is a vital mechanism for staying in flow. We need to leave breadcrumbs to maintain context as we navigate complex problems.

The problem I see isn’t the act of writing; it’s the friction of the “diary.” We don’t want to leave our environment to update a formal document or a separate ticket. We want to capture those internal realisations or “failed tries” directly in the stream of work.

To solve this, I’ve added two ways to log a breadcrumb during development:

tbdflow note <message>             # Log a note
tbdflow + <message>                # Shorthand alias

With +, the friction is close to zero. No shell escaping, no context switching, no separate file to manage. It also works directly without doing task start <description>.

The discipline

I’ve added breadcrumb instructions to both tbdflow SKILL.md and AGENTS.md, they are good instructions so same rules should apply whether you’re a human or an AI agent working in the repo:

• Drop a breadcrumb whenever you change approach or reject an alternative.
• Before a complex commit, there should be at least one or two breadcrumbs explaining major decisions.
• Do not wait until commit time — log as you go.

The point is that reasoning captured after the fact is reconstruction. Reasoning captured in the moment is evidence. The intent log only works if the habit is there.

The lifecycle of a thought

The Intent Log follows a strict lifecycle designed to keep the repository clean while enriching the history.

Capture: The first time you use a note command, tbdflow creates a local .tbdflow-intent.json. This file is automatically added to .gitignore so it never accidentally hits the trunk.

Tasks: For more structured work, you can use tbdflow task start "Refactor auth logic". This sets a high-level context that all subsequent notes are attached to.

Integrate: When you run tbdflow commit, the CLI reads your notes and injects them into the body of the commit message, positioned before any breaking change or TODO footers.

Cleanup: Once the commit is pushed to the trunk, the local JSON file is deleted. The reasoning is preserved in git history, but the workspace is reset.

Handling branch drift

One challenge with local logging is branch switching. If you start a task on a feature branch and switch to a hotfix, your notes shouldn’t follow you blindly.

tbdflow now tracks branch ownership in the intent log. If you try to add a note on a different branch than where you started, the CLI will warn you:

Stale intent log detected: notes were captured on 'feat/auth', but you are now on 'main'.

If you explicitly start a new task on the new branch, tbdflow will rebind the existing notes to the new context. The developer is always aware of which stream their thoughts belong to.

Why this helps with TBD adoption

Context for the auditor. In a Non-blocking Review, the code is already integrated. The auditor needs to know the intent to verify whether the implementation matches the goal. Seeing that a developer tried and rejected a pattern saves the auditor from suggesting the same thing. Hopefully it turns into a knowledge-sharing moment.

Agent transparency. When an AI agent is working, it can use the + shorthand to think out loud. The human developer can see the agent’s reasoning before the final commit is pushed. It turns the agent from a black box into a transparent colleague.

Fighting cognitive atrophy. By capturing these notes, the history of the struggle isn’t lost. Anyone picking up a task or reverting a change can see the decision-making process.

The result

The Intent Log captures metadata at the point of creation. It requires zero context-switching and provides value during the post-integration audit.

It makes for a more honest git history where the “why” is just as accessible as the “what.”

If you want to see how the Intent Log formats the final commit message, tbdflow includes a --dry-run flag that prints it before execution. You can read more about why I believe dry-runs are essential for workflow tools here.

Give it a try and let me know if the workflow fits you and your team: tbdflow on GitHub.

Throughput is a safety feature!

Then Koka came along…

Why Koka

It’s a research language from Microsoft Research. Functional, but not in the way that usually makes me bounce off after an afternoon.

The dot selection syntax was the first thing that felt right. Coming from Kotlin, I’m used to chaining: names.filter(is-hidden).sort(cmp).foreach(println). Koka lets me write like that. No inside-out nesting. Data flows left to right, which is how I think about it anyway.

But what really got me was the effect system. In most languages, a function signature tells you what goes in and what comes out. In Koka, it also tells you what the function does. A signature like fn(path) -> <fsys,exn> list<string> says: this touches the filesystem and might throw. It’s right there on the tin and not buried in documentation.

The compiler enforces it. There is no way to sneak in a side-effect, type systems are great like that. It’s “honest programming” in a way.

Porting ls

I don’t learn languages from tutorials. I need a real problem. So I started koka-labs, where I’m porting ls and wc from GNU Coreutils. First up: ls.

ls looks simple. List files, print strings. But a proper implementation touches a lot:

• Sorting I had to write an insertion sort to be able to reverse sort and get a feel of how Koka handles recursion.
• File metadata Hidden files, permissions, timestamps. This is where I’ll hit the boundary between pure logic and actual OS interaction, that will be fun when I get to more “advanced” listing.
• Perceus Koka’s reference counting system. This is what makes functional code run at speeds you wouldn’t expect from a language without manual memory management.

Working through it piece by piece, following the GNU philosophy, has been a good way to see how Koka keeps things clean while dealing with the mess of a real operating system.

I have even done some C to implement missing features in stdlib needed for ls -F. This was super-easy, I created a C file in the same directory with a couple of small functions and then it was just to import and wire it up.

// Import my C code
extern import
  c file "fs-inline.c"

// C FFI
extern is-symlink(p : string) : fsys bool
  c "kk_os_is_symlink"

What stands out so far

The effect system changes how I structure code. When side effects are visible in the types, separatng pure logic from IO becomes natural. The language makes that the easiest path.

Perceus is the other thing, functional languages have a reputation for being slow or memory-hungry. Koka’s approach to reference counting gives you immutability without the usual performance cost.

No rush

There’s no timeline on this, and no requirements. Just a compiler and a rabbit hole. I’ll keep porting tools and writing about what I find.

The repo is public if you want to follow along.