Coding Challenges

Coding Challenge #144 - Matrix Falling Text Generator

John Crickett — Sat, 31 Oct 2026 09:01:17 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #144 - Matrix Falling Text Generator

This challenge is to build your own falling text generator that simulates the falling green text from The Matrix. We’re calling it ccmatrix.

If you have seen the film, you will remember the moment the screen fills with streams of glowing characters raining down in the dark. ccmatrix brings that to your terminal. It is a small program, but it is a lot of fun to build, and it is a great way to learn how a terminal really works: how to draw anywhere on the screen, how colours are produced, how to read key presses without waiting for the Enter key, and how to react when the window changes size.

The best part is that you get to watch your work come alive as soon as it runs. It’ll look like this:

The Challenge - Building The Matrix Falling Text Generator

In this challenge you’re going to build a program that will take over the terminal, fill it with columns of random characters that fall at different speeds, and give the whole thing the glow of the film. It will also accept a handful of command line options, so you can change the speed, the colours and the characters it uses.

The core of this challenge is the same in any language, so pick whatever you are most interested in having fun with / learning.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your programming language. Most languages have libraries for drawing on the terminal and reading keys, or you can talk to the terminal directly using escape codes. Either approach is fine, though you will learn more by trying the second.

Step 1

In this step your goal is to switch the terminal into raw mode and draw a single falling character.

Put the terminal into raw mode, which lets you read key presses the moment they happen rather than waiting for the user to press Enter, and gives you full control over where things are drawn on the screen. Then draw a single character at the top of one column and move it down, one row at a time, with a short delay between each move.

The program should keep running until the user presses q. When it exits, it must restore the terminal to the state it was in before your program started, including the cursor, the colours and the contents of the screen as far as is practical.

Testing: Run your program with no options:

ccmatrix

You should see a single character appear at the top of the screen and fall, one row at a time, until it reaches the bottom. Press q and check that you are returned to a normal, usable prompt, with the cursor visible and typed characters echoed back. Try pressing other keys such as a or x and confirm that nothing happens and your program keeps running.

Step 2

In this step your goal is to draw the trail behind the falling character.

Rather than a single character moving down the screen, draw a trail behind it: the leading character bright white, followed by a green trail a few rows long, and behind the trail the column left blank so the characters appear to fall through the dark. As the head moves down, the trail should move with it.

Testing:

ccmatrix

You should see a bright white character with a green trail falling away behind it, down a single column. Compare the length of the trail and how it fades with the real cmatrix running in another window. Press q and confirm the terminal is still restored correctly.

Step 3

In this step your goal is to fill the screen with many falling trails.

Extend your single column so that every column on the screen has its own falling trail. Each should start at a random time and fall at its own speed, so the screen looks interesting and reflects the screenshot above, rather than uniform.

Testing:

ccmatrix

You should see the screen fill with falling green characters, each column with a bright white head. Press q and check that you are returned to a normal, usable prompt, with the cursor visible and typed characters echoed back. Try pressing other keys such as a or x and confirm that nothing happens and your program keeps running.

Step 4

In this step your goal is to add screensaver mode with the -s flag.

When -s is passed, your program should exit as soon as the user presses any key at all, not just q. If your system has a mouse include that too. As before, the terminal must be fully restored on exit.

Testing:

ccmatrix -s

Let the screen fill, then press the space bar. The program should exit straight away and leave you with a working prompt. Repeat the test with a few other keys, such as a letter, a digit, the Enter key and finally the mouse. Then run without -s and check that those same keys are ignored, so the difference between the two modes is clear.

Step 5

In this step your goal is to add control over the speed of the animation.

Support the -u flag, which sets the delay between updates as a number from 0 to 10. The default is 4, and 0 is the fastest. Your program should also let the user change the speed while it is running by pressing the keys 0 to 9, taking effect straight away without restarting the animation.

Think about what should happen when someone passes a value outside the range, or something that is not a number. A clear error message and a non-zero exit code is the right way to handle it.

Testing:

ccmatrix -u 0
ccmatrix -u 10
ccmatrix

The first run should be noticeably faster than the third (which uses the default of 4), and the second should be noticeably slower. While one of them is running, press 0, then 9, and watch the animation speed up and slow down. Finally check the error handling:

ccmatrix -u 11
ccmatrix -u fast

Both should report a problem and exit without drawing anything.

Step 6

In this step your goal is to add colour options.

Support the -C flag, which sets the colour of the trails. It should accept one of green (the default), red, blue, white, yellow, cyan, magenta or black. The bright leading character should stay white. Also support the -r flag, which displays the trails in rainbow colours instead.

Testing:

ccmatrix -C red
ccmatrix -C cyan
ccmatrix -r

The first two runs should show trails in the requested colours, with white heads. The third should show trails made up of several different colours. Also try an unknown colour:

ccmatrix -C purple

This should report the list of colours that are supported and exit.

Step 7

In this final step your goal is to add Japanese characters and handle resizing.

Support the -c flag, which draws half-width katakana characters instead of the default letters and numbers. This is the closest you will get to the look of the film, so it is a very satisfying one to see working.

Your program should also react when the terminal window is resized, either by making it larger or smaller. After a resize the display should redraw correctly to fill the new size, with no leftover fragments, no crashes and no columns drawn outside the window.

Testing:

ccmatrix -c

You should see katakana characters falling down the screen. If they appear as boxes or question marks, check that your terminal uses a font that supports them and that it is set to UTF-8. Combine it with other options to check they work together:

ccmatrix -c -C cyan -u 2

Then, while any of the above is running, drag the window larger and smaller. The animation should carry on and fill the new space each time. Do the same by changing the font size, or by using your window manager to maximise and restore the window.

Going Further

Once you have the core tool working, here are some ideas to take it further:

Add the b and B flags, which make some or all of the characters bold
Add the a flag for asynchronous scrolling, where columns move at different rates
Add a message mode, where the falling characters briefly resolve into a line of text of your choosing
Support a configuration file so a user can store their favourite options
Make the characters in the trail flicker and change as they fall, rather than staying fixed
Add support for true colour terminals, with smooth fades along each trail
Measure how much CPU your program uses, and see if you can make it lighter without changing how it looks
Make it into a full blown screensaver

Share Your Solutions!

If you think your solution is an example other developers can learn from please share it, put it on GitHub, GitLab or elsewhere. Then let me know via Bluesky or LinkedIn or just post about it there and tag me. Alternately please add a link to it in the Coding Challenges Shared Solutions Github repo

Request for Feedback

I’m writing these challenges to help you develop your skills as a software engineer based on how I’ve approached my own personal learning and development. What works for me, might not be the best way for you - so if you have suggestions for how I can make these challenges more useful to you and others, please get in touch and let me know. All feedback is greatly appreciated.

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #142 - Software KVM

John Crickett — Sat, 24 Oct 2026 08:00:50 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #142 - Software KVM

This challenge is to build your own software KVM switch, a simplified version of Barrier, the open source tool that lets you control several computers with a single keyboard and mouse.

If you’ve ever had two or three computers side by side on your desk, you’ll know the pain of swapping keyboards and mice between them, swapping you between different keyboards and mice, or reaching for a physical KVM switch.

Barrier solves this in software: move your cursor off the edge of one screen and it reappears on the next computer, carrying your keyboard and clipboard with it. No extra cables, no hardware box, just a small program running on each machine.

In this challenge you’ll build both halves of that system from scratch, speaking Barrier’s own open wire protocol, so that a real, unmodified Barrier client or server can interoperate with yours, and two instances of your own build can run the whole show on their own.

Fancy Winning A MacBook Neo or some Merch? Then Join Kesta’s Hacktober Event.

This October I’m pleased to be part of the Kestra Hacktober event. It’s a great way to contribute to open source this October and win some great prizes!

There are two ways to enter:

Fix an issue in their open-source codebase.

They’ve identified and scoped a number of issues across their core and plugin repositories. They’re tagged good-first-issue, so you can find one that interests you.

Build a blueprint, a ready-to-use flow template that other developers can pick up and run.

Whichever way you take part, there are prizes to be won!

🥇 1st place: 13” MacBook Neo

🥈 2nd place: Apple iPad

🥉 3rd place: $150 Amazon gift card

You need to register here to win prizes.

And you can find the full details on Kestra’s Hacktober page.

OK, on with the coding challenge!

The Challenge - Building Your Own Software KVM

You’re going to build a software KVM. It’s a client-server systems.

The server captures keyboard and mouse activity on your main machine, works out which connected screen should be in control as the cursor crosses screen edges, and forwards input, clipboard and status updates to the right client over the network.

The client connects to a server, and acts on everything it’s sent, moving the cursor, typing keystrokes, updating the clipboard, on the machine it’s running on. Because you’re implementing Barrier’s real protocol rather than inventing your own, you’ll be able to test your work against the genuine Barrier client and server at every stage, right up until the point where you don’t need them any more.

This is challenge combines binary network protocol work with low level, platform specific input handling, so pick a language with solid support for both TCP sockets and OS level mouse and keyboard capture.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your target platform and programming language, bearing in mind you’ll need a library for network programming, one for capturing global mouse and keyboard events on your own machine (not just events inside your own windows), and one for injecting simulated mouse and keyboard input, since you’ll eventually be building the client side too. Most mainstream languages have options for all three.

Download and install the real Barrier client on a second machine, you’ll use this throughout the challenge as the thing your server controls. Also consider installing a packet capture tool such as Wireshark or tcpdump, and spend some time capturing traffic between two genuine Barrier instances so you have a reference for what correctly formed messages look like.

Finally, read through Barrier’s own protocol header in its source code (src/lib/barrier/protocol_types.h in the debauchee/barrier repository) to familiarise yourself with the message codes you’ll be implementing.

Step 1

In this step your goal is to accept connections from Barrier clients and complete the initial handshake.

Your server should listen for TCP connections on port 24800, the default Barrier port. When a client connects, it should send a Hello message carrying the protocol’s major and minor version, and wait for the client to reply with a HelloBack message containing the client’s own version and the name it was configured with.

Testing: Point the Barrier client at your server’s address and port. Watch your server log the client’s reported name and protocol version once the handshake completes. If you installed Wireshark, capture the exchange in Wireshark and compare it against the reference capture you took in Step Zero.

Step 2

In this step your goal is to reject clients speaking an incompatible version of the protocol.

If the version a client reports in its HelloBack is one your server doesn’t support, your server should respond with an EICV (incompatible version) message and close the connection rather than proceeding.

Testing: Write a small script that opens a raw TCP connection to your server and sends a HelloBack with a deliberately wrong version number. Confirm your server sends EICV and disconnects. Then reconnect with the real Barrier client and confirm the normal handshake still succeeds.

Step 3

In this step your goal is to load a screen configuration describing the layout of connected screens.

Your server should read a configuration that names each client screen and defines its directional neighbours, left, right, top and bottom, relative to the other configured screens. This is the layout Barrier itself asks you to draw when you arrange screens in its own configuration tool.

Testing: Write a configuration with at least two screens, for example office-mac to the left of office-pc, and confirm your server parses it into a lookup you can query, such as “what is to the right of office-mac?”. Try a configuration that references a screen that doesn’t exist and confirm your server reports a clear error instead of crashing.

Step 4

In this step your goal is to exchange screen information with a connected client.

After the handshake, your server should receive a DINF message from the client reporting its screen size and current cursor position, and acknowledge it with a CIAK message.

Testing: Connect the real Barrier client and confirm your server logs the screen resolution it reports in its DINF message. Compare the CIAK your server sends against the one sent by a genuine Barrier server in your Wireshark reference capture if you did it.

Step 5

In this step your goal is to track which screen currently has control and where the cursor is on it.

Your server captures mouse movement on your own machine (the one with the physical keyboard and mouse attached), so it needs to keep its own model of which screen is “active” and the cursor’s current coordinates on that screen, updating it as the mouse moves.

Testing: Move your mouse around your screen and log the coordinates your server is tracking. Confirm the logged position matches where your cursor actually is, and that it stays within your screen’s bounds.

Step 6

In this step your goal is to detect when the cursor should hand off to another screen.

When the cursor reaches the edge of the active screen, your server should check the screen configuration from Step 3 for a neighbour in that direction. If one is configured, that’s a handoff; if there’s no neighbour configured on that edge, the cursor should simply stop at the edge as normal.

Testing: With a configuration that has a neighbour to the right but none above, move your cursor to the right edge and confirm your server detects a handoff. Move it to the top edge and confirm it doesn’t.

Step 7

In this step your goal is to actually switch control to the neighbouring screen.

When your server detects a handoff, it should send a CINN command to the client gaining control, including the coordinates where the cursor enters and a sequence number, and send a COUT command to the client that just lost control.

Testing: With the real Barrier client connected and configured as a neighbour, move your cursor to the matching screen edge and watch the cursor appear on the client machine. Move it back the other way and confirm control returns to your own screen.

Step 8

In this step your goal is to forward keyboard activity to the client currently in control.

Your server should forward key press and release events using DKDN and DKUP messages, carrying the key code and modifier mask, and forward repeated keystrokes from a held key using DKRP.

Testing: With the Barrier client in control, open a text editor on the client machine and type on your physical keyboard. Confirm the correct characters appear, including held keys like a repeated letter when you hold a key down, and that modifier combinations like Shift+A produce a capital letter.

Step 9

In this step your goal is to forward mouse button and wheel activity.

Your server should forward mouse button press and release events using DMDN and DMUP messages carrying the button id, and forward scroll wheel movement using DMWM.

Testing: With the Barrier client in control, click and scroll with your physical mouse. Confirm clicks register correctly on the client machine (for example, clicking a button in an open application) and that scrolling moves the content on the client’s screen.

Step 10

In this step your goal is to switch to relative mouse movement once control has entered a client screen.

Rather than repeatedly resending absolute coordinates, your server should send relative movement deltas using DMRM once the cursor has entered a client’s screen.

Testing: Capture the traffic between your server and the Barrier client while moving the mouse continuously across the client’s screen. Confirm the messages are DMRM, not repeated DMMV, and that cursor movement on the client stays smooth with no jumps or drift.

Step 11

In this step your goal is to keep connections alive and close them cleanly.

Your server should send a CALV keep-alive message to each connected client every 3 seconds, and disconnect any client that fails to respond within 9 seconds. It should also support a CNOP no-op message for simple connectivity checks, and send a CBYE message when deliberately closing a connection.

Testing: Leave a client connected and idle, and confirm in Wireshark that CALV messages go out roughly every 3 seconds. Simulate an unresponsive client (for example, by blocking its replies with a firewall rule) and confirm your server disconnects it after about 9 seconds. Stop your server normally and confirm the client receives a CBYE before the connection closes.

Step 12

In this step your goal is to synchronise the clipboard between screens.

When the clipboard changes on the screen currently in control, your server should send a CCLP ownership notification followed by a DCLP message carrying the clipboard contents to the other connected clients, and it should accept the same messages coming the other way when the clipboard changes on a client.

Testing: Copy some text on your own machine while a client is connected, then paste on the client machine and confirm the same text appears. Then copy something on the client machine and confirm it comes back to your own clipboard.

Step 13

In this step your goal is to notify clients when your screensaver starts or stops.

Your server should send a CSEC message to connected clients when the primary screen’s screensaver activates, and another when it deactivates.

Testing: Trigger your machine’s screensaver and confirm connected clients receive a CSEC message indicating the started state, followed by one indicating the stopped state when you dismiss it.

Step 14

In this step your goal is to support more than two screens at once.

Your screen configuration and switching logic from earlier steps should work for any number of connected screens arranged in a configurable grid, not just a single pair.

Testing: Configure three screens in an L shape, for example one to the right of your primary, and one below that one, connect three client instances, and confirm the cursor moves correctly between all of them as you’d expect from the layout, including that moving diagonally across two edges in sequence puts you on the right screen each time.

Step 15

In this step your goal is to confirm full interoperability with a real Barrier client.

Run an extended session using only the genuine, unmodified Barrier client as your test client; type, click, scroll, switch screens back and forth, and sync the clipboard, all without the client needing any changes or special configuration to work with your server.

Testing: Use your server as a daily driver for a short working session, controlling the Barrier client machine for ordinary tasks like browsing or editing a document. If everything behaves as it would with a genuine Barrier server, nice work!

Step 16

In this step your goal is to implement the client side of the protocol, so your own build can act as the screen being controlled, not just the one doing the controlling.

Your client should connect to a server, complete the handshake and the DINF/CIAK exchange, and then act on everything the server sends it: moving the cursor and injecting keystrokes on CINN/COUT and the DKDN/DKUP/DKRP/DMDN/DMUP/DMWM/DMRM messages, updating the local clipboard on CCLP/DCLP, responding to CALV and CNOP, and disconnecting cleanly on CBYE.

Testing: First connect your client to a Barrier server and confirm it behaves just like a genuine Barrier client, moving the cursor and typing correctly on your machine as the Barrier server hands it control.

Then run two instances of your own build, one as server and one as client, on two machines (or two user sessions on one machine), with no real Barrier software involved at all, and repeat the full set of tests from the earlier steps, screen switching, typing, clicking, scrolling, and clipboard sync, end to end between your own software only.

Going Further

Once you have the core software KVM working, here are some ideas to take it further:

Add TLS encryption to the connection, matching the SSL support in newer versions of the real protocol.
Support file drag and drop between screens using the DFTR message.
Add hotkey-triggered screen switching as an alternative to edge detection.
Handle screens with different resolutions or DPI scaling correctly when translating cursor coordinates.
Build a small configuration UI for drawing the screen layout, rather than hand editing a config file.
Add automatic reconnection when a client drops and comes back.
Package your server and client as a background service or system tray application.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #141 - Tail

John Crickett — Sat, 17 Oct 2026 08:00:56 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #141 - Tail

This challenge is to build your own version of tail, the classic Unix utility for looking at the end of a file and following a file as it grows.

If you’ve ever debugged a live system, you’ve almost certainly run tail -f on a log file to watch new entries appear in real time. It looks simple, but there’s some interesting systems programming going on: efficiently seeking to the end of huge files, detecting when a file has been truncated or rotated out from under you, and using the operating system’s own file notification mechanisms instead of just polling in a loop.

Building your own version is a great way to get comfortable with low-level file I/O and the quirks of how files actually behave on a live system.

Fancy Winning A MacBook Neo or some Merch?Then Join Kesta’s Hacktober Event.

This October I’m pleased to be part of the Kestra Hacktober event. It’s a great way to contribute to open source this October and win some great prizes!

There are two ways to enter:

Fix an issue in their open-source codebase.

They’ve identified and scoped a number of issues across their core and plugin repositories. They’re tagged good-first-issue, so you can find one that interests you.

Build a blueprint, a ready-to-use flow template that other developers can pick up and run.

Whichever way you take part, there are prizes to be won!

🥇 1st place: 13” MacBook Neo

🥈 2nd place: Apple iPad

🥉 3rd place: $150 Amazon gift card

You need to register here to win prizes.

And you can find the full details on Kestra’s Hacktober page.

OK, on with the coding challenge!

The Challenge - Building Your Own Tail

In this challenge you’re going to build your own version of tail. You’ll start with the basics, printing the last few lines or bytes of a file, then work your way up to a proper -f follow mode that can track a file being written to by another process, survive that file being truncated or rotated, and watch several files at once.

The core logic is the same in any language, so pick whatever you’re most comfortable with, though a language that gives you easy access to low-level file I/O and system calls will make the later steps noticeably smoother.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your target platform and programming language. Because this challenge leans on operating system specific features later on, kqueue on macOS and BSD, inotify on Linux, it’s worth checking early on what your language offers for file system event notifications, or whether you’ll need to reach for the underlying system calls directly.

Spend a little time with the system tail before you start. Run it on a few files, try -f on a log file while appending to it from another terminal, and read through man tail.

Create a small test file to use throughout the challenge:

seq 1 15 > test.log

This gives you a file with 15 lines, numbered 1 to 15, which makes it easy to check your output against what you’d expect.

Step 1

In this step your goal is to print the last 10 lines of a file, matching the default behaviour of tail.

Your tool should accept a single filename as an argument, read the file, and print only its final 10 lines. If the file has fewer than 10 lines, print all of them.

Testing:

cctail test.log

You should see lines 6 to 15. Try it against a file with fewer than 10 lines and confirm the whole file is printed.

Step 2

In this step your goal is to add the -n flag so the user can choose how many lines to display.

-n takes a number and your tool should print that many lines from the end of the file instead of the default 10.

Testing:

cctail -n 5 test.log

You should see lines 11 to 15. Try cctail -n 20 test.log, since there are only 15 lines in the file, the whole file should be printed.

Step 3

In this step your goal is to support the -n +NUM syntax.

Instead of counting backwards from the end of the file, -n +NUM counts forwards from the start, starting output at line NUM. So -n +5 means “start at line 5 and print to the end of the file”, rather than “print the last 5 lines”.

Testing:

cctail -n +5 test.log

You should see lines 5 to 15. Compare it with cctail -n 5 test.log from the previous step to make sure you haven’t mixed the two up.

Step 4

In this step your goal is to add the -c flag to output the last NUM bytes of a file instead of lines.

-c should work independently of n: when it’s given, your tool should seek to NUM bytes before the end of the file and print exactly that many bytes, with no regard for line boundaries.

Testing:

printf 'abcdefghij' > bytes.log
cctail -c 4 bytes.log

You should see ghij printed with no trailing newline. Compare your output against the system tail -c 4 bytes.log to confirm it matches exactly.

Step 5

In this step your goal is to make reading the last N lines or bytes efficient on large files.

If your current implementation reads the whole file into memory before working out what to print, it’ll fall over on large files. Rework it to seek from the end of the file and read backwards in chunks, stopping as soon as you’ve found enough lines (or bytes), rather than reading the entire file from the start.

Testing: Generate a large test file and confirm your tool still returns quickly and correctly:

seq 1 5000000 > bigfile.log
time cctail -n 10 bigfile.log

The command should return almost instantly and show lines 4999991 to 5000000, rather than taking noticeably longer the way a “read the whole file” approach would.

Step 6

In this step your goal is to support reading from standard input when no file is specified.

When your tool is run without a filename, it should read from stdin instead and apply the same last-N-lines or last-N-bytes logic to whatever it receives. Bear in mind that you can’t seek on a stream the way you can on a regular file, so this will need a different approach from the one you used in Step 5. Hint: think about ways of buffering data.

Testing:

cat test.log | cctail -n 5
seq 1 100 | cctail -n 3

Both should behave the same as if you’d passed the equivalent file as an argument.

Step 7

In this step your goal is to support multiple files as arguments, each displayed under its own header.

When more than one file is given, your tool should print a header line in the form ==> filename <== before each file’s output, in the order the files were given on the command line.

Testing:

seq 100 115 > test2.log
cctail test.log test2.log

You should see a ==> test.log <== header followed by its last 10 lines, then a ==> test2.log <== header followed by its last 10 lines.

Step 8

In this step your goal is to implement the -f (follow) flag.

After printing the initial lines, your tool should keep running and watch the file for new data being appended, printing each new line as it arrives, exactly as if another process were writing to that file. A straightforward way to start is to poll the file periodically and check whether it has grown.

Testing: In one terminal:

cctail -f test.log

In a second terminal:

echo "a new line" >> test.log

You should see a new line appear in the first terminal shortly after you run the second command. Stop your tool with Ctrl+C for now, we’ll make that exit cleanly in a later step.

Step 9

In this step your goal is to replace simple polling with OS-level file watching where it’s available.

Rather than waking up on a timer to check if the file has changed, use the operating system’s native file notification mechanism, inotify on Linux, kqueue on macOS and BSD, to be told immediately when the file is written to. Fall back to the polling approach from Step 8 on platforms or file systems where this isn’t available.

Testing:

cctail -f test.log

In another terminal, append a line and confirm it appears essentially instantly, noticeably faster than a one second polling interval would allow. If you can, add some temporary logging to confirm which code path (watch-based or polling) is actually being used.

Step 10

In this step your goal is to detect file truncation and recover from it.

If the file you’re following suddenly becomes shorter than it was, it has been truncated, likely by something like log rotation with copy-and-truncate, or a tool clearing a log file. When this happens, your tool should notice and restart reading from the beginning of the file, rather than trying to carry on from an offset that no longer makes sense (or erroring out).

Testing:

cctail -f test.log

In another terminal, truncate and refill the file:

> test.log
echo "fresh start" >> test.log

Your tool should detect the truncation and print fresh start rather than hanging or throwing an error.

Step 11

In this step your goal is to add the -F flag, which follows a file by name rather than by file handle, so it survives the file being rotated or replaced.

With plain -f, if a file is renamed and a new file is created in its place (the way logrotate typically works), your tool keeps following the old, now-renamed file and never sees the new one. With -F, it should detect that the original filename has been replaced by a new file and switch over to following that new file instead.

Testing: Run with the new flag:

cctail -F test.log

In another terminal, simulate rotation:

mv test.log test.log.old
echo "post-rotation line" >> test.log

Your tool should pick up post-rotation line from the newly created test.log. Repeat the same steps using -f instead of -F and confirm it does not pick up the new file, demonstrating the difference between the two flags.

Step 12

In this step your goal is to extend follow mode to support watching multiple files at once.

Your tool should be able to follow several files simultaneously, printing the ==> filename <== header (from Step 7) whenever output switches from one file to another, so it’s always clear which file a given line came from.

Testing:

cctail -f test.log test2.log

In another terminal, append to each file in turn:

echo "line for test.log" >> test.log
echo "line for test2.log" >> test2.log
echo "another line for test.log" >> test.log

Each append should appear under the correct file’s header, with a fresh header printed whenever the active file changes.

Step 13

In this step your goal is to add the -q flag to suppress filename headers.

When -q is passed, your tool should never print the ==> filename <== headers, even when following multiple files. This is handy for scripting, where you just want the raw output without knowing (or caring) which file each line came from.

Testing:

cctail -q -f test.log test2.log

Append to both files as in Step 12’s test and confirm no headers appear at all, just the interleaved output.

Step 14

In this step your goal is to make sure your tool exits cleanly and leaves the terminal in a sane state when interrupted.

Pressing Ctrl+C while following a file should cause your tool to shut down promptly: close any open file handles or watchers, and make sure the terminal behaves normally afterwards, with no leftover state from anything you changed while running.

Testing:

cctail -f test.log

Press Ctrl+C. Your tool should exit immediately with no hanging or stray output, and the shell prompt that follows should behave exactly as it did before you ran the command.

Going Further

Once you have the core tool working, here are some ideas to take it further:

Add colour to the filename headers or to lines matching particular patterns, to make it easier to scan output visually.
Add a -grep style flag that only shows lines matching a pattern, useful for following a busy log but only caring about certain messages.
Support following gzip-compressed log files, decompressing on the fly.
Add support for following remote files over SSH, similar to tools like mtail or multitail.
Add a -pid flag that stops following once a given process has exited, useful for following a log for exactly as long as the program writing it is running.
Build a split-pane terminal UI that follows several files side by side at once, rather than interleaving output into a single stream.
Benchmark your implementation against the system tail -f under heavy write load and see how the latency compares.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #140 - Bluetooth Proximity Finder

John Crickett — Sat, 10 Oct 2026 08:02:06 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #140 - Bluetooth Proximity Finder

This challenge is to build your own Bluetooth proximity locator, a command line tool that helps you find a nearby device by watching its signal strength climb as you get closer.

The idea comes from a true story a developer posted on X. They lost their phone at the office and spent half an hour turning the place over, only to remember that Find My had been switched off by the company’s device management software. Out of ideas, they asked Claude for help. Claude suggested tracking the phone’s Bluetooth signal strength instead, and wrote a simple signal meter for them. Then they walked around the office watching the number climb, and found the phone.

That is exactly what you are going to build in this challenge. Along the way you will learn how to scan for Bluetooth Low Energy devices. It is a great excuse to step outside the terminal and interact with real hardware.

I accidentally deleted the URL for the X post, if you know it please add it to the comments on SubStack. Thanks.

Fancy Winning A MacBook Neo or some Merch?Then Join Kesta’s Hacktober Event.

This October I’m pleased to be part of the Kestra Hacktober event. It’s a great way to contribute to open source this October and win some great prizes!

There are two ways to enter:

Fix an issue in their open-source codebase.

They’ve identified and scoped a number of issues across their core and plugin repositories. They’re tagged good-first-issue, so you can find one that interests you.

Build a blueprint, a ready-to-use flow template that other developers can pick up and run.

Whichever way you take part, there are prizes to be won!

🥇 1st place: 13” MacBook Neo

🥈 2nd place: Apple iPad

🥉 3rd place: $150 Amazon gift card

You can find out more and sign up on Kestra’s Hacktober page.

OK, on with the coding challenge!

The Challenge - Building Your Own Bluetooth Proximity Finder

You’re going to build a command line tool that scans for nearby Bluetooth Low Energy (BLE) devices, ranks them by signal strength, and helps you track a specific device down by turning its raw signal into “getting warmer, getting colder” style feedback.

The core ideas, scanning, smoothing noisy data, and turning a number into useful feedback, are the same in any language, so pick a language and BLE library you’re comfortable with. If you’ve mostly worked on the web or in application code, this is also a nice opportunity to get a taste of hardware-adjacent programming.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose a language with a BLE scanning library available for your operating system, for example Python’s bleak, Node’s @abandonware/noble, Go’s tinygo-org/bluetooth, or Swift’s CoreBluetooth on macOS. You’ll need a machine with a Bluetooth adapter, and at least one other BLE-advertising device nearby to scan for, your phone, a pair of wireless headphones, or a fitness tracker will all work.

Before writing any code, use your operating system’s built in Bluetooth scanning to confirm your adapter can see nearby devices and to get a feel for what a real scan result looks like, including the Received Signal Strength Indicator (RSSI) value reported in dBm. As a rough guide, a device held at arm’s length is often somewhere around -45 dBm, while a device in the same room but further away might read closer to -72 dBm. These numbers vary a lot by device and environment, so treat them as a rough guide rather than a rule.

Step 1

In this step your goal is to build a survey mode that continuously lists nearby BLE devices ranked by signal strength.

Your tool should scan for nearby BLE devices and print each one’s advertised name (or its address, if no name is broadcast), its address or identifier, and its RSSI in dBm. Rather than scanning once and exiting, refresh the displayed list on a fixed interval, a default of once a second is a sensible starting point.

Sort the list so the strongest signal, the closest device, always appears at the top. Remove a device from the list once it hasn’t been seen for a while, say 10 seconds, so devices that move out of range or power off disappear rather than lingering forever.

Testing: Run your tool in survey mode with a couple of BLE devices nearby (your phone, headphones, and so on). You should see a live-updating list with the strongest signal at the top. Walk a device further away and confirm it drops down the list, then out of range entirely and confirm it disappears after your timeout has passed.

Step 2

In this step your goal is to add a calibration mode that converts raw RSSI into human-readable proximity bands.

A raw dBm reading isn’t meaningful to most people at a glance. Add a calibration mode that prompts the user to hold a target device at arm’s length, and records the RSSI it sees as the “near” reference point. Use that reference, plus a documented default “far” reference (-72 dBm is a reasonable default), to map incoming RSSI readings to at least three bands, for example “very close”, “same room”, and “far”. Let the user override both reference points with command line flags, since the right values will vary by device and environment.

Testing: Run calibration while holding your test device at arm’s length, then run survey mode and confirm the device shows as “very close”. Walk it across the room and confirm the band changes to “same room” or “far” as appropriate. Try overriding the reference points with your flags and confirm the bands shift accordingly.

Step 3

In this step your goal is to add a hunt mode that tracks a single named device.

Add a hunt mode, invoked with a device name or address, for example --hunt "John's iPhone", that filters the live display down to just that one target instead of showing the full survey.

It should show the target’s current proximity band and raw RSSI, updating on every new reading, and it should clearly indicate when the target hasn’t been seen within your timeout window rather than silently freezing on stale data. If the named device is never seen at all within a configurable startup timeout (30 seconds is a sensible default), exit with a non-zero status and a clear error message rather than waiting forever.

Testing: Run hunt mode against a device you know is nearby and confirm it tracks that device specifically, ignoring any others in range. Turn the target device’s Bluetooth off (or walk it out of range) and confirm your tool reports that it has lost the target rather than showing frozen data. Run hunt mode against a name that doesn’t exist and confirm it exits with an error after your startup timeout.

Step 4

In this step your goal is to smooth out noisy readings so the displayed signal doesn’t jump around.

Raw RSSI readings are noisy, and some Bluetooth stacks will hand you back a cached value rather than a fresh measurement. Maintain a rolling window of recent readings per device, the last five is a reasonable starting point, and compute a smoothed RSSI using a simple moving average or exponential moving average rather than displaying the raw last-seen value directly.

Treat a new reading as a duplicate, and discard it, when its value exactly matches the previous reading for that device and arrives within a short debounce window (200ms is a reasonable default), since this usually means you’ve been handed a cached value rather than a genuinely new measurement.

Add a verbose mode that shows how many raw readings came in versus how many were counted as genuine changes, so you can actually see the debounce doing its job.

Testing: Run hunt mode in verbose mode and watch the raw versus counted reading totals. Confirm the displayed RSSI is noticeably smoother than the raw values you saw in Step 1. Leave a device stationary for a while and confirm the “counted” total grows much more slowly than the “raw” total, since a stationary device should be producing mostly repeated cached readings.

Step 5

In this step your goal is to add optional audio feedback that speeds up as you get closer to the target.

Add a --sound flag that plays a short click or beep each time a new reading is processed for the hunted device. Scale the interval between clicks to the smoothed RSSI, so clicks arrive slowly when the target is far away and rapidly, parking-sensor style, as you close in. Make sure the clicking stops automatically when hunt mode loses the target, rather than continuing to click away at the last known rate once the device is gone.

Bonus points if you use the motion detection sound from Aliens! 😎

Testing: Run hunt mode with --sound enabled and walk towards your target device. Confirm the clicks speed up as you get closer and slow down as you move away. Move the target out of range and confirm the sound stops rather than continuing at its last rate.

Step 6

In this step your goal is to estimate a rough distance in metres, and to be upfront about the limits of that estimate.

Using the log-distance path loss model, estimate an approximate distance in metres from the smoothed RSSI, taking your calibrated “near” reference and a configurable path-loss exponent as inputs. Display this estimated distance alongside a clear disclaimer that BLE RSSI-based distance is noisy and approximate, not a precise measurement, since walls, your own body, and interference all affect the reading. Also document, in your tool’s help output, that a single radio only gives you distance, not bearing, so your tool can tell you “warmer” but never “that way”.

Testing: Run hunt mode and compare the estimated distance against the actual physical distance to your target device at a few different points (right next to it, across the room, in another room). Confirm the numbers are in a sensible ballpark rather than being wildly off, and confirm the disclaimer and help text are visible.

Step 7

In this step your goal is to handle a missing or unauthorised Bluetooth adapter gracefully.

Detect when the host’s Bluetooth adapter is powered off, or when your process hasn’t been granted permission to use it, and print a clear, actionable error message rather than a stack trace or a silent hang. Also handle the case where there’s no BLE-capable adapter on the host at all, exiting cleanly with a descriptive error rather than crashing.

Testing: Turn off Bluetooth on your machine (or revoke your tool’s Bluetooth permission, if your OS supports that) and run your tool. Confirm you get a clear, readable error message rather than a crash or a hang. Turn Bluetooth back on and confirm your tool works normally again.

Going Further

Once you have the core tool working, here are some ideas to take it further:

Add classic Bluetooth (BR/EDR) scanning as a second signal source alongside your BLE scan.
Build a simple signal-strength bar chart or “big text” display for the terminal, so the proximity band is readable from across the room.
Log a session’s readings to a file and plot the signal strength over time afterwards.
Experiment with combining readings from two scanning stations (two laptops, say) to see how close you can get to estimating a rough direction, even though a single radio alone cannot.
Package your calibration reference points per device, so you don’t have to recalibrate every time you hunt for the same phone or headphones.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #139 - Code Context MCP Server

John Crickett — Sat, 03 Oct 2026 08:01:19 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #X139 - Code Context MCP Server

This challenge is to build your own code context server, a searchable, self-improving brain for your codebases that any AI coding tool can plug into.

If you use an AI coding assistant, you have probably noticed that it starts every session knowing nothing. It greps around, opens a few files, makes some guesses at how the project fits together, and then forgets all of it the moment you close or clear the session. Next task, it does the same work again to get the same context.

In this challenge you are going to build the missing layer. You will ingest a codebase, or a whole collection of them, into a database, chop it up at function and class boundaries, and turn it into something you can ask questions of in plain English. Then you will serve it over the Model Context Protocol, so Claude Code, Codex, Cursor, or any other MCP client is talking to the same brain.

Finally you will make it improve over time: it will write its own notes, remember what it has already worked out about your code, and learn from which answers actually got used.

This challenge was created in collaboration with Oracle, inspired by their blog post Build a Self-Improving Second Brain on Oracle AI Database.

The Challenge - Building Your Own Code Context MCP Server

You are going to build a tool that indexes codebases and serves them to AI clients over MCP.

Along the way you will get to play with semantic search, hybrid ranking, graph queries, and a few ideas from the world of AI agents that are genuinely useful and not just hype.

This Coding Challenge leverages Oracle AI Database 26ai because it supports generating embeddings inside the database, hybrid search that fuses keyword and semantic results, and graph queries over your code, all in the same database engine. That means your source code never leaves the database to be indexed, and you do not need an embedding API key. If you would rather use a different stack, it still works, but you will be assembling three or four separate pieces of infrastructure instead of one.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your programming language. You will need a decent database driver, a code parser, and an MCP server library, so pick something well served on all three counts. Python, TypeScript, Go, Java, and Rust are all great choices.

You will need a few things in place before you start:

A container runtime, so you can run the database locally. I use Docker.
A code parser. Tree-sitter has bindings for most languages and grammars for almost every language you would want to index, but anything that can tell you where functions and classes start and end will do.
An MCP client to test against. The MCP Inspector is the quickest way to poke at a server by hand, and Claude Code, Codex or Cursor will let you try it for real.

Spend a little time reading about the two ideas that are core to this challenge. The Model Context Protocol specification explains how tools are described and called. The Oracle AI Vector Search guide covers the VECTOR type, embeddings, and vector indexes.

Finally, grab some code to index. I would suggest cloning two real projects in different languages, so you exercise multi-repository and multi-language support from the start:

mkdir -p ~/ccctx-repos
git clone  ~/ccctx-repos/flask
git clone  ~/ccctx-repos/gin

Throughout this challenge I will call the tool ccctx, but name yours whatever you like.

Step 1

In this step your goal is to get the database running and create somewhere to put the code.

Start Oracle AI Database 26ai Free as a local container from container-registry.oracle.com/database/free:latest. It should listen on port 1521 and store its data on a mounted volume, so that your index survives a restart.

Then create your schema. You need somewhere to record repositories, files, and symbols. A symbol is a single indexed chunk of code, and for each one you will want to know which repository and file it came from, its path, its language, its name, what kind of thing it is (a function, a method, a class), and the line range it occupies, along with the source code itself.

Finally, give your tool a way to register a codebase. The user should be able to point it at a local directory, give it a short name, and later list everything that has been registered along with how many files and symbols each one holds.

Testing: Check the container is up and the database is ready:

docker ps
docker logs oracle26ai | tail -5

You are looking for DATABASE IS READY TO USE! in the logs. Connect with SQLcl, SQL*Plus, or your language’s driver and confirm your tables exist.

Then register both repositories and list them:

ccctx repo add ~/ccctx-repos/flask --name flask
ccctx repo add ~/ccctx-repos/gin --name gin
ccctx repo list

You should see something like:

NAME   PATH                       FILES  SYMBOLS
flask  /home/you/ccctx-repos/flask    0        0
gin    /home/you/ccctx-repos/gin      0        0

Both counts are zero, because we have not indexed anything yet. That is next.

Step 2

In this step your goal is to ingest a codebase and parse it into meaningful chunks.

Walk the working tree of a registered repository and decide what is worth indexing. Respect the repository’s .gitignore, and skip anything that will only add noise: binary files, and vendored dependency directories.

Rather than chopping files into arbitrary blocks of text, cut them at function, method, and class boundaries, so that every chunk is a complete, self-contained piece of code. Support at least three languages. Some files will not parse, either because you have no grammar for that language or because the code is broken, so fall back to 60 line windows with 10 lines of overlap rather than skipping them. The overlap is important, because it stops a chunk boundary from slicing a relevant section of code in half.

For every symbol you store, record the commit SHA the repository was sitting at when you indexed it. You are not using it yet, but in Step 5 it becomes the thing that makes re-ingestion cheap, and it means every chunk is traceable back to an exact revision of the code.

Round the step off by reporting what happened: how many files you scanned, how many you skipped and why, how many symbols you indexed, and how long it all took.

Testing:

ccctx ingest flask

You should output a summary along these lines:

Scanned   214 files
Skipped    38 files (12 ignored, 24 binary, 2 too large)
Indexed  1,847 symbols in 9.2s

Check the chunking is doing something sensible rather than just producing 60 line windows everywhere:

ccctx symbols --repo flask --limit 5

Each row should name a real function or class with a believable line range. Pick one and compare it against the file on disk to confirm the boundaries line up.

Now ingest the Go repository too, and confirm your language detection is working:

ccctx ingest gin
ccctx stats --by-language

You should see Python symbols from flask and Go symbols from gin, with a handful of fallback chunks for files neither grammar could parse.

Step 3

In this step your goal is to make the code searchable by meaning rather than by exact text.

Load an embedding model into the database itself. Oracle publishes a prebuilt ONNX version of all_MiniLM_L12_v2, which you can load with DBMS_VECTOR.LOAD_ONNX_MODEL and give a name like ALL_MINILM_L12_V2. Once it is loaded, the database can turn text into vectors on its own. No API key, no network call, and your source code never leaves the database to be indexed. For a lot of teams that last point is the difference between being allowed to build this and not.

Store the embeddings in a VECTOR(384, FLOAT32) column, and have the database populate it with VECTOR_EMBEDDING as rows are inserted, rather than computing vectors in your application and sending them over. Then build an HNSW index over that column so searches stay fast as the index grows. Use ORGANIZATION INMEMORY NEIGHBOR GRAPH DISTANCE COSINE WITH TARGET ACCURACY 95.

With that in place, add a search command. Given a question in plain English, it should return the 10 closest symbols by cosine distance. Throw away anything below a cosine similarity of 0.3, because a bad match is worse than no match at all when the results are going to be fed to a language model.

Testing: First confirm the model is loaded and working:

SELECT model_name FROM user_mining_models;

SELECT VECTOR_EMBEDDING(ALL_MINILM_L12_V2 USING ‘hello world’ as data) AS v;

The first should list ALL_MINILM_L12_V2, the second should return a 384 element vector.

Re-ingest so your symbols get embeddings, then try a question that shares no words with the code you expect back:

ccctx search “how are incoming requests routed to handlers”

You should get routing and dispatch code from both repositories, ranked by similarity, even though none of it contains the phrase you typed. That is the whole point: grep could not have found this.

Check your similarity floor is doing its job by searching for something completely unrelated to the indexed code:

ccctx search “recipe for sourdough bread”

You should get few results or none at all, rather than ten weak matches presented as if they were useful.

Step 4

In this step your goal is to combine semantic search with keyword search, so exact names win when exact names matter.

Semantic search is excellent at “where do we handle retries” and surprisingly bad at “show me url_for”. When you know the exact identifier you are after, you want plain old keyword matching. When you are describing a concept, you want vectors. Real code search needs both, which is why hybrid search is so useful.

Create a hybrid vector index over your symbol text, so lexical and semantic matching are served from one index rather than two. Query it with DBMS_HYBRID_VECTOR.SEARCH, using RRF as the search_scorer and UNION as the search_fusion mode. Reciprocal rank fusion is a neat trick: rather than trying to make two incompatible scores comparable, it throws the scores away and combines the rankings. A result that both methods rank highly rises to the top, and neither method can dominate the other.

Make sure that when someone searches for an identifier that exists in the code, the definition of that identifier comes back above its call sites. There are usually hundreds of call sites and exactly one definition, and the definition is almost always what the reader wanted.

Finally, now that you have more than one repository indexed, let the user choose. Search everything by default, and provide a flag to narrow a search to one or more named repositories.

Testing: Search for an exact identifier and check what comes first:

ccctx search “url_for”

The definition of url_for should be the top result, not one of the many places it gets called.

Compare the three modes on the same query to see the fusion working:

ccctx search “url_for” --mode vector
ccctx search “url_for” --mode text
ccctx search “url_for” --mode hybrid

Vector mode will return things that are conceptually about URL building. Text mode will return everything containing the string. Hybrid should look better than either.

Then check repository scoping:

ccctx search “middleware chain” --repo gin

Every result should come from gin, with nothing from flask.

Step 5

In this step your goal is to make re-indexing cheap, so you can keep the brain current.

Right now every ingest starts from scratch on a large repository that is slow enough that you will stop doing it. And a stale index is worse than no index because you cannot tell when to trust it. The fix is to only do the work that the changes require.

Record the commit SHA of each repository the last time you indexed it. If someone asks you to re-ingest while the working tree is still at that revision, say so and do nothing, unless they insist.

When there are changes, work out what they are by comparing the working tree against the last indexed commit, and only re-parse and re-embed the files that were added, changed, or renamed. Everything else is already correct and does not need touching.

Deletions need care. When a file is removed or renamed, its old symbols and embeddings have to go too. Orphaned chunks are poison in a search index, because they point at code that is not there anymore and there is nothing in the results to tell the reader that.

Lastly, give the user an escape hatch: a full rebuild that throws away a repository’s index and starts over. You will want it the first time you change your chunking rules.

Testing: Re-ingest with nothing changed:

ccctx ingest flask

It should tell you the repository is already up-to-date and do no work.

Now make a change and try again:

cd ~/ccctx-repos/flask
git checkout HEAD~20
cd -
ccctx ingest flask

The summary should report a handful of changed files rather than the whole repository, and it should be noticeably faster than the first ingest was.

Test deletion handling by removing a file, re-ingesting, and confirming its symbols have gone:

rm ~/ccctx-repos/flask/src/flask/json/tag.py
ccctx ingest flask
ccctx search “json tag serialisation” --repo flask

No result should point at the deleted file. Restore it with git checkout afterwards.

Finally check the full rebuild:

ccctx ingest flask --full

This should re-index everything, with counts matching your original ingest.

Step 6

In this step your goal is to turn the relationships between bits of code into something you can query.

Searching finds code that looks like what you asked for. It cannot tell you what will break if you change a function. For that you need the structure of the code, not just its text.

While you are ingesting, extract the relationships you can see: which files import which other files, which symbols call which other symbols, and which file defines which symbol. You will not catch everything, especially anything dynamic, and that is fine. A graph that captures most direct calls is enormously useful even when it is incomplete.

Expose those relationships as a SQL property graph with CREATE PROPERTY GRAPH, built over the tables you already have, with files and symbols as vertex tables and imports, calls, and defines as edge tables. You are not copying the data into a separate graph database, you are putting a graph-shaped view over the rows you already stored.

Then answer the two questions every developer asks before changing anything. “What calls this?” and “What does this call?” using a GRAPH_TABLE query with a MATCH pattern. Once those work, go further and compute a blast radius: follow the call edges out to a depth of 3 hops and report every symbol that could be affected, along with how many hops away it is. Distance matters, because a direct caller is a very different risk from something three steps downstream.

Testing: Pick a function with a decent number of callers and look both ways:

ccctx callers url_for
ccctx calls url_for

Cross-check the results against grep -rn “url_for” ~/ccctx-repos/flask. Your graph should find the real call sites, and unlike grep, it should not be confused by the string appearing in a comment or a docstring.

Now try the blast radius:

ccctx impact url_for --depth 3

You should get a list of affected symbols with a hop count, and there should be more results at 3 hops than at 1:

ccctx impact url_for --depth 1 | wc -l
ccctx impact url_for --depth 3 | wc -l

Step 7

In this step your goal is to hand all of this to an AI client over MCP.

Everything so far has been for you at a terminal. Now make it available to the tools you actually code with. Expose the brain as an MCP server over standard input and output. There is no network listener and no authentication to worry about, because the client starts your server as a child process and talks to it over standard io.

Provide four tools, described well enough that a model can work out when to reach for each one. Tool descriptions are effectively prompts, so it is worth spending time on them.

A search_code tool that takes a query, optional repository and language filters, and a result count that defaults to 10. It should return the file path, symbol name, line range, and a snippet for each hit.
A get_symbol tool that returns the full source of a named symbol, along with its file path and line range, for when the snippet is not enough.
A find_callers tool and an impact_of tool, both backed by the property graph you built in Step 6, so a client can trace call sites and work out the consequences of a change without opening a single file.

Testing: Start with the MCP Inspector, which lets you call tools by hand:

npx @modelcontextprotocol/inspector ccctx mcp

Confirm all four tools appear with their descriptions and parameters, then call search_code with {”query”: “how are requests routed”, “repo”: “flask”} and check you get the same results your CLI gives.

Then wire it into a real client and use it for some real coding:

claude mcp add ccctx -- ccctx mcp

Start a session in an unrelated directory, so the client has no filesystem access to the code and has to use your server, and ask it something like “using ccctx, how does Flask decide which view function handles a request?”. Watch which tools it chooses. If it reaches for the wrong one, your descriptions need work, and that is a genuinely useful thing to learn.

Step 8

In this step your goal is to have your tool write and maintain its own architecture notes.

Search answers narrow questions well. It is much weaker at “what does this module actually do,” because that answer is not written down in any single chunk. So have your tool write it down.

Generate a wiki page for each module or directory once it holds at least 10 indexed symbols. A page should cover what the module is for, its key symbols, and which other modules it depends on. You already have everything needed to work that out: the symbols, and the import edges from Step 6.

Store each page’s citations as rows pointing at real file and symbol records, not as text in the prose. This is the part that makes the wiki trustworthy. A citation that is just a sentence saying “see app.py line 40” starts rotting the moment someone edits that file, and nothing tells you. A citation that is a foreign key cannot point at something that is not there.

That also gives you staleness for free. When the commit SHA of a symbol a page cites changes, mark that page stale, and recompile stale pages on the next re-ingestion. A wiki that quietly goes out of date is worse than no wiki, because people keep believing it.

Then make the pages useful: expose a read_wiki MCP tool, and include wiki pages in your hybrid search results alongside code symbols, so a question about a whole module can be answered by the page rather than by ten disconnected functions.

Testing: Build the wiki and read a page:

ccctx wiki build --repo flask
ccctx wiki list --repo flask
ccctx wiki show flask/json

The page should describe what the module does and name real symbols from it. Check the citations are stored as references rather than prose:

ccctx wiki citations flask/json

Every citation should resolve to a symbol that exists. Now test staleness by changing a cited function:

cd ~/ccctx-repos/flask
# edit a function that the flask/json page cites, then commit it
git commit -am “tweak”
cd -
ccctx ingest flask
ccctx wiki list --repo flask

The flask/json page should be marked stale and then recompiled. Finally, confirm pages show up in search:

ccctx search “what does the json module do”

A wiki page should rank above the individual functions.

Step 9

In this step your goal is to give your server a memory, so it stops working the same things out over and over. You can draw on the ideas for AI Agent Memory and if you’re working in Python, leverage Oracle’s AI Agent Memory Python package for this step.

Every time a client calls one of your tools, record it: the question, which tool was used, what came back, and when. This is your episodic memory, a raw log of everything that has happened. On its own it is not much use, because by next week there will be thousands of rows and no way to find anything in them.

So distil it. Turn those raw runs into durable facts about the codebase, each with a subject, the fact itself, a confidence score, and the run IDs it came from so you can always trace it back. Merge duplicates as you go rather than accumulating fifty near-identical variations of the same observation. Run this on demand, and automatically after each re-ingestion, so the memory keeps pace with the code.

Then expose it. A recall tool should return the relevant facts and recent runs for a repository, so an agent opens a session already knowing what has been worked out before. This is the loop that makes the whole thing self-improving: the server answers a question, records what it found, distils it into a fact, and hands that fact back the next time someone asks something similar.

Testing: Ask your server several related questions through the MCP Inspector or a real client, then look at what it remembered:

ccctx memory list --repo flask --limit 10

You should see one row per tool call. Now distil them:

ccctx memory consolidate --repo flask
ccctx memory facts --repo flask

You should get a much shorter list of facts than you had runs, each traceable to the runs it came from. Ask two near-identical questions, consolidate again, and confirm you get one merged fact rather than two.

Then check recall works end-to-end. Start a fresh client session and ask “what do you already know about this codebase?”. The client should call recall and come back with the facts, without searching for them.

Step 10

In this step your goal is to let your server learn from which results actually turned out to be useful.

Start recording when a client uses a result by citing it in an answer or opening it. Mark it as used, so you can tell the difference between a result you returned and a result that helped.

Then feed that back into ranking carefully. Boost frequently used symbols on future searches, but cap the boost at 20 percent. Feedback loops in search have a nasty habit of eating themselves: popular results get boosted, so they get shown more, so they get used more, so they get boosted further, until your search only ever returns the same five things. A bounded boost nudges the ordering without ever overruling relevance.

Add decay for the same reason. Halve the weight of feedback every 30 days, so what the tool learned during last quarter’s refactor fades out instead of haunting your searches forever.

Testing: Build your gold set as a simple file of questions and expected paths, then take a baseline:

ccctx eval --gold gold.json

Questions: 20
recall@10: 0.65 (13/20)

Now generate feedback by running sessions and marking useful results, then measure again:

ccctx eval --gold gold.json --with-feedback

Recall should improve, or at least hold steady. If it drops, your boost is too strong and is pushing correct answers out of the top 10, which is exactly the failure this step is designed to let you catch.

Check the cap is real by hammering a single symbol with feedback and confirming it does not take over:

ccctx search “database connection pooling”

A heavily used but irrelevant symbol should still not appear for an unrelated query.

Test decay by backdating some feedback and confirming its influence has halved:

ccctx feedback list --repo flask

Going Further

Once you have the core server working, here are some ideas to take it further:

Index git history as searchable content: commit messages, diffs, and blame. It lets the brain answer “why is this code like this” and not just “what does it do,” which is often the question you actually have.
Add an MCP tool that answers “who should review this change” by combining the blast radius from Step 6 with blame data.
Extend staleness detection from wiki pages to semantic facts, so the memory knows when what it believes about the code has been invalidated by a commit.
Expose the whole thing over HTTP instead of stdio, with OAuth, an email allowlist, and a read-only flag that disables any tool that writes. That is what you need before a team can share one brain.
Move the database to an Always Free Autonomous AI Database instance in the cloud, so your index is available from any machine.
Add JSON Relational Duality views over your content tables, so the same rows can be read as clean JSON documents by your application and as normalised relational data by your SQL.
Support incremental indexing triggered by a git hook or a file watcher, so the index updates as you work rather than when you remember to run it.
Let the server suggest where new code should live by finding the module whose wiki page best matches a description of what you are about to build.
Benchmark your retrieval against a plain grep and against your editor’s built-in search on the same gold set, and see where each one wins.

Share Your Solutions!

Request for Feedback

I’m writing these challenges to help you develop your skills as a software engineer based on how I’ve approached my own personal learning and development. What works for me might not be the best way for you - so if you have suggestions for how I can make these challenges more useful to you and others, please get in touch and let me know. All feedback is greatly appreciated.

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #138 - DMB

John Crickett — Sat, 26 Sep 2026 08:01:34 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #139 - DBM

This challenge is to build your own version of DBM, the classic Unix key-value database library.

DBM has been around since the earliest days of Unix. It was written by Ken Thompson and released by AT&T in 1979. The name stands for Database Manager, and along with its descendants (ndbm, gdbm, Berkeley DB) it has been quietly powering everything from mail servers to Apache web server modules for decades.

DBM was one of the first NoSQL systems, a key-value store that let you fetch data by a single key, long before NoSQL became popular. Showing once again that everything that’s new, is old.

DBM stores key-value pairs on disk using a clever trick called extendible hashing. Instead of a fixed-size hash table that you have to rebuild when it fills up, extendible hashing grows gracefully as you add keys. It splits buckets when they overflow maps hash values to buckets. The result is fast single-key lookups that only need a couple of disk reads, no matter how large your database grows.

Fancy Winning A MacBook Neo or some Merch?Then Join Kesta’s Hacktober Event.

This October I’m pleased to be part of the Kestra Hacktober event. It’s a great way to contribute to open source this October and win some great prizes!

There are two ways to enter:

Fix an issue in their open-source codebase.

They’ve identified and scoped a number of issues across their core and plugin repositories. They’re tagged good-first-issue, so you can find one that interests you.

Build a blueprint, a ready-to-use flow template that other developers can pick up and run.

Whichever way you take part, there are prizes to be won!

🥇 1st place: 13” MacBook Neo

🥈 2nd place: Apple iPad

🥉 3rd place: $150 Amazon gift card

You can find out more and sign up on Kestra’s Hacktober page.

OK, on with the coding challenge!

The Challenge - Building Your Own DBM

In this challenge you’re going to build your own version of DBM. You’ll start with a simple key-value store in memory, work through extendible hashing, then move the whole thing to disk. By the end you’ll have a working on-disk hash table database with its own command-line tool.

Step Zero

In this introductory step your goal is to set your environment up ready to begin developing and testing your solution.

Choose your target platform and programming language. DBM involves low-level disk I/O and binary data handling, so pick a language you’re comfortable with for reading and writing binary files. C, Go, Rust, Python, and Java all work well here. If you’re looking to learn something new, Go’s standard library has excellent support for binary encoding and file I/O or C will give you the most authentic “building a Unix tool” experience. Rust gives you the “rewrite in rust” modern vibe.

Before you start coding, spend a few minutes playing with a real DBM implementation to get a feel for how it works:

# Install GNU dbm if you don't have it

# Create a database and add some keys
echo 'store greeting "Hello, world!"' | gdbmtool test.db
echo 'store name Alice' | gdbmtool test.db
echo 'store language English' | gdbmtool test.db

# Fetch keys back
echo 'fetch greeting' | gdbmtool test.db
echo 'fetch name' | gdbmtool test.db

# List every key with its value
echo 'list' | gdbmtool test.db

# Delete a key
echo 'delete language' | gdbmtool test.db

# Try to fetch a deleted key
echo 'fetch language' | gdbmtool test.db

Notice how the store operation inserts or updates a key, fetch retrieves it, and delete removes it. The list command iterates over all keys in the database. These are the core operations you’ll be implementing.

Step 1

In this step your goal is to build a simple in-memory key-value store, a hash table that supports put, get, and delete operations.

Think of it as building a dictionary or map, but one that you’ll later move to disk. For now, keep it simple: your hash table should take arbitrary byte sequences as keys and values, use a hash function to determine where each key lives, and handle collisions somehow (chaining or open addressing are both fine).

You don’t need to worry about persistence yet, keep everything in memory. The goal is to get a working hash table that can store, retrieve, and delete key-value pairs.

Testing: Write a small test program that exercises your hash table.

Step 2

In this step your goal is to replace your simple hash table with the extendible hashing that powers DBM.

Fixed-size hash tables are fine for small in-memory stores, but they don’t scale. On disk, if you allocate 10,000 buckets upfront and only store 100 keys, you’re wasting disk space. If you start with 10 buckets and later need to store 100,000 keys, you’d have to rebuild the entire table. Extendible hashing solves this by growing the database on demand.

Here’s how it works. You have the directory, which is an array of pointers to buckets. Each bucket has a fixed capacity and a local depth. The directory has a global depth. You use the most significant bits of the hash value to index into the directory, which tells you which bucket to use.

When a bucket fills up, you split it: the bucket’s local depth increases by one, and you redistribute its entries between the original bucket and a new one based on the next bit of the hash. If the bucket’s local depth was already equal to the global depth, you double the directory size and increment the global depth first.

The result: as you add keys, the directory grows and buckets split, but you never need to rehash everything. Each lookup requires reading one bucket from disk (plus following the directory), which is typically just one or two disk reads.

You can read more about extended hashing here.

Testing: Write a test that inserts enough keys to trigger at least three bucket splits. Then verify you can retrieve every key you inserted. Print out the directory state (global depth, directory size, bucket count) at each split to help debug:

Inserting key 1:  global depth=1, buckets=2, directory size=2
Inserting key 2:  global depth=1, buckets=2, directory size=2
Inserting key 3:  global depth=1, buckets=3, directory size=2
Inserting key 4:  global depth=2, buckets=4, directory size=4

Retrieve every key and confirm the values are correct. Delete a few keys and verify they’re gone. Insert new keys into the freed space and confirm they end up in the right buckets.

Step 3

In this step your goal is to persist your database to disk.

You’ll need to design an on-disk format. The original DBM used two files: a .dir file for the directory and a .pag file for the bucket data. GDBM and Berkeley DB use a single file. Either approach works. Pick whichever feels simpler to you.

Each bucket on disk should contain a header with the bucket’s local depth, a count of entries, and space for the key-value pairs themselves. Since keys and values can vary in length, you’ll need a way to encode where each record starts and how long it is within the bucket.

When a bucket overflows and can’t fit another entry - even after splitting - you’ll need overflow buckets.

Make your put, get, and delete operations read from and write to disk rather than memory. Think about when to flush writes: flushing after every operation guarantees durability but is slow; buffering writes is faster but risks losing data on a crash. Start with flushing after every mutation for correctness, then consider adding an option to buffer later.

Testing: Create a new database, insert several keys, then reopen it and verify all keys are still there:

# First run: create and populate
ccdbm create test.db
ccdbm put test.db key1 "value one"
ccdbm put test.db key2 "value two"

# Second run: reopen and verify
ccdbm get test.db key1     # should print "value one"
ccdbm get test.db key2     # should print "value two"

Delete a key, close and reopen, and confirm the deleted key is truly gone. Insert enough keys to trigger overflow buckets, then verify retrieval still works correctly. Use a hex dump tool (xxd or hexdump) to inspect your database file and confirm the on-disk format matches what you expect.

Step 4

In this step your goal is to support iterating over all keys in the database with firstkey and nextkey operations.

Hash tables are great for single-key lookups but not naturally suited for iteration. DBM solves this by providing firstkey() to get the first key in the database (whatever that means for a hash table) and nextkey(key) to get the next key after a given one.

The simplest approach is to walk through the directory entries and then through each bucket’s records in order. Since the directory is indexed by hash bits, the iteration order will seem random, that’s expected for a hash-based store.

You should also think about what happens when keys are deleted during iteration. In the original DBM, deleted records were simply marked as empty slots within their bucket. Your iteration should skip over these deleted slots.

Testing: Populate a database with several keys, then iterate over all of them and confirm every key you inserted is returned exactly once:

ccdbm put test.db apple "red"
ccdbm put test.db banana "yellow"
ccdbm put test.db cherry "red"

ccdbm list test.db
# Should print: apple, banana, cherry (order may vary)

Delete a key, then iterate again and confirm the deleted key no longer appears. Insert new keys into the empty slots and confirm iteration picks them up.

Step 5

In this step your goal is to implement a reorganise (compact) operation.

Over time, as keys are inserted and deleted, your database accumulates waste: deleted records leave empty slots in buckets. A reorganise operation rebuilds the entire database from scratch, rehashing every key into fresh buckets and reclaiming the wasted space.

The process is straightforward: iterate over every key-value pair in the old database, insert them all into a new empty database, then replace the old files with the new ones. After reorganising, there should be no empty slots and no overflow buckets (assuming your bucket size and hash function distribute keys well).

Testing:

# Insert and delete some keys to create fragmentation
ccdbm put test.db a "1"
ccdbm put test.db b "2"
ccdbm put test.db c "3"
ccdbm delete test.db a
ccdbm delete test.db c

# Show stats before reorganise
ccdbm stats test.db

# Reorganise
ccdbm reorganise test.db

# Show stats after
ccdbm stats test.db

Verify the database file is smaller after reorganising. Confirm all remaining keys are still retrievable after the operation.

Step 6

In this step your goal is to build a command-line interface for your DBM. You’ve been using it piecemeal for testing - now wrap everything in a clean CLI tool called ccdbm.

Your CLI should support these commands:

ccdbm create - create a new empty database file
ccdbm put - insert or update a key-value pair
ccdbm get - retrieve the value for a key
ccdbm delete - delete a key
ccdbm list - list all keys in the database
ccdbm stats - show database statistics
ccdbm reorganise - compact the database

The stats command should display useful information: the number of buckets, global depth, total key count, file size on disk, and number of overflow buckets. This gives the user insight into how their database is performing and whether it might benefit from a reorganise.

Testing: Run through a complete workflow with your CLI:

# Create
ccdbm create demo.db

# Populate
ccdbm put demo.db title "The Lord of the Rings"
ccdbm put demo.db author "J.R.R. Tolkien"
ccdbm put demo.db year "1954"

# Retrieve
ccdbm get demo.db title    # The Lord of the Rings
ccdbm get demo.db author   # J.R.R. Tolkien

# List all keys
ccdbm list demo.db         # title, author, year

# Check stats
ccdbm stats demo.db

# Delete one
ccdbm delete demo.db year

# Verify deletion
ccdbm get demo.db year     # Error: key not found

# Reorganise
ccdbm reorganise demo.db

# Verify data still intact
ccdbm get demo.db title    # The Lord of the Rings

Try with a larger dataset - insert a few thousand keys and verify both retrieval and iteration work correctly. Measure how long a lookup takes and how long a reorganise takes as the database grows.

Going Further

Here are some ideas to take your implementation further:

Support storing arbitrary binary data by accepting key and value inputs as hex strings (e.g., ccdbm put test.db hexkey deadbeef)
Add a batch mode that reads commands from a file or stdin, processing multiple operations in a single session
Benchmark your DBM against GNU dbm or Berkeley DB on the same dataset and see how your performance compares
Try different hash functions (djb2, FNV-1a, MurmurHash3) and measure how evenly they distribute keys across buckets
Add support for key expiry with a time-to-live (TTL), where keys are automatically removed after a configurable duration

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #137 - fzf

John Crickett — Sat, 19 Sep 2026 08:01:18 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #137 - fzf

This challenge is to build your own version of fzf, the command-line fuzzy finder.

fzf is one of those tools that changes how you use a terminal. You pipe a list of things into it, start typing a few letters, and it narrows a list of a million items down to the one you wanted before you have finished typing. It is used for finding files, checking out git branches, searching shell history, killing processes, and about a hundred other things.

Underneath the friendly interface there is a surprising amount of interesting engineering: a scoring algorithm that ranks matches the way a human would, a terminal user interface built from raw escape sequences, and a design that is responsive while a huge stream of input. Building your own fzf is a great way to learn all three.

The Challenge - Building Your Own fzf

In this challenge you’re going to build your own fuzzy finder. It will read a list of items, take over the terminal, and let the user type a query that filters and re-ranks the list on every keystroke. By the end you’ll have a tool you can drop into your own shell aliases and scripts in place of the real fzf.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your target platform and programming language. You’ll be reading key presses one at a time and drawing directly to the terminal, so look for a language that lets you put the terminal into raw mode and write escape sequences, either from its standard library or from a small terminal library. Avoid anything that hides the terminal from you completely.

Before you write any code, spend time with the real thing. Install fzf if you don’t already have it, then read the fzf man page and the project README. Pipe some things into it and watch how it behaves as you type:

find . -type f | fzf
git ls-files | fzf
history | fzf

Pay attention to the small details, like what happens to the screen when you quit, what the counter above the prompt shows, and which items float to the top when you type a few letters.

You’ll also want some test data. A big list of lines is ideal, so grab a word list and generate a large file of paths to use throughout the challenge:

wc -l /usr/share/dict/words
find / -type f 2>/dev/null | head -1000000 > /tmp/paths.txt
wc -l /tmp/paths.txt

Keep both files handy, you’ll use the small one for correctness and the large one for performance.

Step 1

In this step your goal is to build the skeleton of the finder: read items, show them, and let the user pick one.

Your tool should read newline-delimited items from standard input and display them in an interactive full-screen list, with a prompt where the user’s query will eventually go. Pressing Enter should accept the item the cursor is on and print it to standard output. Pressing Ctrl-C, Ctrl-G or Esc should abort without printing anything.

The finder should draw itself on the alternate screen buffer, so when it exits the user’s original terminal contents and cursor position are exactly as they were before. It should exit with the right status code, because scripts depend on these: 0 when an item was selected, 1 when there was no match, 2 on error, and 130 when the finder was interrupted.

Testing: Run your finder against a small list and select an item:

printf "apple\nbanana\ncherry\n" | ccfzf

You should get a full screen list of the three items, and after pressing Enter you should be back at your normal shell prompt with your previous screen contents intact, and the chosen item printed. Check the exit codes:

printf "apple\nbanana\n" | ccfzf; echo "exit: $?"

Selecting an item should report exit: 0, and pressing Esc should report exit: 130. Try it with a much larger input to make sure nothing falls over:

ccfzf < /tmp/paths.txt

Step 2

In this step your goal is to make the finder filter as the user types.

Your finder should accept typed characters into the query and narrow the list to the items that match. A match is a fuzzy match: the query characters must appear in the item in order, but they do not have to be next to each other. So abc matches a_big_cat and alphabetacharlie, but not acb.

Matching should use smart case by default, which means the query is matched case-insensitively unless it contains an uppercase letter, in which case it becomes case-sensitive. The user should be able to override this with -i or --ignore-case to force case-insensitive matching, and +i or --no-ignore-case to force case-sensitive matching.

Now that there is a query, the rest of the default key bindings should work too. Ctrl-K, Ctrl-P and Up should move the cursor up the screen, and Ctrl-J, Ctrl-N and Down should move it back down. Remember that the default layout draws the list upwards from the prompt with the best match at the bottom, so moving up the screen walks further down the results, and the cursor starts on the best match with nowhere below it to go. Backspace should delete the character before the cursor, Ctrl-W should delete the word before it, Ctrl-U should clear the query, and Ctrl-A and Ctrl-E should jump the cursor to the start and end of the query.

Finally, add -q or --query=STR so the finder can be started with a query already typed. It saves a lot of typing when you are testing the steps that follow.

Testing: Filter the word list and watch the results change on every keystroke:

ccfzf < /usr/share/dict/words

Type fxf and confirm every remaining item contains an f, then a x, then an f, in that order. Type README against a file list and check that smart case has made the match case-sensitive, then try the same query with -i and confirm lower case matches come back:

git ls-files | ccfzf -i

Move up and down with the arrow keys and with the control keys and confirm both work, then check each editing key does what it should. Check that -q starts you off with the list already narrowed:

git ls-files | ccfzf -q readme

Step 3

In this step your goal is to rank the matches so the best one is at the top.

A fuzzy match on its own is not much use when a query matches ten thousand items. Your finder should score every match and sort the results best first. A good score rewards the things a we care about: characters that matched next to each other, characters that matched at the start of a word (after a space, /, -, _ or .), characters that matched at a camelCase transition, and matches that start nearer the beginning of the item.

Your finder should support --algo=v1|v2 and default to v2, which finds the best possible alignment of the query within the item. The v1 algorithm should be a faster option that is not guaranteed to find the best match.

When two items score the same, --tiebreak=CRI[,..] should decide the order, supporting the criteria length, begin, end and index, and defaulting to length. Finally, the list should show its work: highlight the characters of each item that the query matched.

Have a read of the fzf algorithm notes if you want to see how the original approaches this, but try it yourself first.

Testing: Check that the obvious best match wins:

printf "src/app/main.go\nsrc/main_test.go\nmain.go\ndocs/domain.md\n" | ccfzf -q main

main.go should sort above docs/domain.md, and the matched characters in each line should be highlighted. Compare the two algorithms on the same query:

ccfzf --algo=v1 < /tmp/paths.txt
ccfzf --algo=v2 < /tmp/paths.txt

Type the same query into both and confirm v2 gives at least as good a top result. Then check tiebreaking:

printf "abc\nabcdef\nabcd\n" | ccfzf -q abc --tiebreak=length

The shortest item should be first. Run it again with --tiebreak=index and confirm the input order is used instead.

Step 4

In this step your goal is to make the finder start instantly and stay responsive, no matter how much input is coming.

Right now your finder probably reads all of its input before it draws anything. Real fzf starts up immediately and keeps reading in the background, so the user can begin typing while items are still arriving. Your finder should do the same: show the interface as soon as it starts, then update the item list, the match count and the result list as more input arrives, without ever blocking the keyboard.

To show what is happening, add an info line that displays how many items currently match out of the total number read so far. It should support --info=default|inline|hidden so the user can move it onto the prompt line or turn it off.

Two flags change the order items are considered in: --tac reverses the input, and --no-sort leaves matches in input order instead of score order.

The real test of this step is scale. Your finder should stay interactive with an input of at least one million items, filtering and re-sorting on every keystroke with no pause you can feel.

Testing: Check that the finder appears before the input has finished:

find / -type f 2>/dev/null | ccfzf

The interface should appear immediately and the counter should climb while you type. Try a deliberately slow producer:

(for i in $(seq 1 20); do echo "item $i"; sleep 0.5; done) | ccfzf

You should be able to type and move around while new items keep appearing. Then test at scale:

ccfzf < /tmp/paths.txt

Type a query one character at a time and confirm each keystroke feels instant. Check the info line with --info=inline and --info=hidden, and confirm --tac and --no-sort change the order as expected:

ccfzf --tac < /tmp/paths.txt
ccfzf --no-sort < /tmp/paths.txt

Step 5

In this step your goal is to support extended-search mode, which turns the query box into a small search language.

Extended-search mode is enabled by default. In it, the query is split on spaces and each term must match, so src go finds items containing a fuzzy match for src and a fuzzy match for go. Individual terms can change how they match:

'wild matches items that contain wild exactly, not fuzzily.
^music matches items that start with music.
.mp3$ matches items that end with .mp3.
!fire matches items that do not contain a fuzzy match for fire.
a | b | c matches items that match any one of the terms.

Two flags change the rules. +x or --no-extended turns the mode off so the whole query is treated as one fuzzy term. -e or --exact makes every term an exact match, and in that mode a leading ' means the opposite, a fuzzy term.

Testing: Build a small list you can reason about:

printf "music/song.mp3\nmusic/song.wav\nvideo/clip.mp4\nfirewall.md\nsrc/main.go\n" > /tmp/ext.txt

Then check each form of term:

ccfzf -q "^music .mp3$" < /tmp/ext.txt
ccfzf -q "'song" < /tmp/ext.txt
ccfzf -q "!fire" < /tmp/ext.txt
ccfzf -q "mp3 | mp4" < /tmp/ext.txt

The first should leave only music/song.mp3, and the last should leave the two media files. Confirm +x treats a query with spaces as a single fuzzy term, and that -e makes song an exact match while 'song becomes fuzzy again.

Step 6

In this step your goal is to let the user pick more than one item, and to control the query and the output from the command line.

Your finder should support -m or --multi for multi-select. Tab should mark the item under the cursor and move on, Shift-Tab should unmark it, marked items should be visibly different in the list, and accepting should print all of the marked items rather than just the one under the cursor. --multi=MAX should limit how many items can be marked.

Alongside that, add the options that make the finder easy to drive from a script:

-print-query prints the final query as the first line of output.
f or -filter=STR skips the interface completely and prints the matching items to standard output in score order.
1 or -select-1 accepts immediately when exactly one item matches, and 0 or -exit-0 exits immediately when nothing matches.

Testing: Mark a few items and check they all come out:

git ls-files | ccfzf -m

Press Tab on three items, then Enter, and confirm all three are printed. Check the limit is enforced with --multi=2. Then check the scripting options:

git ls-files | ccfzf -f go
git ls-files | ccfzf -q main --print-query
printf "only-one\n" | ccfzf -1 -q only; echo "exit: $?"
printf "apple\n" | ccfzf -0 -q zzz; echo "exit: $?"

The filter run should print matches in the same order the interactive list would show them, without ever clearing the screen. The -1 run should print only-one without you pressing anything, and the -0 run should exit straight away with exit: 1.

Step 7

In this step your goal is to make your finder a good citizen of the shell.

So far your finder always takes over the whole screen. Add --height=[~]HEIGHT[%] so it can instead draw in a window below the cursor, leaving the rest of the terminal visible, with ~ meaning the window should shrink to fit the content. This is how most people use fzf day to day.

The list arrangement should be configurable too, with --layout=default|reverse|reverse-list. The default puts the list above a prompt at the bottom, reverse puts the prompt at the top with the list below it, and reverse-list puts the list at the top with the prompt at the bottom. --reverse should be a shorthand for --layout=reverse.

Then add the features that let it slot into pipelines and key bindings:

-ansi should interpret ANSI colour codes in the input, rendering the colours in the list and matching against the text rather than the escape sequences.
-read0 should read NUL-delimited input and -print0 should write NUL-delimited output, so your finder is safe with filenames containing newlines.
-expect=KEYS should accept on any of the listed keys as well as Enter, and print the name of the key that was pressed as the first line of output.
When standard input is a terminal, your finder should run $FZF_DEFAULT_COMMAND to produce the item list, and it should read default options from $FZF_DEFAULT_OPTS before the ones on the command line.

Testing: Check the window and layouts:

git ls-files | ccfzf --height=40%
git ls-files | ccfzf --height=~40% --reverse

Your shell prompt and previous output should still be visible above the finder, and the second command should shrink the window when few items match. Then check the rest:

grep --color=always -r "func" . | ccfzf --ansi
find . -type f -print0 | ccfzf --read0 --print0 | xargs -0 ls -l
git ls-files | ccfzf --expect=ctrl-o,ctrl-e
export FZF_DEFAULT_COMMAND='find . -type f'
export FZF_DEFAULT_OPTS='--reverse --height=40%'
ccfzf

With --ansi the colours from grep should appear in the list and typing an escape sequence like [0m should match nothing. The --expect run should print ctrl-o on its own line before the selected item. The last run should start the finder with no input piped in, using the command and options from the environment.

Step 8

In this step your goal is to add the two features that make fzf genuinely powerful: matching on part of an item, and previewing what is under the cursor.

First, fields. -d or --delimiter=REGEX should split each item into fields, defaulting to AWK-style whitespace splitting. -n or --nth=N[,..] should restrict matching to the given fields, so the user can search on one column and ignore the rest. --with-nth=N[,..] should change which fields are displayed. Both should accept the field index expressions 1, -1, 3..5, 2.., ..-3 and ...

Second, previews. --preview=COMMAND should run a command each time the cursor moves and show its output in a preview window beside the list. Inside the command, {} should be replaced with the current item single quoted, {1}, {2} and so on with its fields, {n} with its zero-based index, and {+} with the selected items. --preview-window=[POSITION][,SIZE[%]] should place the window up, down, left or right, defaulting to right,50%.

Testing: Search on a single column of a table:

ps aux | ccfzf -n 11.. --with-nth 11..

You should be matching and seeing only the command, not the process statistics. Try a different delimiter:

ccfzf -d : -n 1 < /etc/passwd

Typing a user name should match, but typing part of a home directory path should not. Then check the previews:

git ls-files | ccfzf --preview 'head -50 {}'
git ls-files | ccfzf --preview 'head -50 {}' --preview-window=up,30%
git log --oneline | ccfzf --preview 'git show {1}'

The preview should update as you move the cursor, the window should move where you asked it to, and the git log example should show the full commit for the hash in the first field.

Going Further

Once you have the core finder working, here are some ideas to take it further:

Add -prompt, -pointer and -marker so the interface can be styled.
Add -color to support custom colour schemes, including the built-in dark, light and 16 themes.
Add -bind so users can attach their own actions to their own keys.
Add -header and -header-lines to keep a fixed header above the list.
Add -cycle so moving past the end of the list wraps around to the start.
Add -history so queries are saved between runs and can be recalled with Ctrl-P and Ctrl-N.
Add the reload action so the item list can be regenerated from a new command while the finder is running.
Add -listen so a running finder can be controlled over HTTP.
Write the shell integration: Ctrl-T to insert a file path, Ctrl-R to search history, and * completion.
Benchmark your finder against the real fzf on a list of ten million items and see how close you can get.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #136 - Hyperfine

John Crickett — Sat, 12 Sep 2026 08:03:11 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #136 - Hyperfine

This challenge is to build your own version of hyperfine, a command-line benchmarking tool.

When we want to benchmark the performance of a program or script the easy answer is to use time. If the old tool took 45 minutes and the new one takes 4 minutes, time is good enough. If the difference isn’t so glaringly obvious you need. proper benchmarking tool.

A proper benchmarking tool exists to run each command several times, throw away the noise, work out how confident it can be in the result, and warn you when the numbers should not be trusted.

That is what makes hyperfine such an interesting project. The process side of it is straightforward. The statistics and interpretation of the results is interesting and fun!

The Challenge - Building Your Own Hyperfine

In this challenge you’re going to build your own version of hyperfine, a benchmarking tool for the command line. Your tool will take one or more commands, run each of them enough times to get a reliable answer, and report how long they took with a proper measure of how much that time varied. It will compare commands against each other, run the same command with different parameters, export the results for further analysis, and warn you when something about the measurements looks suspicious.

The tricky parts are not where you might expect. Spawning a process and timing it is easy. Working out how many times to run it, removing the cost of starting a shell from the measurement, deciding whether a slow run is a real result or a random blip, and putting a sensible error bar on a comparison, those are the parts that will make you think.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your target platform and programming language. You will need to start a child process, wait for it to finish, and measure both the elapsed wall clock time and the processor time it used in user space and in the kernel. Most languages expose the second part through something like getrusage or wait4, so it is worth checking how yours does it before you start.

Install the real hyperfine so that you have something to compare your output against as you go. Run it on a few commands and get a feel for what it prints:

hyperfine 'sleep 0.3'
hyperfine --runs 5 'sleep 0.3'
hyperfine 'sleep 0.1' 'sleep 0.2'

Throughout this challenge I will use sleep as the command being benchmarked. That is deliberate: sleep 0.3 should take almost exactly 300 milliseconds, so you always know what the right answer looks like and can tell when your tool is wrong. I’ll call our version cchyperfine, but name yours whatever you like.

Step 1

In this step your goal is to time a single run of a single command.

Your tool should take one command as an argument, run it, and report how long it took. Run the command through an intermediate shell, the way hyperfine does, so that anything you can type at a shell prompt works as a benchmark: pipes, redirection, quoting, shell built-ins, and so on. On Unix that means /bin/sh -c, on Windows cmd.exe /C.

As well as the elapsed time, record how much processor time the command used in user space and how much it spent in the kernel. Those two numbers are useful later for telling the difference between a command that is working hard and one that is waiting around.

Don’t worry about the output of the benchmarked command appearing on your screen and making a mess. We’ll deal with that in the last step.

Testing:

cchyperfine 'sleep 0.3'

You should see a time of roughly 300 milliseconds, plus a small amount of overhead for starting the shell and the sleep process. The user and system times should both be tiny, because sleep does nothing but wait.

Check that the shell really is involved:

cchyperfine 'echo hello | wc -c'

This should run and report a time rather than complaining about an unknown command or an unexpected |.

Step 2

In this step your goal is to run a command many times and report the statistics.

Add a -r / --runs NUM option that runs the command that many times, then report a summary of the results in the same shape that hyperfine uses: a mean with a standard deviation next to it, the user and system times, then the fastest and slowest run along with how many runs were performed.

Benchmark 1: sleep 0.3
  Time (mean ± σ):     304.7 ms ±   1.6 ms    [User: 1.1 ms, System: 1.8 ms]
  Range (min … max):   302.6 ms … 308.4 ms    5 runs

Pick the time unit automatically based on how big the numbers are, so a command that takes a few hundred microseconds is not reported as 0.0003 s. Add a -u / --time-unit option taking microsecond, millisecond or second for when the reader wants to choose for themselves.

Testing:

cchyperfine --runs 5 'sleep 0.3'

The mean should be close to 300 ms and the standard deviation should be small, a couple of milliseconds at most on an idle machine. Compare your output against the real thing:

hyperfine --runs 5 'sleep 0.3'

Then check the unit handling:

cchyperfine --runs 5 -u second 'sleep 0.3'
cchyperfine --runs 50 'sleep 0.005'

The first should report seconds, and the second should choose milliseconds by itself.

Step 3

In this step your goal is to decide how many runs to perform automatically.

Asking the reader how many runs they want is not much of an improvement on running the command by hand. Instead, when no exact number of runs is given, you should work it out: time the first run, use that to estimate how many runs fit into a minimum benchmarking time of three seconds, and go with that. Never do fewer than ten runs, however fast the command is, because you cannot say anything useful with just a handful of measurements.

Add -m / --min-runs NUM (defaulting to 10) and -M / --max-runs NUM (no limit by default) so the reader can move those boundaries.

A benchmark that runs for more than a few seconds also needs to show some sign of life, so display a progress bar while the runs are happening, along with an estimate of how much longer it will take.

Testing:

cchyperfine 'sleep 0.3'

Three seconds divided by 0.3 seconds is 10, and the minimum is 10, so this should perform 10 runs. Now try a much faster command:

cchyperfine 'sleep 0.01'

This should settle on roughly 300 runs, and you should watch a progress bar fill up while it does them. Then check the boundaries are respected:

cchyperfine --min-runs 50 'sleep 0.3'
cchyperfine --max-runs 20 'sleep 0.01'

The first should perform 50 runs even though 10 would have been enough, and the second should stop at 20.

Step 4

In this step your goal is to remove the cost of the shell from your measurements.

Every time you run a command through a shell, you are also measuring the cost of starting that shell. It is only a few milliseconds, but if the command you are benchmarking takes five milliseconds then a few milliseconds is an enormous error.

Before benchmarking anything, your tool should measure how long the shell takes to start and do nothing. You can work this out by timing 50 runs of an empty command. Subtract that overhead from every measurement afterwards, so what you report is the cost of the command rather than the cost of the shell.

Sometimes the reader does not want a shell at all. Add -S / --shell to choose a different shell, with none meaning “run the command directly, with no shell in the middle”, and -N as a shorthand for --shell=none.

Testing:

cchyperfine 'true'
cchyperfine -N 'true'

Both should report a time close to zero rather than the few milliseconds the shell costs, because that overhead has been taken off. Compare with the real tool, which does exactly the same thing:

hyperfine 'true'

Then check the shell options behave:

cchyperfine -N 'sleep 0.3'
cchyperfine --shell=bash 'sleep 0.3'

Both should still report about 300 ms.

Step 5

In this step your goal is to control what happens around each run.

Real benchmarks need set up. Sometimes you need to build the thing first, sometimes you need to clear a cache before every single run, and sometimes you need to kill a server you started.

Add five options for this:

w / -warmup NUM performs NUM runs before the timed ones and throws the results away, which fills disk caches so that the numbers you keep are all measured under the same conditions.
s / -setup CMD runs once before the timed runs of a benchmark begin.
p / -prepare CMD runs before each timed run.
C / -conclude CMD runs after each timed run.
c / -cleanup CMD runs once after all the runs of a benchmark have finished.

The time taken by the prepare and conclude commands must not end up in the measurement. Only the command being benchmarked is timed. --prepare and --conclude can each be given once for all commands, or once per command when several commands are being benchmarked.

Testing: The order things happen in is the thing to check here, so have each hook leave a trace:

rm -f order.log
cchyperfine --runs 3 \
  --setup 'echo setup >> order.log' \
  --prepare 'echo prepare >> order.log' \
  --conclude 'echo conclude >> order.log' \
  --cleanup 'echo cleanup >> order.log' \
  'echo run >> order.log'
cat order.log

You should see setup once at the start, then prepare, run and conclude repeated three times, then cleanup once at the end.

Check that the hooks are not being timed:

cchyperfine --runs 5 --prepare 'sleep 0.2' 'sleep 0.1'

The reported mean should be about 100 ms, not 300 ms. Finally, try a warmup on something that touches the disk:

cchyperfine --warmup 3 --runs 10 'find . -name "*.md"'

Step 6

In this step your goal is to tell the reader when the numbers cannot be trusted.

This is what separates a good benchmarking tool from time in a loop. Your tool should notice four things and say so.

First, when a benchmarked command exits with a non-zero status, stop and report an error, because timing something that failed is meaningless. Add -i / --ignore-failure for the cases where the reader knows the command exits non-zero and wants the timing anyway, printing the warning Ignoring non-zero exit code.

Second, when a command takes less than five milliseconds, warn that the result may be inaccurate, because the shell startup time cannot be measured much more precisely than that, and suggest the -N option.

Third, look for statistical outliers. Work out how far each measurement sits from the median, measured in units of the median absolute deviation, and treat anything beyond a threshold as an outlier. This is a more robust way of spotting a stray result than using the mean and standard deviation, because one wild measurement does not drag the threshold along with it. When you find outliers, suggest re-running on a quiet machine, and mention --warmup and --prepare if they are not already being used.

Fourth, check whether the first run in particular was much slower than the rest. That is the fingerprint of a cold cache rather than a busy machine, so it should get its own warning, pointing the reader at --warmup and --prepare.

Testing:

cchyperfine 'false'

This should report an error and exit non-zero. Then:

cchyperfine -i 'false'

This should complete and print the warning about ignoring the non-zero exit code. For the fast execution warning:

cchyperfine -N 'true'

For the outlier warning, run a benchmark while giving your machine something else to do in another terminal, for example a build or yes > /dev/null:

cchyperfine --runs 30 'sleep 0.05'

For the slow first run warning, make a large file, drop it out of your cache if you can, and read it without a warmup:

dd if=/dev/urandom of=big.bin bs=1048576 count=200
cchyperfine --runs 10 'wc -c big.bin'

Step 7

In this step your goal is to compare several commands with each other.

Your tool should accept more than one command and benchmark each in turn, numbering them Benchmark 1, Benchmark 2 and so on. Afterwards, print a summary that compares them: find the fastest, then express every other command as a multiple of it, with an error bar that takes the variation in both sets of measurements into account.

Summary
  'sleep 0.1' ran
    2.01 ± 0.02 times faster than 'sleep 0.2'
    3.02 ± 0.03 times faster than 'sleep 0.3'

Add --reference CMD for when the reader wants everything compared against a particular command rather than the fastest one, which is what you want when you are asking “how much did my change cost?” rather than “which of these is quickest?”. Add -n / --command-name NAME so that a long command line can be given a short, readable name in the output, once for each command being benchmarked.

Testing:

cchyperfine 'sleep 0.1' 'sleep 0.2' 'sleep 0.3'

The summary should report the second command as about 2 times slower than the first and the third as about 3 times slower, with small error bars. Then change the reference:

cchyperfine --reference 'sleep 0.2' 'sleep 0.1' 'sleep 0.3'

Everything should now be compared against sleep 0.2, so sleep 0.1 is about 2 times faster and sleep 0.3 about 1.5 times slower. Finally, check the names:

cchyperfine -n fast 'sleep 0.1' -n slow 'sleep 0.2'

The output should say fast and slow rather than repeating the commands.

Step 8

In this step your goal is to run the same benchmark across a range of parameter values.

Very often the question is not “which command is faster” but “how does this command behave as I change one thing about it”. Add two options for that, both of which replace {VAR} in the command with the current value:

P / -parameter-scan VAR MIN MAX runs a benchmark for each value in the range, with D / -parameter-step-size DELTA controlling the size of the steps.
L / -parameter-list VAR VALUES runs a benchmark for each value in a comma-separated list. Given more than once, it should benchmark every possible combination of the values.

Testing:

cchyperfine -P delay 0.1 0.3 -D 0.1 'sleep {delay}'

This should run three benchmarks, taking about 100 ms, 200 ms and 300 ms, and the summary should show them getting steadily slower. Then:

cchyperfine -L delay 0.1,0.2,0.3 'sleep {delay}'

That should produce the same three benchmarks. Now try two parameters at once:

cchyperfine -L outer 0.1,0.2 -L inner 0.1,0.2 'sleep {outer}; sleep {inner}'

You should get four benchmarks, one for each combination.

Step 9

In this step your goal is to export the results for further analysis.

Printing to the terminal is fine for a quick comparison, but benchmark results are much more useful when you can plot them, put them in a report, or track them over time in a build pipeline. Add --export-json FILE, which should record for each command its mean, standard deviation, median, user time, system time, minimum, maximum, the individual timings of every single run, the exit codes, and the values of any parameters used.

Then add --export-csv FILE, --export-markdown FILE, --export-asciidoc FILE and --export-orgmode FILE, which need only the summary statistics rather than the individual timings.

If you match the JSON that the real hyperfine produces, the plotting scripts that ship with it will work on your output too, which is a nice way to check you got the format right.

Testing:

cchyperfine --runs 10 --export-json results.json 'sleep 0.1' 'sleep 0.2'
cat results.json

The file should contain two entries, each with a times array holding exactly 10 measurements, and the mean should match what was printed on screen. Then:

cchyperfine --runs 10 --export-markdown results.md 'sleep 0.1' 'sleep 0.2'
cat results.md

That should give you a table you could paste straight into a pull request.

Step 10

In this step your goal is to control the input and output of the benchmarked commands.

Up to now the output of whatever you benchmark has been print on your terminal. By default it should be thrown away instead. Add --output taking null (the default), pipe, inherit, or a filename, and --show-output as a shorthand for --output=inherit. The pipe option matters because some programs, grep among them, notice when their output is going to /dev/null and take shortcuts, which would make your benchmark measure the wrong thing.

Add --input taking null (the default) or a filename, for benchmarking commands that read from standard input.

Set an environment variable $HYPERFINE_ITERATION for each run, holding the number of the current run, so that the benchmarked command can tell its runs apart. Finally add --sort taking auto, command or mean-time to order the results, and --style taking auto, basic, full, nocolor, color or none to control how much decoration the output has.

Testing:

cchyperfine --runs 3 'echo hello'
cchyperfine --runs 3 --show-output 'echo hello'

The first should print nothing from echo, the second should print hello three times. Then check the input redirection:

seq 1 100000 > numbers.txt
cchyperfine --input numbers.txt 'wc -l'

Check the iteration variable:

rm -f iterations.txt
cchyperfine --runs 3 'echo $HYPERFINE_ITERATION >> iterations.txt'
cat iterations.txt

You should see three different numbers. Finally:

cchyperfine --sort mean-time --style basic 'sleep 0.3' 'sleep 0.1' 'sleep 0.2'

The results should be listed fastest first, with no colour or progress bar in the output.

Going Further

Once you have the core tool working, here are some ideas to take it further:

Add -time-unit support for nanoseconds, and check your formatting still reads well at that scale.
Report peak memory usage alongside the timings, which is often the number that actually matters.
Warn when the machine looks like a bad place to benchmark, for example when the load average is high, the battery is discharging, or CPU frequency scaling is enabled.
Add an option to pin the benchmarked process to a particular CPU core, and see how much it reduces the variation.
Produce an HTML report with interactive charts from a set of exported JSON files.
Use it in a build pipeline to fail a change that makes a command measurably slower than the previous run, which means solving the harder problem of comparing results measured on different machines at different times.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #135 - Voice Dictation App

John Crickett — Sat, 05 Sep 2026 08:01:16 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #35 - Voice Dictation App

This challenge is to build your own private voice dictation app. It’s a simple version of something like SuperWhisper or Whispr Flow.

Most dictation tools send your voice off to a server in the cloud. That works, but it means you need an internet connection, and your voice is leaving your machine. That comes with a cost, for the service, the latency and privacy. So, in this challenge you’ll build the whole pipeline yourself and keep it entirely on your own computer: capturing audio, turning it into text with a local speech model, tidying that text up, and then typing it directly into the app that currently has focus. All without a single network request.

Along the way you’ll get hands on with some genuinely tricky systems programming: catching a keypress that happens outside your own app, running a machine learning model, and injecting text into a program you don’t control and didn’t write.

The Challenge - Building Your Own Voice Dictation App

You’re going to build a background app that lets you press and hold a hotkey, speak, and release the hotkey to have your words appear as text wherever your cursor is, be that an email, a chat window, a code editor or a document.

Over the course of this challenge you’ll add local speech recognition, an AI cleanup pass that removes your “ums” and fixes your grammar, spoken formatting commands, a custom dictionary, and a history of everything you’ve dictated.

The speech recognition and text cleanup logic is much the same wherever you build it, but capturing a global hotkey and inserting text into another application’s focused field are done through operating system specific APIs.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose the operating system you’ll target, macOS, Windows or Linux, and a programming language with good support for that OS’s accessibility or automation APIs (the APIs that let a program capture a global hotkey and type into whatever window has focus).

Spend a little time reading up on what your platform offers here: on macOS that’s the Accessibility API and CGEventTap, on Windows it’s SetWindowsHookEx and UI Automation, on Linux it’s typically AT-SPI along with a tool like wtype or xdotool .

You’ll also need a way to run speech-to-text locally. Have a look at whisper.cpp, faster-whisper, or Vosk, and check which of them your chosen language and platform can use comfortably. You don’t need to install everything now, just confirm you have a path from “microphone audio” to “text” that runs entirely offline.

Finally, open a plain text editor and a couple of other everyday apps (a browser address bar, a notes app, a terminal) that you can use as targets to type into while you test each step.

Step 1

In this step your goal is to create a simple app and register a global, system-wide hotkey and use it to start and stop an audio recording.

Your app should let the user choose a hotkey from at least two options (for example the Fn key or the right Cmd/Ctrl key). While the app is running in the background, pressing and holding that hotkey should start recording from the system microphone, and releasing it should stop the recording immediately, regardless of which application is currently focused.

Testing: With your app running in the background, switch focus to any other application (a browser, a text editor). Press and hold your configured hotkey, say a few words, then release it. Add some logging so you can confirm in your console or logs that a recording started on key down and stopped on key up, with a duration roughly matching how long you held the key.

Step 2

In this step your goal is to show a visual indicator confirming that recording is in progress.

While the hotkey is held down, display something the user can see, a small floating overlay near the cursor, an animation in the menu bar or system tray, whatever suits your platform, that clearly shows recording is active. It should disappear the moment the hotkey is released.

Testing: Hold the hotkey and confirm the indicator appears within a fraction of a second. Release it and confirm the indicator disappears immediately. Try triggering it while different applications are focused to make sure it always appears regardless of what’s underneath it.

Step 3

In this step your goal is to transcribe the recorded audio to text entirely on your local machine.

Wire up the local speech-to-text engine you chose in Step Zero so that, when the hotkey is released, the recorded audio is transcribed and the resulting text is printed or logged. Make sure no audio or text ever leaves the machine,.

Testing: Turn off your Wi-Fi or unplug your network cable, then hold the hotkey and say a short, clear sentence like “The quick brown fox jumps over the lazy dog.” Release the hotkey and confirm the transcribed text appears in your logs and roughly matches what you said, with the network still disconnected.

Step 4

In this step your goal is to let the user choose between at least two speech-to-text models with different size and accuracy trade-offs.

Offer at least two models, for example a small, fast model and a larger, more accurate one, in a settings screen. The first time a model is selected, download its weights to disk and show a progress indicator while that happens. Once downloaded, switching models should be instant.

Testing: Select the smaller model, dictate a sentence, and note the response time. Switch to the larger model (triggering a download if it’s the first time you’ve selected it, and confirm the progress indicator moves) and dictate the same sentence again. Compare the accuracy and speed of the two.

Step 5

In this step your goal is to show a live, continuously updating preview of what’s being recognised while the hotkey is still held down.

Rather than waiting until the hotkey is released to show any text, update your visual indicator from Step 2 with the transcription so far, refreshing it as more speech is recognised.

Testing: Hold the hotkey and speak a longer sentence slowly. Watch the preview and confirm it updates progressively as you speak, rather than appearing all at once only after you release the key.

Step 6

In this step your goal is to run a cleanup pass over the raw transcript that removes filler words and fixes grammar and punctuation.

After the hotkey is released and you have a raw transcript, run it through a local cleanup step before it’s used anywhere else. This should strip out filler words like “um” and “uh”, correct obvious grammar mistakes, and add sensible sentence casing and punctuation. This all needs to happen locally too, no calling out to a hosted AI cleanup API.

Testing: Dictate a sentence with deliberate filler words, something like “so, um, I think we should, uh, meet on Tuesday”. Confirm the cleaned up output reads naturally, for example “I think we should meet on Tuesday.”, with the filler words gone and proper punctuation added. Repeat the network monitoring check from Step 3 to confirm the cleanup pass makes no outbound calls either.

Step 7

In this step your goal is to recognise spoken formatting commands and turn them into real line and paragraph breaks.

When the user says “new line” or “new paragraph” partway through dictating, your cleanup pass should detect the phrase and insert an actual line break or paragraph break at that point in the output, rather than transcribing the words literally.

Testing: Dictate “Dear Sam, new paragraph, Thanks for your help this week, new line, Best, Alex” in one go. Confirm the output has an actual paragraph break after “Dear Sam,” and a line break before “Best, Alex”, and that the words “new paragraph” and “new line” do not appear in the output.

Step 8

In this step your goal is to detect dictated lists and format them as bulleted or numbered lists.

When someone dictates something that sounds like a list, for example “first buy milk, second walk the dog, third call mum”, your cleanup pass should recognise the pattern and produce an actual bulleted or numbered list in the output.

Testing: Dictate a three item list using ordinal words (”first”, “second”, “third”). Confirm the output is formatted as a numbered or bulleted list with three separate items rather than one run-on sentence.

Step 9

In this step your goal is to insert the cleaned up text directly into whichever application and text field currently has focus.

Using your platform’s accessibility or automation APIs, insert the final text at the current cursor position in the focused field, in the focused application, the moment it’s ready. This should work across different kinds of apps: a browser text box, a native text editor, a chat app.

Testing: Open a plain text editor, click into it so it has focus, and dictate a sentence. Confirm the text appears at your cursor position in the editor. Repeat with a browser address bar or search box, and with a chat or notes app, confirming the text lands correctly in each.

Step 10

In this step your goal is to add a clipboard fallback for when direct text insertion isn’t possible.

Some fields or apps won’t support direct insertion, for example because of missing permissions or an unsupported field type. Detect when insertion fails, copy the cleaned up text to the clipboard instead, and show the user a clear notification telling them what happened and that the text is ready to paste.

Testing: Find or simulate a case where direct insertion fails (for example, by revoking the accessibility permission your app needs, or targeting a field type you know your implementation doesn’t support). Dictate something and confirm you see a fallback notification and that the text is sitting on the clipboard ready to paste.

Step 11

In this step your goal is to build a first launch setup flow that requests the permissions your app needs before it can be used.

On first launch, walk the user through granting microphone access and input injection/accessibility access, one at a time, checking that each has actually been granted before letting them move on to the next step.

Testing: Reset your app’s permissions and relaunch it. Confirm you’re taken through the setup flow, that you can’t skip past a step whose permission hasn’t been granted yet, and that once both are granted, dictation works straight away.

Step 12

In this step your goal is to detect when a previously granted permission has been revoked and prompt the user to fix it.

If the user (or their OS) revokes microphone or accessibility access after setup, your app should notice this before attempting to dictate and prompt the user to re-grant the permission, rather than failing silently or crashing.

Testing: With your app set up and working, manually revoke the accessibility permission in your OS settings, then try to dictate. Confirm your app detects the missing permission and shows a clear prompt to re-grant it, rather than silently failing.

Step 13

In this step your goal is to add a dictionary screen where the user can teach the app words it gets wrong.

Add a settings screen listing custom words and corrections, for example proper nouns, product names, or jargon, that the user can add to or edit. Apply these entries during the cleanup pass in Step 6, so a word the speech model consistently mishears gets corrected before the text is inserted.

Testing: Dictate a word you know your speech model struggles with (an unusual name works well) and confirm it comes out wrong. Add a dictionary entry correcting it, dictate the same word again, and confirm it now comes out correctly.

Step 14

In this step your goal is to keep a local, searchable history of everything you’ve dictated.

Every time text is dictated, store the raw transcript, the cleaned up text, and a timestamp. Add a screen where the user can search and browse this history.

Testing: Dictate several different sentences over a few minutes. Open the history screen and confirm all of them appear with the correct timestamps and both the raw and cleaned up versions. Search for a word that only appears in one of them and confirm only that entry is returned.

Step 15

In this step your goal is to show aggregate dictation statistics drawn from the history.

Using the history you built in Step 14, calculate and display statistics such as the total number of words dictated and the total number of dictation sessions.

Testing: Note your current statistics, dictate a sentence with a known word count, and confirm the totals update by the expected amount. Restart your app and confirm the statistics persist rather than resetting.

Going Further

Once you have the core tool working, here are some ideas to take it further:

Let the user define custom voice commands beyond “new line” and “new paragraph”, for example “select all” or “delete that”.
Add per application profiles, so the cleanup style (for example more formal for email, more relaxed for chat) changes depending on which app is focused.
Build an always on “ambient” mode as an alternative to push to talk, with a wake phrase to start and stop listening.
Add undo support, so a single keypress reverts the last inserted dictation.
Benchmark your different supported speech models for latency and accuracy against a fixed set of test recordings.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #134 - Agentic Engineering Graph

John Crickett — Sat, 29 Aug 2026 08:01:12 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #134 - Agentic Engineering Graph

This challenge is to build your own agentic engineering graph. So what is an agentic engineering graph? It’s a small orchestration system that runs an autonomous coding loop: plan, write code, test, review, and retry, with state, that allows it to survive a crash and a control point where a human can step in and approve or reject a plan.

If you follow the agentic engineering discussion on social media and the latest tech news you’ll have seen that agent graphs have gone from a niche pattern to something every engineering team seems to be experimenting with this year.

The reason is simple: a single call to an agentic coding CLI is impressive but unreliable on its own, ask it to fix a bug and it might nail it the first time, or wander off down the wrong path with nothing to stop it. Or you have to sit there reading all the output and stop it manually. Yuk!

The fix that teams have converged on is the same one distributed systems adopted years ago: break the work into discrete steps, persist state between them, and let an orchestrator decide what runs next based on what actually happened rather than what was supposed to happen.

That’s what frameworks like LangGraph do, and it’s also what’s often inside CI pipelines and internal tools wherever teams are wiring agentic CLIs into their workflows.

In this challenge you’ll build the same kind of system yourself, without reaching for a graph framework. Your “graph” will be a small dispatcher and a set of scripts, your “nodes” will be calls to an agentic coding CLI running non-interactively, and your “state” will be plain files on disk that you could open and read at any point.

Along the way you’ll add a deterministic quality gate using Sonar‘s static analysis CLI, so your agent has to satisfy a set of rules it cannot argue its way around, and then you’ll swap that gate for an AI-augmented review node using the SonarQube MCP Server, and watch the rest of your graph carry on working without caring which kind of node it’s talking to.

Ultimately that’ll look like this:

With the inner loop being this:

This challenge was created in collaboration with Sonar.

The Challenge - Building Your Own Agentic Engineering Graph

You’re going to build a small system that takes a coding task, plans an approach, writes code, tests it, reviews it, and retries automatically when something fails, all the way through to a working result. It will survive being killed and restarted, it will let a user approve the plan before any code gets written, and then it will run one or more attempts at a task in parallel and pick the best one.

This challenge doesn’t require expertise in any particular programming language, most of what you’re building is small scripts and a dispatcher.

Pick whatever scripting or general-purpose language you’re most comfortable with for the dispatcher and the small helper scripts. The interesting parts of this challenge are architectural, so the programming language is genuinely up to you. As the individual programs are quite small it’ll be a fun project to learn a new language or (or go crazy and use several to compare).

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

You’ll need three things.

First, an agentic coding CLI that can run non-interactively from a single command, let you scope which tools it’s allowed to use for a given invocation, and connect to MCP servers. Claude Code and Codex CLI both qualify. If you’re planning to use something else, check it supports all three of those before you start, because you’ll rely on each of them at different points in the challenge.

Second, SonarQube running SonarQube Cloud (or the self-managed Community Build) gets you a working setup, and you’ll also want the sonar-scanner CLI installed and able to talk to it. You won’t need it until partway through the challenge, but it’s worth confirming it works now rather than discovering a setup problem later.

Third, a small coding task you can use as your test fixture throughout the challenge, ideally something with its own test suite. Pick something you can deliberately break, a function you can introduce a bug into, a rule you can violate on purpose, so you have a reliable way to drive the loop through both its happy path and its failure path at every step. I used one of the Redis clones I’ve built with students in my coding with AI classes.

Step 1

In this step your goal is to build the fragile version of an agentic workflow. This is the one you’ll spend the rest of the challenge replacing. This is the MVP or prototype.

You’re going to write a single script that invokes your agentic coding CLI non-interactively exactly once, with a prompt describing your fixture task, and writes whatever comes back straight to a file. No branching, no retry, and nothing recorded anywhere about what happened.

Once it runs, write down everything it doesn’t do. There’s no retry if the invocation fails, there’s no record anywhere that it ran, there’s no way to see what happened partway through, and if it produces something wrong there’s no way to try again short of running the whole thing over.

Keep that list. Every remaining step in this challenge addresses one of the items on it.

Testing: Run your script against your fixture task and confirm you get a plausible attempt at the task written to a file. Then break it on purpose, point it at an invalid credential or an unreachable endpoint, and run it again. Confirm you get nothing useful back and no trace of what was attempted.

Step 2

In this step your goal is to turn that single script into the first version of your graph.

Define what a node is in your system: an executable that reads a state file from a run directory, invokes your agentic CLI with a narrowly scoped prompt and a limited set of tool permissions, and writes an updated state file back. Then write a dispatcher, a script that, given a run directory and a starting node name, runs that node, reads which node to run next from the state it wrote, and calls that node in turn.

Re-implement Step 1 as three separate nodes, wired together by your dispatcher in a straight line: a plan node that produces an approach, a code node that writes an implementation based on that plan, and a write node that commits the result to your fixture project.

Testing: Point your dispatcher at your fixture task and run it from plan through to write. Confirm all three state files were created, in order, and that the final result matches what your Step 1 script produced. Open one of the intermediate state files and confirm it’s readable on its own, with no need to run anything to inspect it.

Step 3

In this step your goal is to add a test node and a self-correcting fix loop.

Add a test node that runs your fixture task’s test suite and writes the pass or fail result, along with the output, into the state file. Have your dispatcher branch on that result: on to a terminal END node if the tests pass, or to a fix node if they don’t.

Build fix as a node like any other: it reads the failure output and the previous code from state, asks your agentic CLI to repair it, writes the result back, and loops to test again. Add an iteration count to your state, and once it passes a limit you choose, route to a give_up terminal node instead of looping forever.

Testing: Deliberately break your fixture task’s code so the tests fail, then run the graph from code onward. Confirm test fails once, fix runs, test runs again and passes, and the dispatcher reaches END. Now introduce a failure your fixture genuinely can’t be talked out of, run it again, and confirm the loop stops at give_up once it hits your limit rather than running indefinitely.

Step 4

In this step your goal is to make a run survive a process dying.

After every node runs, write an entry to a run manifest recording which node ran, when, and whether it succeeded. When the dispatcher starts, have it check for an existing manifest for that run and, if one exists, resume from the node after the last one that completed successfully rather than starting from plan again.

Add a small command that lists past runs by reading their manifests, showing each run’s current node and status at a glance.

Testing: Start a run, and once the manifest shows plan complete but before code has finished, kill the dispatcher process. Restart it against the same run directory and confirm it picks up at code, not from the beginning. List your runs and confirm the status shown matches what actually happened.

Step 5

In this step your goal is to let a human review and approve a plan before any code gets written.

Add an interrupt point right after the plan node. Rather than moving straight on to code, the dispatcher should stop and wait until a human has reviewed the plan file, optionally edited it, and given a clear signal that it’s ready to proceed.

You shouldn’t need any special machinery to keep a run paused for as long as you like. Because your state already lives in files rather than in memory, a paused run is just a run directory sitting there until someone comes back to it and runs the tool again.

Testing: Start a run and confirm it stops after plan and waits. Edit the plan file, give your readiness signal, and confirm code then runs using your edited version rather than the original. This time, stop the dispatcher entirely while it’s paused, walk away, and come back later to confirm the run is exactly where you left it and resumes correctly.

Step 6

In this step your goal is to add a deterministic quality gate using SonarQube.

Add a review node that runs sonar-scanner against the code your graph has produced and parses the resulting quality gate status into your state. Ensure you set sonar.qualitygate.wait=true and sonar.qualitygate.timeout for your environment.

Extend your dispatcher’s branching so that a failed gate, whether from a new bug, a vulnerability, or coverage dropping below your threshold, routes to fix with the Sonar findings attached to state, exactly the way a failing test does.

Testing: Introduce an issue into your fixture that SonarQube reliably catches, something like a hardcoded secret or a deeply nested conditional, and confirm review fails the gate and routes to fix, with the loop eventually producing a version that passes. Then run the same input through review twice in a row and confirm you get identical findings both times. That repeatability is the whole point of this step.

This is what we want to see in SonarQube, passing quality gates:

Useful reference: SonarScanner docs.

Step 7

In this step your goal is to extend that review node with one backed by an AI agent, using the SonarQube MCP Server.

Instead of parsing sonar-scanner’s output yourself, have review invoke your agentic CLI with the SonarQube MCP server attached and a scoped prompt instructing it to query issues, security hotspots, and the quality gate through tool calls. Keep the state it writes identical in shape to what the CLI-based version wrote, so your dispatcher’s branching logic doesn’t need to change at all.

Testing: Run the graph against the same fixture issue you used in Step 6, through the MCP-backed review node this time, and confirm it reaches the same pass or fail decision. Inspect the node’s own record of what it did and confirm it queried SonarQube through tool calls rather than guessing at an answer.

Useful reference: SonarQube MCP Server.

Step 8

In this step your goal is to run several attempts at a task in parallel and pick the best one.

Add a node that starts several candidate attempts at the same task at once, each working in its own isolated copy of the project, each running its own test and review nodes independently of the others. Add a join node that looks at the candidates once they’ve all finished, discards any that failed the tests or the quality gate, and picks a winner from what’s left using a rule you define, such as the fewest Sonar issues or the fastest test run.

You should make the number of candidates configurable.

Testing: Run the fan-out with at least three candidates against your fixture task and confirm all three run without interfering with each other’s files or state. Deliberately make one candidate worse than the others, either by constraining it or sabotaging its starting point, and confirm your join node correctly excludes it and picks a winner from the remaining candidates according to your chosen rule.

Step 9

In this step your goal is to make a run’s history visible.

Log the node name, timestamp, and duration for every transition your dispatcher makes, either through your agentic CLI’s own lifecycle hooks if it has them, or by having the dispatcher log directly. Then build a simple way to render a run’s log as a timeline, so you can see the path a run actually took from start to finish.

Testing: Run the full graph end to end on a task that needs at least one pass through the fix loop, and check the resulting timeline. Confirm every node that executed appears in the correct order with a plausible duration, and confirm a node like fix that ran more than once shows up more than once, in the right places.

Going Further

Once you have the core graph working, here are some ideas to take it further:

Point your finished graph at a handful of real Coding Challenges as target tasks and see how far it gets unattended.
Swap which agentic CLI runs different nodes in the same graph, and confirm nothing else needs to change, since the only real contract is the files a node reads and writes.
Add a ship node that pushes a branch and opens a pull request once a candidate passes everything, and see what changes once your output is a pull request rather than a local file.
Track token usage and cost per node, so you can see exactly which part of the loop is the expensive one.
Add Sonar’s Gitar AI Code Review alongside SonarQube and have the review lead to agentic fix.
Turn your timeline from Step 9 into an actual diagram of the graph, showing which nodes ran, which were skipped, and where the loops happened.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #133 - Particle Playground

John Crickett — Sat, 22 Aug 2026 08:01:30 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #133 - Particle Playground

This challenge is to build your own particle playground: an interactive canvas where you paint materials and watch them behave. Sand will pile up. Water will flow and finds its level. Fire spreads and burns out. Fireworks launch, burst, and rain embers back down onto whatever you painted underneath.

Particle systems are the trick behind most of the physical-looking effects you see in games and creative coding: explosions, smoke, rain, magic spells, crumbling terrain. That’s where I first learned about them, creating computer graphics for simple games and firework simulators!

In this “particle system” we’re going to cover two different techniques. One is a swarm of free-flying objects pushed around by forces like gravity and wind. The other is a grid of cells updated by simple local rules, which is what lets thousands of grains of sand or drops of water run in real time without doing full physics on each one. In this challenge you’ll build both, then join them together: a firework whose burning embers can fall onto your material grid and set fire to anything flammable underneath.

Win $$$ - Just 48 hours left! Join The Ready, Spec, Ship Hackathon Hackathon I’m Running.

There’s just under 48 hours left in the Ready, Spec, Ship Hackathon!

There’s a $9,600 prize pool, plus 2000 FREE Kiro credits for every verified entry. Submissions close on midnight on the 23rd August, with the winners announced on 6 September.

Find out more and take part:https://codingagents.fyi/hackathon/kiro/

It’s a great chance to checkout the Kiro agentic coding environment!

OK, on with the challenge!

The Challenge - Building Your Own Particle Playground

You’re going to build a 2D particle simulation with two engines working side by side. The first is a classic particle engine: particles with position, velocity, and acceleration, pushed around by gravity, wind, and drag. The second is a cellular automaton: a grid of cells, each holding a material, updated every tick by rules like “sand falls if the cell below is empty”. You’ll build up materials one at a time, add an interface for painting them onto the canvas, and finish with a fireworks display that reuses your particle engine and can set your grid alight.

You can build this in any programming language, so pick whatever you’re comfortable with for 2D graphics and mouse input.

You’ll be making something like this:

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose a platform that gives you pixel-level 2D rendering and mouse input.

Before you start coding, it’s worth reading up on the two techniques you’re going to combine:

The Nature of Code, Chapter 4: Particle Systems covers the classic force-driven particle engine you’ll build in Steps 1 and 2.
Making Sandspiel and Falling Sand explain the cellular automaton approach you’ll build in Steps 3 to 5. You can also have a play with Sandspiel itself to get a feel for how the materials should behave.

Step 1

In this step your goal is to build a basic particle emitter.

Set up an empty window or canvas with a render loop that clears the screen and redraws every frame. Get it running at a steady frame rate before moving on.

Give each particle a position, a velocity, and an acceleration. On every frame, integrate acceleration into velocity and velocity into position, so particles move smoothly over time. When the user clicks or taps on the canvas, spawn one or more particles at that point. Render each particle as a circle, and have it fade out as it approaches the end of its lifespan. Once a particle’s lifespan expires (or it becomes fully transparent), remove it so your particle list doesn’t grow forever.

Testing: Click a few times in different spots on the canvas. You should see small circles appear at each click point, drift briefly, and fade to nothing over a second or two. Click rapidly in one spot and confirm old particles disappear rather than piling up forever, watch a particle counter to be sure they’re actually being removed.

Step 2

In this step your goal is to make your particles respond to forces.

Add a constant downward gravity force applied to every particle every frame, so they arc and fall instead of drifting in a straight line. Add an adjustable wind force, a constant horizontal acceleration you can tune, and a drag force proportional to each particle’s velocity, so particles slow down over time even with no gravity or wind acting on them. Finally, detect when a particle reaches the edges or floor of the canvas, and have it bounce, reflecting its velocity and losing some speed (damping) each time it bounces.

Testing: Click near the top of the canvas and watch particles fall under gravity rather than drifting evenly. Turn wind on and confirm particles curve sideways as they fall. Increase drag and confirm particles slow down and settle rather than bouncing forever. Drop particles onto the floor and count how many bounces it takes before a particle’s bounce height becomes negligible, it should be a handful, not dozens.

Step 3

In this step your goal is to add a second simulation substrate: a grid-based falling sand simulation.

Create a 2D grid of fixed-size cells, each holding a material type (start with just empty and sand). Implement the classic falling sand rule for sand: on each tick, a sand cell falls one cell straight down if the cell below is empty; if straight down is blocked but a diagonal (down-left or down-right) is free, it falls diagonally instead. Update the whole grid in a way that guarantees no cell is processed more than once per tick, for example by writing updates into a second buffer and swapping buffers at the end of the tick, or by scanning in an order that never lets an already-moved cell be revisited.

Testing: Programmatically fill a vertical line of sand cells near the top of an otherwise empty grid and run the simulation. You should see the sand fall and form a roughly triangular pile with a natural angle of repose, not a perfectly flat-topped column and not sand that clips through the floor.

Step 4

In this step your goal is to add liquids and a static solid to your material grid.

Add a water material that falls like sand but, when it can’t fall any further, spreads sideways into an empty neighbouring cell. Add an oil material that behaves like water but is less dense, when a falling oil cell would land on top of a water cell, it should displace upward through the water instead of settling below it, so oil ends up floating on water. Add a stone material that is immovable and blocks every other material from passing through or displacing it.

Testing: Fill a small pool of water and confirm it spreads out to find a level surface rather than staying in a pile like sand. Drop oil into a container of water and confirm it rises to the top over a few ticks. Build a stone wall across the middle of the grid and pour sand or water onto it, confirm nothing passes through or moves a stone cell.

Step 5

In this step your goal is to add fire, smoke, and steam.

Add a wood material that, like stone, doesn’t move, but is flammable. Add a fire material that ignites any flammable material (wood or oil) in an adjacent cell, and burns itself out to an empty cell after a fixed lifetime. Add a smoke material that spawns above burning cells, drifts upward, and dissipates back to empty over a fixed lifetime. Finally, when a water cell is adjacent to fire, convert it to steam; a steam cell should drift like smoke and convert back to water once it’s gone a fixed amount of time without contacting more fire.

Testing: Build a small wood structure and light one cell of it on fire. Confirm the fire spreads across connected wood cells, each burning out to empty after a few seconds, and that smoke rises from the burning area and fades away rather than accumulating forever. Pour water next to a fire and confirm it turns to steam, drifts upward, and eventually turns back into water once it’s away from the flames.

Step 6

In this step your goal is to make the simulation interactive.

Add a palette letting the user pick the current material to paint, at minimum sand, water, oil, stone, wood, and fire. Add an adjustable brush size, so pressing and dragging the mouse or pointer paints a filled circle of cells of that size in the selected material. Add a button to clear the entire grid back to empty, and a way to pause and resume the simulation without losing the current grid state.

Testing: Select each material in turn and paint a patch of it onto the grid, confirm the right material appears and behaves correctly (sand falls, water spreads, fire spreads and burns out). Increase and decrease the brush size and confirm the painted area scales accordingly. Pause the simulation mid-fall, confirm nothing moves while paused, then resume and confirm it continues from where it left off. Clear the grid and confirm every cell returns to empty.

Step 7

In this step your goal is to build a fireworks display on top of your particle engine. Building fireworks with particles was where I first used them. It was a fun introduction to computer graphics.

When the user clicks a launch point, spawn a rocket using the particle engine and forces you built in Steps 1 and 2, and let the user control how high it goes before exploding, for example with a power slider, or by how far they drag before releasing the click. On explosion, spawn a burst of ember particles following a pattern the user can select. Implement at least four of the classic firework styles described in this overview of firework particle styles:

Ring / sphere: embers spread out evenly in all directions.
Willow: embers have extra drag and gravity, so they trail and droop as they fall, rather than flying outward and vanishing.
Crossette: each ember splits into a small secondary burst partway through its life.
Strobe: embers flicker between visible and invisible as they age.

Let embers fall under gravity after the burst, just like any other particle. When an ember from a low-height burst lands on your material grid, check the cell underneath it, if it holds a flammable material, ignite it, so a firework that bursts close to the ground can set fire to anything flammable you’ve painted there.

Testing: Launch a firework at maximum height and confirm it explodes and spawns embers in your selected pattern, ring embers should spread evenly, willow embers should droop and trail, crossette embers should each produce a smaller secondary burst, and strobe embers should visibly flicker. Launch a low-height firework directly over a patch of wood or oil you’ve painted on the grid, and confirm falling embers ignite it. Launch a low-height firework over sand or stone and confirm nothing ignites.

Step 8

In this step your goal is to make the simulation perform well as particle and cell counts grow.

Decouple your simulation update from your render frame rate by running updates on a fixed timestep, this keeps the simulation speed consistent even if the display refresh rate varies. Cap the number of live particles, or reuse a pool of particle objects, so dense emitters and big fireworks don’t collapse your frame rate. Update your material grid so that, once it’s reasonably large, you only process cells that changed or were active on the previous tick, rather than scanning every cell every tick. Add an on-screen readout showing frames per second, the current live particle count, and the current active grid cell count.

Testing: Fill a large grid (at least a few hundred cells wide) with a mix of falling sand and water and confirm the readout shows a healthy frame rate once most of it has settled and few cells are still active. Launch several fireworks in quick succession and confirm your particle count readout stays capped rather than climbing indefinitely, and that the frame rate holds up. Compare frame rate with and without your active-cell optimisation on a mostly-settled grid to confirm it’s actually helping.

Going Further

Once you have the core playground working, here are some ideas to take it further:

Add more materials: acid that dissolves what it touches, plant seeds that grow when watered, ice that forms from water in a cold region and melts back
Add a save/load feature that serialises the grid and lets users share or reload a scene
Let the user resize the brush with a scroll wheel or pinch gesture, and add an eraser tool
Add a “wind zone” the user can draw that applies extra wind force to particles and embers passing through it
Support multiple simultaneous fireworks with different colours, and let the user pick a colour per launch
Render the grid with a lighting pass, so fire and embers cast a warm glow on nearby cells
Port the grid simulation to run on the GPU (for example with a fragment shader or compute shader) so you can push the grid size and particle count much higher
Add sound effects that react to events: a crackle for fire, a whoosh for launch, a boom for each firework burst

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Just Four Days Left To Enter The Ready, Spec, Ship Hackathon!

John Crickett — Wed, 19 Aug 2026 08:02:04 GMT

Hi All,

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

I just wanted to remind you there are just 4 days left to enter and submit to the Ready, Spec, Ship Hackathon.

If you’ve been thinking about entering, now’s the time to stop polishing the idea and start shipping the project.

You can enter solo or as a team of up to three people, and you can submit more than one project.

All verified entries receive free Kiro credits to use during the hackathon, and there’s a $9,600 prize pool across the top three projects.

🥇 $5,000 cash + 12 months of Kiro Pro Max
🥈 $1,000 cash + 12 months of Kiro Pro Max
🥉 12 months of Kiro Pro Max

Your project doesn’t need to be perfect. It needs to be submitted.

I’ve been building my screen recording tool alongside everyone, and the deadline has been a great push to keep making progress. I’ve also taken a detour along the way to submit a couple of PRs to Kiro’s new Kiro Crew tool which has become a favourite of mine.

📅 Submission deadline: 23 August midnight UTC
🏆 Winners announced: 6 September

Submit here:
https://codingagents.fyi/hackathon/kiro/

Four days. Build, finish, submit. 🚀

It’s a great chance to checkout the Kiro agentic coding environment!

I hope to see you taking part.

Please let me know if you have any questions.

Regards, John

P.S. You can read about Kiro Crew here: https://kiro.dev/crew/

Coding Challenge #131 - Automated Code Review Agent

John Crickett — Sat, 15 Aug 2026 08:01:51 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #131 - Automated Code Review Agent

This challenge is to build your own automated code review agent that reviews every pull request against your team’s coding guidelines and posts what it finds back as a comment.

This challenge was created in collaboration with Kestra, an open source orchestration platform where workflows are written as YAML and run anywhere, including on-premise and air-gapped environments. If you want a sense of where the first few steps are heading, their AI GitHub PR Review blueprint is a compact example of the idea, though you’ll be building well past it.

It’s relatively easy to write a script to review code with an LLM. Grab the diff, send them to a language model with a list of your team’s rules, and post the feedback as a comment. It takes an afternoon and it feels like magic. Then reality hits. The model provider rate limits you and the review silently disappears. Two people push at the same time and the bot posts three contradictory comments. Someone opens a 4,000 line pull request and the whole thing falls over. Worst of all, the bot starts confidently complaining about code that is perfectly fine, because all it can see is the diff and it has no idea what the rest of the file looks like.

In this challenge you’ll start with exactly that fragile script, and then rebuild it robustly. You’ll turn it into a declarative workflow with retries, event triggers and concurrency control. You’ll teach it to handle large pull requests, to run real static analysis tools instead of guessing, and finally to go and look things up for itself.

The Challenge - Building Your Own Automated Code Review Agent

You’re going to build a code review agent that watches a repository, reviews every pull request that opens, and posts its findings as a comment. It will survive a provider outage, cope with a pull request that touches sixty files, and ground its opinions in the output of real linters rather than vibes.

You don’t need deep experience with any particular language, because most of what you build will be YAML workflow definitions plus a small amount of scripting. What it does ask for is patience with real world plumbing: API tokens, webhooks, containers, and the awkward gap between something that works on your machine and something that works every time.

The fun parts are not the AI bits. Getting a model to write a code review is easy. The fun parts are everything that stops it being a demo project: what happens when the API call fails, what happens when three events arrive at once, and what happens when the diff is bigger than the context window?

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

You’ll need three things before you start.

First, a GitHub personal access token with permission to read pull requests and write comments on a repository you own. Keep it somewhere safe, you’ll be using it throughout.

Second, an API key for a language model provider. Any of the big ones will do to begin with, and later in the challenge you’ll deliberately swap between several, so pick whichever is quickest for you to get started with today.

Third, and most importantly, something to review. A code reviewer is only as testable as the code you point it at, so you want a pull request where you already know what a good review would say.

I’ve put one together for you at ReviewMe. It’s a small Python checkout service, and every flaw in it is deliberate. Fork it, and you’ll find two pull requests waiting. The big one, which adds refund ratios and a reporting pack, is the one you’ll use for almost every step. It contains, on purpose:

A live-looking Stripe key committed straight into app/config.py. Your reviewer should always catch this one.
A rewritten calculate_discount in app/pricing.py with conditionals nested five levels deep. Your reviewer should suggest early returns.
A new ratio = amount / order.total line in app/orders.py that looks like a division by zero waiting to happen. It isn’t, because the only caller guards against it, but that caller lives in app/checkout.py which this pull request does not touch. This one is a trap, and it matters much later.
A regenerated uv.lock with several hundred changed lines.
A rewritten app/report.py of around 650 lines.
An updated test file covering the pricing changes.

The second pull request just fixes a spelling mistake in a comment. You’ll want that one in Step 4.

If you’d rather build your own, do, just create the same six issues.

You’ll also want Kestra running locally. It ships as a Docker image and the quickstart will get you to a working UI, though you won’t need it until Step 2. Alternatively it’s an open source project you can download from Kestra’s GitHub.

Testing: Confirm your credentials work before writing anything substantial. Fetch the pull request with a single request to https://api.github.com/repos/{owner}/{repo}/pulls/{number}/files, using your token as a bearer token. You should get back a JSON array with one entry per changed file, each containing a patch field with the diff. If you get a 401 or an empty array, fix that now rather than debugging it later through three layers of workflow.

Step 1

In this step your goal is to build the fragile version, the one you’ll spend the rest of the challenge replacing.

Write a single script, in whatever language you like, that takes a repository owner, a repository name and a pull request number, fetches the list of changed files from the GitHub API, sends the diff to your language model along with a handful of review guidelines, and prints the review to your terminal. Read both the GitHub token and the model API key from environment variables. Don’t post anything to GitHub yet, just print it.

Keep this deliberately small. It should be well under a hundred lines. The point is not to build something good, it’s to have a working baseline and to prove your credentials and your prompt both do what you expect.

Once it runs, write down everything it doesn’t do. Mine looked like this: if the API call gets rate limited the review is simply lost, there is no record anywhere that it ran, the only way to trigger it is to run it by hand or put it on a cron job and hope, and if it produces nothing useful there is no way to find out why. Keep that list. Every remaining step in this challenge addresses one of the items on it.

Testing: Run your script against the refund and reporting pull request from Step Zero. You should get a review printed to your terminal that mentions the Stripe key sitting in app/config.py. If it doesn’t spot that, your prompt needs work before you go any further, because everything after this depends on the review being worth reading.

Now break it on purpose. Set your model API key to an invalid value and run it again. Notice what you get: probably a stack trace, and definitely no review.

Step 2

In this step your goal is to get the same pull request data flowing through a workflow instead of a script.

Get Kestra running locally and create a namespace for your work. Kestra organises flows into namespaces the way a filesystem uses directories, so something like company.reviews is fine.

Now build your first flow. It should take the repository owner, the repository name and the pull request number as inputs, so you can type them into the UI and hit execute. It should fetch the pull request’s changed files, and it should log what came back. Kestra has an HTTP request task for this, and templating that lets you drop input values into a URL.

Once that works, add a second fetch for the pull request itself, at /repos/{owner}/{repo}/pulls/{number}, which gets you the title and description. The author’s own explanation of what they were trying to do are often some of the most useful context you can give a reviewer, human or otherwise.

Don’t add the model yet. This step is about getting comfortable with the shape of a flow, and about the fact that you can now see every execution, its inputs, its outputs and its logs, in a UI. That’s the first item off your Step 1 list gone.

Testing: Execute the flow from the UI with your fork’s owner, name and pull request number. Open the execution in the UI, click through to the task outputs, and confirm you can see the diff for each changed file and the pull request title. Execute it a second time and confirm both runs appear in the execution history with their inputs recorded.

Step 3

In this step your goal is to turn the diff into an actual review.

Add a task that sends the diff and the pull request metadata to a language model. Kestra’s AI plugin has a chat completion task that takes a provider, a model and a list of messages, so you can point it at whichever provider you set up in Step Zero.

There are two key things here. First is the system prompt: tell the model it is an engineer reviewing a pull request, and be specific about what you want back. Ask for a Summary, an Issues Found section where every issue is tagged CRITICAL, MAJOR or MINOR, a Suggestions section, and a Verdict. Structure matters more than you’d think, because in a few steps you’ll be merging several of these together and sorting them by severity.

The second is the guidelines. Take them as a flow input rather than burying them in the prompt. Your team’s coding standards will change, and the people who want to change them are often not the people who are comfortable editing a workflow. Making the rules an input rather than part of the code is a small decision that pays off every time someone asks for a new rule.

Testing: Run the flow against the pull request. The review should come back in the structure you asked for, with the Stripe key tagged CRITICAL and the nesting in calculate_discount showing up as at least a MINOR issue.

Now change the guidelines input without touching the flow. Remove the rule about nesting and add one demanding that every function has a docstring. Run it again. The nesting complaint should disappear, and you should not have edited a single line of the flow to make that happen.

Step 4

In this step your goal is to close the loop and get the review onto the pull request.

Add a final task that posts the review as a comment, using the GitHub issues comments endpoint. Pull requests are issues as far as that part of the API is concerned, so the URL is /repos/{owner}/{repo}/issues/{number}/comments.

While you’re here, stop passing your tokens around in plain sight. Kestra has a secret() function for this. One thing that catches people out: in the open source edition, secrets come from environment variables prefixed with SECRET_, and the value has to be base64 encoded. If you paste a raw token in, you’ll get a confusing failure rather than a clear one, so encode it first.

Finally, add one small piece of judgement. If the review found no issues at all, log that fact and skip posting. A bot that comments “looks good to me” on every single trivial pull request gets muted fast, and a muted bot is worth nothing.

Testing: Run the flow and check the pull request on GitHub. The review should be there as a comment, readable, with its headings intact.

Then test the quiet path. Run the flow against the second pull request, the one that fixes the spelling mistake in a comment. Nothing should be posted, and the execution log should tell you why it chose not to. If your reviewer manages to find a CRITICAL issue in a corrected spelling, your prompt is being far too eager and that will only get worse from here.

Step 5

In this step your goal is to make the choice of model a detail rather than a decision.

Right now your flow is welded to one provider. Change the provider on your completion task to a different one, Anthropic or Google Gemini or OpenAI, whichever you didn’t use in Step 3, and run the same pull request through again. You’ll need a second API key, and you should not need to touch anything else in the flow. Three lines change. The fetching, the prompt, the posting and the skip logic all stay exactly as they are.

Then do something more interesting. Point it at a model running locally on your own machine via Ollama and run the review again with no outbound calls to any commercial API at all. This is the version that can run inside a bank or a defence contractor, and being able to switch to it by editing three lines is the whole argument for keeping your orchestration separate from your model.

While you’re doing all this, record the token usage and the completion task reports for each provider on the same pull request, alongside how long each one took. You now have a cost comparison based on your own code rather than someone’s pricing page.

Testing: Run the identical flow against the same pull request with at least three different providers, including a local model. All three should produce a usable review that catches the Stripe key.

Compare them. Note the token counts, the wall clock time, and where the reviews disagree. The local model will likely be slower and less sharp. Decide for yourself whether it’s good enough, because that’s a real decision teams have to make.

Step 6

In this step your goal is to stop running the review by hand.

Replace manual execution with a webhook trigger, and point a GitHub webhook at it so that opening a pull request runs the review automatically. Secure the trigger with a key, otherwise anyone who finds the URL can make your workflow burn tokens on their behalf.

If you’re running Kestra locally, GitHub can’t reach you directly. A tunnelling tool such as ngrok will give you a public URL that forwards to your machine, which is fine for the length of this challenge.

Two bits of care are needed here. GitHub sends a lot of events to that webhook, so your flow should act on opened, reopened and synchronize, and quietly ignore everything else. Somebody adding a label should not trigger a code review.

The second is more subtle, and it’s the reason this step and the next are separate. synchronize fires on every single push. If someone pushes three quick fixes in a row, you’ll get three reviews running at once, all posting comments, at least two of them already out of date by the time they land. Set a concurrency limit on the flow so that only one review of a given pull request runs at a time, and choose what happens to the ones that arrive while it’s busy. Cancelling them is usually right for code review, because a review of the final state is worth more than three reviews of states nobody will ever look at again.

Testing: Push a new commit to the pull request and watch the execution start on its own. The comment should appear on GitHub without you touching anything.

Then try to break it. Push three commits in quick succession. You should end up with one review, not three. Check the execution list and confirm you can see the ones that were cancelled and why.

Finally, add a label to the pull request. Nothing should happen at all.

Step 7

In this step your goal is to make the workflow survive a bad day.

Add retries to the tasks that talk to the outside world. Both the GitHub API and every model provider will rate limit you eventually, and a single 429 should not mean a lost review. Three attempts with an increasing delay between them handles the overwhelming majority of real failures.

Add a timeout to the model call. Providers occasionally accept a request and then simply never answer, and without a timeout your execution will sit there indefinitely looking like it’s working.

Then handle the case where it genuinely fails anyway. Add error handling to the flow that posts a short notice to Slack or Discord when a review fails, including the execution ID so you can go straight to the logs. This is the difference between a system you trust and a system you have to check on. Without it, a broken review looks exactly the same as a pull request nobody bothered to review, and you won’t find out for weeks.

Testing: Set your model API key to an invalid value and push a commit. The flow should retry, fail cleanly, and you should get a notification containing the execution ID. Follow that ID back to the logs and confirm you can see exactly what went wrong.

Restore the key and confirm normal service resumes. If you can, test the retry path properly by pointing a task at an endpoint that returns a 429 and watching the attempts in the logs with the delay growing between them.

Step 8

In this step your goal is to handle a pull request that is too big to review in one go.

Right now you send the entire diff to the model as a single prompt. That works fine for the small pull requests you’ve been testing with and falls apart on a real one. Change your flow so that it reviews each changed file separately and in parallel, rather than concatenating everything into one enormous prompt.

That immediately raises the question of which files are worth reviewing at all. Nobody wants an AI review of a lockfile. Skip files that are generated, vendored or locked. Whatever you skip, say so in the output. A reviewer that silently ignores half the pull request is worse than no reviewer, because you’ll trust it.

Then put it back together. Merge the per file reviews into a single comment, ordered with the most severe issues first, so that a reader sees the CRITICAL finding at the top rather than four paragraphs down under a MINOR note about naming. One comment, not one per file.

Testing: Run it against the pull request, which has uv.lock, it should be skipped, and the comment should say so and say why. The remaining files, config.py, orders.py, pricing.py and the tests, should each have been reviewed.

Check the execution graph in the UI. You should be able to see the per file reviews running side by side rather than one after another. Compare the total time to what it took in Step 4 and note the difference.

Step 9

In this step your goal is to stop your reviewer guessing about things a tool can simply know.

A language model asked to spot an unused import is doing an expensive impression of a linter, and it is worse at it. So run the real thing. Clone the repository at the pull request’s head commit, run a static analysis tool appropriate to the language, and capture what it finds. ReviewMe is Python and already set up for ruff, so uv run ruff check . will do it. If you built your own fixture in another language, eslint or semgrep will get you to the same place.

Run that tool inside a container rather than installing it on the machine running Kestra. Kestra’s task runners exist for exactly this: the linter, its version and its dependencies live in a Docker image, and your workflow stays clean. This also means your reviewer can handle a repository in a language nobody on your platform team has installed locally.

Then feed the findings into the review prompt, and change your instructions. Tell the model to report the tool’s findings as fact, and to spend its own commentary on the things a linter fundamentally cannot judge: whether the change matches the author’s stated intent, whether the naming makes sense, whether the approach is sound. This is the division of labour that makes automated review actually useful. Deterministic tools for deterministic problems, and the model for the judgement calls.

This is the longest step in the challenge, mostly because getting a repository checked out and a container running takes more fiddling than the rest. Give yourself a bit of time.

Testing: Run it against the pull request. The comment should now contain findings that are clearly attributable to the linter, reported precisely with file and line numbers, alongside softer commentary from the model.

Push a violation your linter definitely catches, an unused variable is ideal, and confirm it appears in the review with the exact line number. Then check the model isn’t taking credit for it or quietly contradicting it. If the two disagree, your prompt needs to be firmer about which one wins.

Going Further

Once you have the core reviewer working, here are some ideas to take it further:

Post inline comments on specific lines using GitHub’s review API, rather than one summary comment at the bottom.
Have the reviewer reply to itself when a new commit fixes something it flagged earlier, so a pull request shows the issue being resolved rather than repeated.
Keep a record of every review, its token cost and its verdict, and build a dashboard showing what your reviewer costs per month and which rules fire most often.
Backfill the last fifty merged pull requests and compare your agent’s findings to the comments humans actually left. This is the honest evaluation, and it will be humbling.
Split the workflow into a reusable subflow that any repository in your organisation can call with its own guidelines, rather than copying the flow around.
Keep your flows in Git and deploy them through CI, so the reviewer is itself code reviewed.
Add support for GitLab or Bitbucket by swapping the fetch and post tasks, keeping everything in between identical.
Give teams their own namespaces and access controls, so the security team can edit review guidelines without being able to change the workflow itself.

P.S. If You Enjoy Coding Challenges Here Are Four Ways You Can Help Support It

Refer a friend or colleague to the newsletter. 🙏
Sign up for a paid subscription - think of it as buying me a coffee ☕️ twice a month, with the bonus that you also get 20% off any of my courses.
Buy one of my courses that walk you through a Coding Challenge.
Subscribe to the Coding Challenges YouTube channel!

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #130 - Sort Visualiser

John Crickett — Sat, 08 Aug 2026 08:01:19 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #130 - Sort Visualiser

This challenge is to build your own sorting algorithm visualiser, a tool that animates how common sorting algorithms operate on an array of values.

Sorting is one of the first topics every programmer meets, and it’s a topic many of us never properly see. We learn that quick sort is faster than bubble sort, that merge sort divides and conquers, that heap sort uses a clever tree structure, but the names blur together until you watch them work.

A visualiser turns each algorithm into a little dance: bars or numbers shuffling, settling, and finally clicking into order. Once you’ve watched insertion sort sweep across a nearly-sorted array, or seen quick sort partition a chaotic mess into neatly halved buckets, the differences between the algorithms become intuitive in a way no Big-O table can match. Building the visualiser yourself is even better, you’ll gain a deep, hands-on understanding of eight classic algorithms and pick up some practical skills around UI rendering, animation timing, and clean abstractions along the way.

Win 💰💰💰 - Join The Ready, Spec, Ship Hackathon I’m Running!

I’m pleased to be hosting the Ready, Spec, Ship Hackathon alongside Angie Jones, and; and sponsored by Kiro. You can enter solo or as a team of up to three people, and you’re welcome to submit more than one project.

There’s a $9,600 prize pool to be won, plus 2000 FREE Kiro credits for every verified entry. Submissions close on 23 August, with the winners announced on 6 September.

Find out more and take part:https://codingagents.fyi/hackathon/kiro/

It’s a great chance to checkout the Kiro agentic coding environment!

OK, on with the coding challenge!

The Challenge - Building Your Own Sorting Visualiser

In this challenge you’re going to build a tool that animates a sorting algorithm at work on an array of values. By the time you’re done, your tool will support eight classic algorithms: bubble, insertion, selection, merge, quick, heap, shell, and radix. And let the user pick the algorithm, the sample size, the initial order of the data, the display mode, and the animation speed.

Something like this:

You can pick the platform that suits you best. A terminal/CLI implementation (using something like ncurses, blessed, or a similar library) is a great fit if you want to stay close to the keyboard. A browser/web implementation gives you the most flexibility for visuals and is easy to share. A native desktop GUI (using something like Qt, Tauri, GTK, or your language’s standard toolkit) is somewhere in between. Pick the one that interests you every step in this challenge applies to all three.

A small note before we start: you’ll be tempted to just run the algorithm and update the screen at each iteration. That works at first, but quickly tangles your sorting logic with your rendering logic. We’ll structure things so that algorithms produce a stream of events (compared these two indices, wrote this value to that index) and the renderer consumes them. That separation is what’ll make adding new algorithms and new display modes painless later on.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

Choose your target platform, terminal/CLI, browser/web, or native desktop GUI, and the programming language to go with it. I’d encourage you to pick a stack you’re comfortable with for both UI rendering and handling user input, because you’ll be doing plenty of both.

Have a think about how you’ll handle the animation loop. Most platforms have a natural answer, a render loop tied to the frame rate in a browser or a GUI toolkit, a timed redraw in a terminal. Whichever route you take, you’ll want a way to do work, redraw, and pause for a configurable interval between steps.

Step 1

In this step your goal is to render an array of values on screen and watch a single sorting algorithm run end-to-end.

Start by generating an array of, say, 30 random integers. Render each value as a vertical bar whose height is proportional to its value, with the bars laid out left-to-right across the screen. Don’t worry about colours, controls, or configuration yet, get the rendering working first.

Now implement bubble sort and animate it. After every comparison and every swap, redraw the array and pause for a short delay (something like 50–100 ms is a good starting point). When the algorithm finishes, the bars should be in ascending order from left to right.

This is your end-to-end skeleton. Everything else in the challenge will hang off this foundation.

Testing: Run your tool and watch the array sort itself. The bars should start in random order and finish in ascending order. Try a few different sample sizes (10, 30, 50) and confirm the layout still looks right. If your bars overflow the screen or look squashed, adjust your scaling so the tallest bar uses most of the available height.

Step 2

In this step your goal is to highlight what the algorithm is doing right now and show some live statistics.

Up to now your bars have all been the same colour. That makes it hard to see what the algorithm is up to at any given moment. Pick three colours: a resting/idle colour for bars that aren’t being touched, a comparison colour for the two indices the algorithm is currently comparing, and a swap/write colour for indices that are currently being swapped or written. Update your bubble sort so that the right indices are highlighted at the right moment.

Next, add a small statistics overlay somewhere on the screen showing the number of comparisons, the number of swaps/writes, the number of array accesses, and the elapsed wall-clock time. Update these as the algorithm runs so the user can watch the counters tick up.

Finally, when the algorithm finishes, validate that the array is actually sorted. If it isn’t, surface a clear error, this’ll save you a lot of pain later when you’re implementing trickier algorithms and a subtle bug slips in.

Testing: Run your tool and confirm the highlighted bars match what bubble sort is doing, the two compared bars should light up in the comparison colour, and when a swap happens you should see the swap colour. Watch the stats counters and sanity check them: for a small array, count a few comparisons by eye and confirm the counter agrees. At the end of the run, deliberately break the algorithm (e.g. comment out the swap) and confirm your validation catches it.

Step 3

In this step your goal is to give the user playback controls and a configurable speed.

Right now the visualisation runs straight through from start to finish with no way to pause or replay it. Add controls that let the user start a run, pause it mid-way, resume from where it paused, restart it from the beginning, and step forward by a single operation at a time. The exact bindings are your call, keys in a terminal, buttons in a GUI, both in a web app.

Add a speed control too. Provide at minimum slow, medium, and fast presets, plus a way to set a custom value. Speed can be expressed as a frames-per-second rate or as a delay-per-step, pick whichever feels natural for your platform.

Make sure your controls remain responsive at all speeds. At the fastest preset, it’s tempting to do many algorithm steps per redraw to keep up, but the user still needs to be able to hit pause and have it actually pause. Test that.

Testing: Start a run, pause it half-way through, and confirm the bars freeze in place with the comparison/swap highlights still visible. Resume and confirm it picks up from where it left off. Hit restart and confirm the array goes back to its original state and the stats reset to zero. Use the step control to advance one operation at a time and watch the comparison/swap highlights move with each press. Try the fast preset and confirm pause still responds promptly.

Step 4

In this step your goal is to refactor bubble sort behind a clean algorithm interface, then add two more algorithms.

So far your sorting code and your rendering code are probably mixed together. We’re going to separate them. Define an interface for a “sortable run”, something that, given an array, produces a stream of events describing what the algorithm is doing. The two essential events are compared these two indices and wrote this value to that index. A generator (or coroutine, or async iterator, depending on your language) is a natural fit: each yield is one event, and the renderer pulls events out one at a time.

Refactor your bubble sort to fit this interface. Your renderer should now consume events from the algorithm rather than calling sort logic directly. The stats counters become trivial to maintain, every comparison event increments the comparison counter, every write event increments the write counter, and so on.

With the interface in place, add insertion sort and selection sort. Each one should be its own implementation of the interface, with no changes needed to your renderer. Add an algorithm selector to your UI so the user can pick which one to run.

Testing: Run each of the three algorithms on the same input and compare. Bubble sort should swap adjacent elements; insertion sort should sweep one element at a time into its correct place in the sorted prefix; selection sort should make far fewer swaps but lots of comparisons. The stats counters should reflect the differences, selection sort, for example, will show roughly the same number of comparisons as bubble sort but far fewer writes.

Step 5

In this step your goal is to add merge sort, quick sort, and heap sort.

Each algorithm should slot into the same algorithm interface you defined in Step 4. If the interface is right, your renderer shouldn’t need any changes, every algorithm is just a different sequence of comparison and write events.

A small word on merge sort: because it uses an auxiliary array, you’ll need to decide how to represent writes back into the main array. The simplest approach is to emit a write event for each element placed back into the main array during the merge. The user will see the array reform piece by piece as the merges complete, which is exactly the behaviour you want.

Testing: Run each of the three algorithms and watch them. Merge sort should produce the classic “halves coming back together” pattern. Quick sort should show pivots being placed and partitions taking shape. Heap sort should show a chaotic phase (heap construction) followed by an orderly phase (extracting the max from the back of the array). Confirm the correctness check from Step 2 passes for all three on a variety of input sizes.

Step 6

In this step your goal is to add shell sort and radix sort.

Radix sort is the odd one out. It’s not comparison-based, it sorts by repeatedly distributing values into buckets based on individual digits. You’ll need to decide how to express what radix sort is doing through your event stream. One approach is to emit write events as values move from the array into the buckets and back. Another is to extend your event vocabulary with something like a bucketed this value event. Either is a reasonable design choice, the goal is for the viewer to be able to see the algorithm working.

Testing: Run shell sort and watch how the array goes from chaotic to “fairly ordered” to fully sorted as the gap shrinks. Run radix sort on a fixed-width integer array and confirm it sorts correctly. Compare radix sort’s stats counters to the comparison sorts, radix sort should have zero comparisons (or very few, depending on how you count) and a number of writes proportional to the number of digits times the array size.

Step 7

In this step your goal is to add the numbers display mode behind a pluggable rendering interface.

Up to now everything has been bars. The numbers display mode renders each value as a small labelled tile or box showing the numeric value, laid out in a row. When two indices are being compared or swapped, the corresponding tiles should be visually lifted or separated from the main row so the active operation is unambiguous, with the comparison/swap colours from Step 2 applied.

That should look something like this:

Just as you separated algorithms from rendering in Step 4, now separate the bars renderer from a generic rendering interface. Each renderer should accept the same array and event stream and decide how to draw it. Adding the numbers renderer should not require changes to any of the algorithms.

Add a display mode selector to your UI so the user can switch between bars and numbers.

Testing: Run each of your eight algorithms in numbers mode and confirm the lift behaviour matches what you expect, when bubble sort compares two adjacent elements, those two tiles should lift; when it swaps them, both should be highlighted in the swap colour. Switch between bars and numbers mid-run if you can; the algorithm should keep running and just the rendering should change.

Step 8

In this step your goal is to add sample size and sample order configuration, polish the user experience, and finish the documentation.

Add controls that let the user select the sample size (the number of elements in the array, with sensible minimum and maximum bounds for your platform) and the initial sample order. Support at least three orders: random, reversed, and already sorted. When the user restarts a run, regenerate a fresh sample of the configured size and order, except for already sorted, which is deterministic by definition. This means consecutive runs of the same algorithm exercise different inputs.

Show the current configuration on screen at all times: the chosen algorithm name, the sample size, the sample order, and the display mode. The user should never have to wonder what they’re looking at.

When a sort completes, present a clear “sorted” state. A nice touch is a final sweep through the array, a brief animation where each element is briefly highlighted in turn, left to right, to confirm visually that everything is in order. Freeze the final stats so the user can read them.

Finally, write a short README documenting how to run your tool, how to choose between platforms (if you’ve implemented more than one), and, importantly, how a future contributor would add a new algorithm or a new display mode. If your interfaces from Steps 4 and 7 are clean, this should be easy to write. If it’s hard to write, that’s a signal that the interfaces could be better.

Testing: Try every combination of configuration: each algorithm, each sample size from your minimum to your maximum, each sample order, each display mode. Confirm the on-screen configuration always matches what you’ve selected. Confirm that two consecutive runs of bubble sort with random order produce different starting arrays, but two consecutive runs with already sorted order produce the same one. Watch the completion sweep at the end of a run and confirm the stats freeze on the final values. Hand your README to a friend and ask them to add a hypothetical “cocktail sort” algorithm; if they can do it without reading your renderer code, you’ve nailed the abstraction.

Going Further

Here are some ideas to take your sorting visualiser further:

Add more algorithms: cocktail sort, comb sort, gnome sort, Tim sort, intro sort, or even bogo sort for fun.
Add a head-to-head mode that runs two algorithms side-by-side on the same input array, so the user can race them.
Add an export-to-video or export-to-GIF option so users can share their favourite runs.
Build an algorithm-comparison view that runs every algorithm across a range of sample sizes and plots comparisons or writes against input size, giving a visual confirmation of each algorithm’s Big-O behaviour.
Visualise additional algorithm-specific metadata: recursion depth for merge and quick sort, the heap structure for heap sort, or the gap sequence for shell sort.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Join the Ready, Spec, Ship Hackathon Hackathon

John Crickett — Tue, 04 Aug 2026 15:03:54 GMT

Hi All,

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

I’m pleased to be hosting the Ready, Spec, Ship Hackathon alongside Angie Jones, , and sponsored by Kiro. You can enter solo or as a team of up to three people, and you’re welcome to submit more than one project.

There’s a $9,600 prize pool, plus 2000 FREE Kiro credits for every verified entry. Submissions close on 23 August, with the winners announced on 6 September.

Find out more and take part:
https://codingagents.fyi/hackathon/kiro/

It’s a great chance to checkout the Kiro agentic coding environment!

I hope to see you taking part.

Please let me know if you have any questions.

Regards, John

Coding Challenge #129 - Coding Challenges Coach

John Crickett — Fri, 31 Jul 2026 08:02:05 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #129 - Coding Challenges Coach

This challenge is to build your own AI coaching agent that helps developers learn by working through the Coding Challenges projects.

We’ve all wished for a patient mentor who sits with us while we learn: someone who helps us pick the right thing to work on, talks through our approach, lets us run our code, and remembers where we got to last time. In this challenge you’ll build exactly that, an AI coaching agent built with Google’s Agent Development Kit (ADK) and the Gemini Enterprise Agent Platform.

You’ll start with a small prototype running on your own machine, then progressively harden it into a production-ready service that runs on Google Cloud, tracks its own costs, watches its own behaviour, and passes a security audit. This coding challenge is all about the process of taking a demo through to something you’d be happy to run for real.

This project is kindly sponsored by Google Cloud.

The Challenge - Building Your Own Coding Challenges Coach

You’re going to build a coaching agent that can hold a conversation with a developer, help them choose a Coding Challenge that suits their interests and skill level, reads the challenge specifications, searches the web for extra context, runs and tests the developer’s code in a safe sandbox, and remembers the whole journey so they can stop and come back later. Then you’ll take that agent and turn it into a proper cloud service: deployed, identified, secured, costed, and observed.

This is a challenge that’s aimed at engineers who are comfortable writing code and now want to learn what it takes to build and operate an AI agent responsibly. Going from a local prototype through to a hardened, audited production service. The core skills here, working with an agent framework, wiring up tools, managing state, deploying to the cloud, and thinking about security and cost, transfer to any agent platform. We’ll use the Google stack throughout because it gives us a complete, coherent path from prototype to production, all driven from local CLI tools.

The interesting and tricky parts are in the second half. Getting an agent to chat is easy. Giving it tools it can safely run, making it remember the right things without repeating itself, deploying it without a single static credential in sight, keeping its costs under control, and proving to an auditor that it’s secure, that’s where the real learning is.

Each step below covers one whole area of the agent, so treat a step as a mini-project of its own rather than a quick hour of work. Get each area solid before you move on, because the later steps build directly on the earlier ones.

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

This challenge uses Google’s Agent Development Kit, you can find installation instructions here: ADK Installation. You’ll also need a Google Cloud account and the gcloud CLI, because the later steps deploy to and lean on Google Cloud. Installation instructions for the gcloud CLI are here.

Everything you do will run from your local command line, so get comfortable with the adk CLI commands (adk run, adk web, and adk deploy).

It’s also worth spending some time reading through the ADK documentation so you understand the core building blocks: agents, tools, and the runtime. Have a look at how the built-in Dev UI works, as that’s where you’ll do most of your local testing.

Finally, gather a handful of Coding Challenge specification files to coach against. Grab two or three challenge descriptions and save them locally as markdown, JSON, or YAML files in a folder your agent will be able to read. These are your test data for the rest of the challenge.

Testing: Confirm your environment is ready by creating an empty starter agent and launching the Dev UI:

adk web

You should be able to open the Dev UI in your browser and see your agent listed, ready to chat, even if it doesn’t do anything useful yet:

Step 1

In this step your goal is to build a coaching agent that runs entirely on your machine and helps a developer choose a Coding Challenge through conversation.

Using the ADK, create an agent that holds a natural-language conversation, asking about the developer’s interests, what they want to learn, and their experience level, then recommending a challenge that suits them. Give the agent a clear coaching persona through its ADK configuration, including a system prompt that makes it behave like a mentor: encouraging, Socratic, and focused on guiding the developer to the answer rather than handing it over. All of your development and testing at this stage should happen locally through the ADK Dev UI. You’ll find some Google ADK examples to build on here.

Check out the previous coding challenge, building an AI-powered chatbot for some guidance on creating this agent and setting the persona via the system prompt.

Testing: Run your agent with adk web and open the Dev UI. Tell the agent you’re a beginner interested in networking and confirm it asks sensible follow-up questions and recommends a suitable challenge. Try again as an experienced developer wanting to learn about databases and confirm it recommends something more advanced. Then ask it to “just give me the full solution” and confirm it declines politely and offers hints or questions instead of the answer.

Your ADK session should look something like this:

And your agent should refuse to provide the full solution:

Step 2

In this step your goal is to give your agent tools so it can ground its coaching in real information rather than guessing.

Implement a custom tool that reads Coding Challenge specification files (markdown, JSON, or YAML) from the local filesystem and returns the content relevant to the developer’s question.

Implement a second tool that performs a web search using an external search API of your choice, so the agent can find extra context, documentation, or alternative approaches when the developer is stuck. Bind both tools to the agent so it can chain them together within a single turn, for example reading the relevant part of a challenge spec and then searching the web for a related concept before it replies.

When building agents there’s a fine line between providing too few tools, reducing the agent’s flexibility, and too many tools, resulting in the agent picking the wrong tool. If several tools are likely to be used in the same order repeatedly, see if you can build a workflow or a composite tool, this saves both time and tokens.

For guidance, refer to the ADK docs on building a multi-tool agent.

Testing: In the Dev UI, ask a question about one of your saved challenge specs, for example “what does step 3 of this challenge ask me to do?”, and confirm the agent reads the file and answers from its real content. Ask something not in your specs, for example “what’s a good library for parsing this format?”, and confirm it runs a web search. Finally ask a question that needs both, for example “I’m on step 2, what background reading would help?”, and confirm you can see both tool calls in the trace, the spec read first and the search second, in a single turn.

Step 3

In this step your goal is to give your agent a safe place to run the developer’s code, in more than one language.

ADK handles code execution through the BaseCodeExecutor interface, and ships a GkeCodeExecutor that runs each snippet in a gVisor-sandboxed, ephemeral GKE workload. Every run should get a fresh, isolated container from a custom image with Python, Node, and Go toolchains installed. The tool should write the developer’s code into that sandbox, run it, and return the standard output, standard error, and exit code. Support at least Python, JavaScript, and Go, with the agent choosing the language from the challenge context or the developer’s stated preference.

Testing: In the Dev UI, ask the agent to run a small snippet that prints something and exits cleanly, and confirm you get the output and an exit code of 0. Give it code that raises an error and confirm you see the error on standard error and a non-zero exit code. Run a “hello world” style snippet in each of Python, JavaScript, and Go and confirm each runs in the right language. Tell the agent you’re on a Go challenge, give it a Go snippet without naming the language, and confirm it picks Go.

Step 4

In this step your goal is to let your agent run tests and coach the developer through the results, while keeping execution under control.

Allow the agent to run a test suite against the user’s code, report which tests fail, and coach the developer through debugging, helping them understand and fix the problem themselves rather than rewriting the code for them. Add safety limits to every execution: a timeout, defaulting to 30 seconds, and a maximum output size, defaulting to 64 KB, both configurable, so a runaway process or a flood of output can’t disrupt the session. You’ll have to provide a way for the user’s code to reach the agent.

Testing: Give the agent code with a known bug and a test that catches it. Confirm it runs the tests, reports the failure clearly, and responds with guiding questions rather than the corrected code, even when you ask it to “just fix it”. Then give it code with an infinite loop and confirm execution is cut off at the timeout with a clear message. Give it code that prints a huge amount of output and confirm the returned output is capped. Change the limits in your configuration and confirm the new values take effect.

Step 5

In this step your goal is to let a developer stop mid-challenge and pick up later, without the agent losing the thread or repeating itself.

Persist the conversation state using Session service and also enable the Memory Bank (VertexAiMemoryBankService) so a session can be paused and resumed. The Session service will capture which challenge the developer is working on, the code they’ve written, the coaching advice they’ve already been given, and which concepts have been covered. The Memory Bank will consolidate related memories across sessions so that user preferences are stored and as the notes accumulate the agent merges overlapping ones and avoids giving the developer the same advice twice.

Testing: Have a session where you pick a challenge, write some code, and receive a couple of pieces of advice, then end it. Start a fresh session and confirm the agent remembers which challenge you’re on and refers back to your earlier code and advice rather than starting over. Across two or three sessions, steer it towards giving the same category of advice and confirm that by the later sessions it recognises it has already covered this and builds on it instead of repeating it.

Step 6

In this step your goal is to take your local agent and run it as a proper cloud service, still driven from your local repository, now easily running on the cloud.

Use adk deploy to deploy the agent from your local ADK project to the Google Cloud Agent Runtime, keeping your local repository as the single source of truth. Configure the deployment to use Gemini models served from Agent Runtime rather than a local or third-party API key. Expose the deployed agent through a public HTTPS endpoint, and set up continuous deployment so that pushing changes from your local repository automatically updates the running agent.

Testing: Deploy with adk deploy and confirm it succeeds. Call the agent’s public HTTPS endpoint from your machine, for example with curl, and confirm you get a valid response over HTTPS using the Gemini models served from Agent Runtime, with no local or third-party model API key in the configuration. Make a small change locally, push it, and confirm the deployed agent updates without you running a manual deploy.

Step 7

In this step your goal is to give your deployed agent a real identity, so you can both restrict what it reaches and attribute everything it does, with no static credentials anywhere.

To do this, look into deploying to Agent Runtime with Agent Identity enabled.

Testing: Confirm the deployed agent can still read specs, run searches, and execute code using its SPIFFE identity (A SPIFFE identity is a secure, cryptographically verifiable identifier assigned to specific software services (workloads) rather than machines - you can learn more on the SPIFFE website), and that there are no static API keys or long-lived credentials anywhere in the deployment.

Enable Data Access audit logs on the specs storage, run a full session, then filter Cloud Audit Logs by the agent’s principal and confirm the spec read, the search, and the sandbox execution all appear under the same SPIFFE ID.

Deploy a second agent and confirm its actions carry a different SPIFFE ID, so you can separate the two agents’ activity from the logs alone.

Capture a valid token and try to use it from a different workload without the agent’s certificate, and confirm it is rejected while the agent’s own requests still succeed. Through the agent’s identity, try to reach a Google Cloud resource it shouldn’t need and confirm access is denied, and that the denial is recorded against the agent’s identity in the audit log.

Step 8

In this step your goal is to prove your hardening actually holds up, by passing an audit.

Build and run a mock third-party security audit against your deployment: a script that only ever reads, the same posture a real external auditor without console access would take. Check for static credentials confirming zero user-managed keys. Check for over-permissive IAM roles, flagging anything broader than the least-privilege set you defined in Step 7. Check for unencrypted state storage. Check for exposed debug endpoints by probing your deployed HTTPS endpoint for known debug paths, such as the ADK Dev UI routes, /docs, and /openapi.json, and confirming each returns 404 or 401 rather than 200. Your agent should pass all four checks.

Testing: Run your audit and confirm it reports a clean pass on all four checks. Then deliberately introduce a problem, for example add a static credential or open up an IAM role, and confirm the audit catches it and fails. Fix it and confirm the audit passes again.

Step 9

In this step your goal is to make your agent pick the right model for the job and keep its spending under control.

Configure the agent to select models from Model Garden based on task complexity, using a lightweight model for chat and challenge selection and a more capable model for code review and debugging. Because an ADK LlmAgent has a fixed model, structure this as a multi-agent setup: a lightweight coordinator agent that handles the conversation and delegates to a more capable sub-agent (via ADK sub-agents and auto-transfer, or by wrapping it as an AgentTool) whenever the developer needs code review or debugging. This makes the model boundary explicit and keeps each model’s usage cleanly attributable in the trace.

Track token usage per request and per session, and report the cost both in the Dev UI during development and in your production logs. Add a configurable per-session cost cap that gracefully ends a session when it’s reached, telling the developer clearly, rather than quietly running up charges.

Testing: Have a simple challenge-selection conversation and confirm the lightweight model is used, then ask for a detailed code review and confirm the more capable model is used, checking the trace to see which model handled each request. Confirm you can see per-request and per-session cost in the Dev UI and in your production logs. Set a low cost cap, run a session until it’s reached, and confirm the session ends gracefully with a clear message and makes no further billable requests. Raise the cap and confirm the session can continue.

Step 10

In this step your goal is to make your agent’s behaviour visible and to keep its recommendations within policy.

Instrument your agent with OpenTelemetry and export its traces to Cloud Trace, so that each agent interaction becomes a single trace whose child spans capture every model call and tool call, each span carrying the user query, the tool used, the model that served the request, and the token counts.

Finally, implement a governance control that restricts which challenges the agent can recommend based on a configurable policy, for example blocking challenges tagged as “enterprise” or “paid”, and record each policy block as a span event so enforcement is auditable in the trace.

Testing: Run some interactions against your deployed agent, including at least one that triggers an error, then open Cloud Trace and confirm each interaction shows up as a single trace with child spans for its model and tool calls, that the model-call spans carry token-count attributes, and that the errored interaction has a span marked with an error status.

Configure the policy to block a particular challenge or tag, steer the conversation towards it, and confirm the agent won’t recommend it and offers an allowed alternative instead, then confirm the block is recorded as a span event on the trace. Then allow it and confirm the agent will recommend it.

Going Further

Once you’ve built the core coaching agent and hardened it for production, here are some ideas to take it further, ordered roughly from easiest to most ambitious:

Add a richer set of challenge specs and let the coach recommend a learning path across several challenges rather than one at a time.
Add automatic grading that assesses how close a developer’s solution is to passing all the challenge’s testing steps.
Support voice or video coaching modes as well as text.
Add multi-user support and team coaching sessions, with per-user memory and shared team progress.
Let the agent use an alternative sandbox provider and compare its behaviour and cost against the GKE-based executor.
Build a proper front end beyond the Dev UI, tailored to the coaching experience.

Share Your Solutions!

Request for Feedback

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John

Coding Challenge #128 - Mock Interview Coach

John Crickett — Sat, 25 Jul 2026 08:01:05 GMT

Hi, this is John with this week’s Coding Challenge.

🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉

If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧

Coding Challenge #128 - Mock Interview Coach

This challenge is to build your own mock interview coach, a tool that lets you practise behavioural interviews face-to-face speaking to a photorealistic AI interviewer.

Behavioural interviews are the part of the hiring process that engineers practise least. Reading sample STAR answers is nothing like composing one out loud, under time pressure, while someone watches you. In this challenge you’ll build a coach that puts a live, talking interviewer on your screen using Anam’s real-time persona platform and their latest cara-4 model. It will ask you behavioural questions, probe your weak answers with follow-ups, and then score your performance and tell you how to improve. Along the way you’ll work with real-time avatar streaming, persona and prompt design, session-based authentication, and post-session transcript analysis.

This project is kindly sponsored by Anam.

The Challenge - Building Building Your Own Mock Interview Coach

You’re going to build a web application with two halves. The backend, in any language you like, will manage interview setup, issue Anam session tokens, and analyse transcripts to produce feedback reports. The frontend is a thin web page that streams the interviewer’s face and voice into a video element and lets you talk to them over your microphone.

The interesting parts are the persona design (writing a system prompt that makes an AI interview you rather than help you), the security model (keeping your API key server-side while the browser streams in real time), and the feedback loop (turning a raw conversation transcript into a structured STAR assessment).

This is an intermediate to advanced challenge. The backend can be written in any language that can serve HTTP and call a REST API, so pick whatever you’re most comfortable with. The frontend needs only a small amount of JavaScript, so don’t be put off if you’re not a frontend developer.

What you’ll build will look something like this:

Step Zero

In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.

First, sign up for a free Anam account. The free tier gives you API access, 30 minutes of conversation per month, and a 3 minute limit per conversation. That’s enough to complete this challenge, but it does mean each test session is short, so plan to test with brief exchanges rather than full-length interviews.

From your Anam account, create an API key and make a note of it. We’ll be keeping it server-side, so think about how you’ll provide it to your backend, an environment variable named ANAM_API_KEY is the convention we’ll use in this challenge.

Next, pick your backend language and an HTTP server library you’re comfortable with. Then spend a little time with the Anam documentation, particularly the JavaScript SDK quickstart, to understand the moving parts: personas, session tokens, and the streaming client.

Finally, make sure you have a browser with a working microphone and camera permissions you can grant to localhost.

Step 1

In this step your goal is to design your interviewer persona.

A persona on the Anam platform combines a face, a voice, an LLM, and a system prompt. The system prompt is where your coaching product lives, it’s what turns a general-purpose talking avatar into a behavioural interviewer.

Define a persona configuration (name, avatar, voice, LLM, and system prompt) for an interviewer that:

Asks one behavioural question at a time and waits for the answer.
Probes with a follow-up when an answer lacks specifics, for example asking “what was the outcome?” when the candidate doesn’t say.
Never suggests answers or completes the candidate’s stories for them.
Stays in role, politely steering the conversation back to the interview if the candidate drifts off topic.

Getting this behaviour reliable is a prompt engineering exercise, expect to iterate. If you want some great ideas for what to include in the system prompt, check out my interview with Austen McDonald about mastering behavioural interviews. Also check out Austen’s newsletter: Mastering Behavioral Interviews. He also has a guide to doing mock interviews.

Testing: Use the Anam Lab to create the persona and talk to it. Try three conversations: give a vague answer (”we fixed it and it was fine”) and check you get a probing follow-up; ask the interviewer “what would you say in my situation?” and check it declines to answer for you; try changing the subject to the weather and check it brings you back to the interview. The lab is a great no-code option for refining the avatar before you build the full system.

Here’s what it looks like:

Use the prompt tab to enter your prompt, the avatar tab to upload / take a photo of you, the voice tab to clone your voice if you want to. Otherwise pick suitable ones from the existing options.

Step 2

In this step your goal is to build the session token service, the backend half of the security model.

Anam’s streaming sessions are authorised with short-lived session tokens, created by calling POST > with your API key and a persona configuration. The API key must never reach the browser, so your backend will act as the exchange point.

Build a backend with an endpoint that, when called by your frontend, requests a session token from the Anam API using the persona configuration from Step 1, and returns that token to the caller. Read the API key from the ANAM_API_KEY environment variable.

Your endpoint should also apply a time limit to each interview session. Make the limit configurable, and default it to fit inside the free tier’s 3 minute conversation limit.

Testing: Start your backend and request a token from the command line:

curl -X POST

You should get back a JSON response containing a session token. Check your frontend code and browser network tab later in the challenge to confirm the Anam API key itself never appears anywhere client-side. Try setting the time limit configuration to a different value and confirm the session created with the token respects it.

`Step 3`

In this step your goal is to get your interviewer on screen, streaming in real time.

Build a minimal web page, served by your backend, that:

Fetches a session token from the endpoint you built in Step 2.
Creates a streaming client using Anam’s @anam-ai/js-sdk package and attaches it to a video element with streamToVideoElement.
Has controls to start the interview and to end the session at any time.

Once connected, the candidate speaks their answers over their microphone and the interviewer responds with voice and video. Have the interviewer open the session by greeting the candidate and explaining the format: how many questions to expect and how the interview will run. That behaviour belongs in your persona’s system prompt or greeting configuration, not in your JavaScript.

Testing: Open the page in your browser, click start, and grant microphone access. You should see your interviewer appear in the video element, greet you, explain the format, and ask the first question within a few seconds. Answer out loud and confirm the interviewer hears you and responds. Click your end control mid-conversation and confirm the stream stops cleanly.

`Step 4`

In this step your goal is to make each interview a real, configurable interview rather than a single hard-coded conversation.

First, build a question bank of at least 20 behavioural questions, each tagged with a competency such as leadership, conflict, failure, teamwork, or delivery. Store it however you like, this is data your backend owns.

Then add an interview setup screen where, before the session starts, the candidate chooses:

The target role they’re practising for.
The seniority level.
Which competencies they want to be assessed on.

Your backend should generate each interview from those choices, drawing suitable questions from the bank, so that repeated sessions produce different interviews rather than the same script every time.

Testing: Set up an interview targeting a senior role with the “conflict” and “failure” competencies. Confirm the questions asked relate to those competencies. Run a second interview with the same setup and confirm you get different questions from the bank. Change the competencies and confirm the questions change to match.

`Step 5`

In this step your goal is to capture and store the interview transcript.

The feedback report in the next step needs the full conversation, both the interviewer’s questions and the candidate’s answers. Anam gives you two routes to it: the SDK emits message history events while the session runs, and there is a session transcript API you can call after the session ends. Pick whichever suits your design.

Once you have the transcript, persist each completed interview with its date, the setup choices from Step 4, and the full transcript, so past sessions can be reviewed later.

Testing: Complete a short interview, answering at least two questions. Then inspect your stored data and confirm it contains the date, the role, seniority and competencies you chose, and the complete conversation with both the interviewer’s and your own words. Complete a second interview and confirm both sessions are stored separately.

`Step 6`

In this step your goal is to turn the transcript into a feedback report, this is where your tool becomes a coach.

The standard framework for behavioural answers is the STAR method: Situation, Task, Action, Result. Strong answers cover all four; weak answers typically describe a situation and then trail off without actions or results.

Analyse each answer in the stored transcript and produce a written feedback report that includes:

Which STAR elements were present and which were missing from each answer.
A score from 1 to 5 for each answer.
The candidate’s overall strengths.
One specific improvement suggestion per question.

You’ll want an LLM to do the analysis, any provider works, this part is independent of the live Anam session.

Finally, track scores across sessions so the candidate can see whether they’re improving over time.

Testing: Run an interview and deliberately give one incomplete answer, describe a situation but never say what the result was. The report should flag the missing Result for that answer and score it lower. Give one full STAR answer in the same interview and confirm it scores higher. Complete a few sessions and confirm you can see your scores across them.

`Step 7`

In this step your goal is to add interviewer styles and give the candidate control over the flow of the interview.

Different interviewers put different pressure on candidates, and practising with only one style leaves you unprepared for the others. Offer at least two selectable interviewer personas with distinct voices and personalities, for example a supportive coach who encourages you along, and a formal bar-raiser who is polite but gives you nothing back.

Then add flow control: the candidate should be able to skip a question they don’t want to answer, and end the interview early. When they do, the feedback report should cover only the questions actually answered, with no scores or feedback invented for questions that were skipped.

Testing: Run an interview with each persona and confirm the voice and manner are noticeably different while the interview structure stays the same. In another session, skip the second question and end the interview after the third. Check the report covers exactly the questions you answered, with the skipped question absent.

`Going Further`

Once you have the core coach working, here are some ideas to take it further:

Add a per-answer timer so candidates can practise keeping answers to two or three minutes.
Generate a printable or PDF version of the feedback report to share with a mentor.
Add technical and system design interview modes with their own question banks and scoring rubrics.
Bring your own LLM to the live conversation, so the same brain that scores the answers also drives the interviewer’s follow-up questions.

`Share Your Solutions!`

If you think your solution is an example other developers can learn from please share it, put it on GitHub, GitLab or elsewhere. Then let me know via Bluesky or LinkedIn or just post about it there and tag me. Alternately please add a link to it in the Coding Challenges Shared Solutions Github repo

`Request for Feedback`

I’m writing these challenges to help you develop your skills as a software engineer based on how I’ve approached my own personal learning and development. What works for me, might not be the best way for you - so if you have suggestions for how I can make these challenges more useful to you and others, please get in touch and let me know. All feedback is greatly appreciated.

You can reach me on Bluesky, LinkedIn or through SubStack

Thanks and happy coding!

John



Coding Challenge #127 - Tmux
John Crickett — Sat, 18 Jul 2026 08:00:26 GMT
Hi, this is John with this week’s Coding Challenge.
🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉
If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧
Coding Challenge #127 - Tmux
This challenge is to build your own version of tmux, the terminal multiplexer.
If you spend any time working in a terminal, sooner or later you’ll meet tmux. It lets you run multiple terminal sessions inside a single window, split that window into panes, and, best of all, detach from a session and come back to it later with everything still running. It’s the tool that saves your work when your SSH connection drops. Under the hood it brings together some fascinating systems programming: pseudo-terminals, client-server architecture over Unix domain sockets, raw terminal input handling, and screen rendering.
Building a simplified version yourself is one of the best ways I know to really understand how a terminal works.
The Challenge - Building Your Own Tmux
In this challenge you’re going to build a simplified terminal multiplexer. Your tool will let you create named sessions that keep running in the background, detach from them and reattach later, open multiple windows within a session, and split windows into panes, each running its own shell.
This is an advanced challenge. The individual steps are manageable, but you’ll be working with pseudo-terminals, raw terminal modes, Unix domain sockets, and screen rendering, so it helps to be comfortable with systems programming.
The concepts are the same in any language, so pick one you know well that gives you good access to operating system APIs. This challenge is best tackled on Linux, macOS, or another Unix-like platform, since that is where pseudo-terminals and Unix domain sockets live.
Step Zero
In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.
Choose your target platform and programming language. You’ll need access to pseudo-terminal (PTY) APIs, Unix domain sockets, and the ability to put the terminal into raw mode, so check your chosen language has libraries for these before you commit.
If you haven’t used tmux before, install it and spend some time with it. Create a session, detach with Ctrl+b d, reattach, split some panes, and switch between windows. Getting a feel for the real thing will make every step of this challenge clearer. The tmux man page and the tmux getting started guide are both excellent references.
It’s also worth reading up on how pseudo-terminals work (man pty on most systems) and how terminal escape sequences control the screen. These two topics are the foundation of everything you’ll build here.
Step 1
In this step your goal is to allocate a pseudo-terminal, spawn a shell inside it, and connect it to your own terminal.
This is the core building block of a terminal multiplexer. Your program should create a PTY, launch the user’s shell as a child process attached to it, put your own terminal into raw mode, and then shuttle data in both directions: keystrokes from your terminal go to the shell, and the shell’s output is displayed on your screen. When the shell exits, your program should restore the terminal to its original state and exit cleanly.
Testing: Run your program:
cctmux
You should see a shell prompt. Try running some commands, including full-screen programs:
ls -la
vim
top
Everything should behave exactly as it would in a normal terminal. Type exit and verify your program shuts down and your terminal is restored to a usable state.
Step 2
In this step your goal is to split your program into a server and a client that communicate over a Unix domain socket.
Real tmux is built as a client-server system. The server owns the sessions and the shells running inside them; the client is a thin process that connects to the server, sends it your keystrokes, and displays whatever the server tells it to. This separation is what makes detaching possible later: the shells belong to the server, so they survive when a client goes away.
When your client starts, it should check whether a server is already running. If not, it should start one in the background. The two should communicate over a Unix domain socket, and you’ll need a simple protocol for passing keyboard input in one direction and screen output in the other.
Testing: Run your client:
cctmux
You should get a working shell, just like in Step 1. In another terminal, verify the socket exists (for example with ls -l on wherever you chose to put it, such as /tmp/cctmux-*) and that the server appears in ps as a separate process from your client.
Step 3
In this step your goal is to support named sessions.
A session is a collection of shells managed by the server under a single name. Your tool should support creating a new named session:
cctmux new-session -s mysession
The server should be able to hold several sessions at once, each with its own shell. If a user tries to create a session with a name that already exists, they should get a clear error message.
Testing: Create a session and verify you get a shell:
cctmux new-session -s work
Run a command like echo hello to confirm the shell works. Then try creating a duplicate:
cctmux new-session -s work
You should see an error telling you the session already exists.
Step 4
In this step your goal is to implement the prefix key and detaching from a session.
Tmux is driven by a prefix key, Ctrl+b by default. When the user presses the prefix, the next keystroke is a command for the multiplexer instead of input for the shell. Your first command is d for detach: the client should disconnect and exit, restoring the terminal, while the session and its shell keep running on the server.
Make the prefix key configurable so users can choose something other than Ctrl+b, for example via a command line flag or a simple configuration file. Any key that isn’t a recognised command after the prefix should be handled gracefully, and pressing the prefix twice should send the prefix key itself through to the shell.
Testing: Create a session and start something long-running in it:
cctmux new-session -s work
Inside the session run:
sleep 300 &
echo "still here"
Press Ctrl+b then d. You should be back at your normal terminal prompt. Verify with ps that the shell and the sleep process are still running. Then configure a different prefix key, start a new client, and verify detaching works with the new prefix and that Ctrl+b now passes through to the shell.
Step 5
In this step your goal is to support reattaching to a running session.
Detaching is only half the magic. Your tool should let the user reconnect to a session that’s running in the background:
cctmux attach-session -t mysession
On attaching, the user should see the session’s current screen content, including output that was produced while they were detached, and be able to carry on working as if they never left. Attaching to a session that doesn’t exist should produce a clear error.
Testing: Create a session, run echo before detach, then detach with Ctrl+b d. Reattach:
cctmux attach-session -t work
You should see the screen as you left it, including before detach. Detach again, then try attaching to a session that doesn’t exist:
cctmux attach-session -t nosuchsession
You should get an error message, not a hang or a crash.
Step 6
In this step your goal is to support listing sessions, killing sessions, and cleaning up the server.
Your tool should report the sessions the server is currently managing:
cctmux list-sessions
The output should show each session’s name and some useful detail, such as how many windows it has and whether a client is attached, similar to the real tmux output.
It should also support killing a session:
cctmux kill-session -t mysession
Killing a session should terminate the shells running inside it. When the last session is closed, whether by kill-session or by all of its shells exiting, the server should shut itself down and remove its socket, leaving nothing behind.
Testing: Create two sessions, work and play, detaching from each. Run:
cctmux list-sessions
You should see both sessions listed. Kill one:
cctmux kill-session -t play
cctmux list-sessions
Only work should remain. Kill work too, then verify with ps that the server process has exited and that the socket file has been removed.
Step 7
In this step your goal is to add a status bar.
Tmux reserves the bottom line of the terminal for a status bar. Yours should show the session name on the left, the list of windows in the middle (just one window for now), and the current time on the right. The status bar should update as things change, including ticking over as the time changes, and the shell should now render in the remaining lines above it without ever overwriting the bar.
Testing: Attach to a session. You should see the status bar on the bottom line showing the session name and the time. Run a command that produces lots of output, such as:
seq 1 100
The output should scroll in the area above the status bar and the bar should stay intact. Watch for a minute and confirm the clock updates.
Step 8
In this step your goal is to support multiple windows within a session.
A window is like a tab: each window has its own shell, but only one window is visible at a time. Pressing the prefix key followed by c should create a new window with its own shell and switch to it. The status bar should list all the windows with their numbers, starting from 0, and indicate which one is currently active.
Testing: Attach to a session and run echo window zero. Press Ctrl+b c. You should get a fresh shell and the status bar should now show two windows, with the second one marked as active. Run echo window one in the new window. Create a third window with Ctrl+b c and confirm the status bar shows three windows.
Step 9
In this step your goal is to support switching between windows.
With multiple windows created, the user needs to move between them:
The prefix key followed by a digit (0 to 9) should switch directly to that window number.
The prefix key followed by n should switch to the next window, wrapping around from the last back to the first.
The prefix key followed by p should switch to the previous window, wrapping the other way.
When switching to a window, its screen content should be restored exactly as it was, and the status bar should update to show the newly active window.
Testing: Using the session from Step 8, press Ctrl+b 0. You should see the first window with window zero still on screen. Press Ctrl+b 1 and verify you see window one. Press Ctrl+b n twice and Ctrl+b p twice, checking the status bar each time to confirm you cycle through the windows in order and wrap around at each end. Try Ctrl+b 9 and confirm switching to a window that doesn’t exist is handled gracefully.
Step 10
In this step your goal is to split a window into two panes, one above the other, with the prefix key followed by ".
This is where your multiplexer really starts to earn its name. Pressing Ctrl+b " should split the current pane horizontally, creating a new pane below it with its own PTY and shell. Both panes run at the same time: output arriving in either pane should render in that pane’s region of the screen, whichever pane is active.
Draw a border between the panes using box-drawing characters (such as ─ and │), and make sure each shell knows its actual pane size so that programs running inside it wrap and draw correctly. Keyboard input should go to the active pane.
Testing: Attach to a session and press Ctrl+b ". The screen should split into a top and bottom pane with a horizontal border between them. In the active pane run:
seq 1 5
The output should appear only in that pane. Start a long-running command in one pane, for example top, and confirm it keeps updating its own region while you type in the other pane after switching (for now you can test switching in the next step, or verify the inactive pane keeps rendering). Run ls and confirm the columns fit the pane width, not the full terminal width.
Step 11
In this step your goal is to split a window into two panes side by side with the prefix key followed by %.
Pressing Ctrl+b % should split the current pane vertically, creating a new pane to the right with its own shell. Vertical borders should be drawn between side-by-side panes, and splits should compose: the user should be able to mix " and % splits to build up a grid of panes, each rendering independently in its own region.
Testing: In a fresh window press Ctrl+b %. You should see two panes side by side with a vertical border. Run seq 1 5 and confirm the output stays within the pane. Now press Ctrl+b " and confirm the current pane splits into top and bottom, giving you three panes. Run a different command in each and verify all three render correctly in their own regions.
Step 12
In this step your goal is to support navigating between panes with the prefix key followed by the arrow keys.
Pressing Ctrl+b followed by an arrow key should move the active pane in that direction: up, down, left, or right. Your tool should give a visual indication of which pane is active, for example by highlighting its border. Keyboard input should always go to the active pane.
Testing: Build a layout with at least three panes. Use Ctrl+b followed by the arrow keys to move between them, confirming the active pane indicator follows you. In each pane type a different command, such as echo top left, and verify the input lands in the pane you expect. Try navigating in a direction where there is no pane and confirm nothing breaks.
Step 13
In this step your goal is to support resizing panes with the prefix key followed by Ctrl and the arrow keys.
Pressing the prefix followed by Ctrl+Up, Ctrl+Down, Ctrl+Left, or Ctrl+Right should move the border of the active pane in that direction, making it bigger or smaller. The neighbouring pane should shrink or grow to match, borders should be redrawn, and the shells in the affected panes should be told their new size so that running programs adapt.
Be warned if you’re working on a Mac Ctrl+Arrow gets captured by the OS, you’ll want to add support for the Alt key just like tmux itself does.
Testing: Split a window with Ctrl+b ". Press Ctrl+b Ctrl+Up a few times and watch the border move up, making the bottom pane taller. Run top in one pane, resize it, and confirm top redraws itself to fit the new size. Repeat with a side-by-side split using Ctrl+Left and Ctrl+Right. Confirm you can’t resize a pane away to nothing.
Step 14
In this step your goal is to handle the terminal itself being resized.
When the user resizes their terminal emulator window, your client should notice, tell the server, and the server should redistribute the space: recalculating the pane layout, informing every shell of its new size, redrawing all borders, and keeping the status bar on the bottom line.
Testing: Attach to a session with several panes and resize your terminal window by dragging its corner. The layout should adapt smoothly: panes share the new space, borders are redrawn correctly, and the status bar stays on the bottom row. Run top in a pane while resizing and confirm it adapts. Make the terminal very small and then large again, and confirm nothing is corrupted.
Step 15
In this step your goal is to add a command prompt.
Pressing the prefix key followed by : should open a prompt on the status bar line where the user can type a command, edit it, and press Enter to run it, or Escape to cancel. Support the commands your multiplexer already understands, for example new-window, split-window, list-sessions, and kill-session. Unknown commands should show an error message on the status line rather than doing anything surprising.
Testing: Press Ctrl+b : and the status bar should turn into a prompt. Type new-window and press Enter; a new window should be created just as if you had pressed Ctrl+b c. Open the prompt again, type nonsense, and confirm you get an error message on the status line. Finally, press Ctrl+b : then Escape and confirm the prompt closes without running anything.
Step 16
In this step your goal is to add copy mode, so users can scroll back through a pane’s output history.
Each pane should keep a scrollback buffer of output that has moved off the top of the screen. Pressing the prefix key followed by [ should enter copy mode for the active pane: the pane freezes, and the user can scroll back through the history using the arrow keys and page up/page down. Give a visual indication that copy mode is active, such as a position indicator showing where the user is in the history. Pressing q should leave copy mode and return the pane to live output.
Testing: In a pane, generate more output than fits on the screen:
seq 1 500
Press Ctrl+b [ and scroll up. You should be able to scroll back and find line 1. Scroll down again, then press q and confirm the pane returns to the live view and typing works normally. Verify that output arriving in another pane doesn’t disturb your position while you’re scrolling.
Going Further
Once you have the core multiplexer working, here are some ideas to take it further:
Add text selection and copying in copy mode, with a paste buffer and a paste key binding (prefix followed by ]).
Support renaming sessions and windows, and show the custom names in the status bar.
Add a session chooser (like tmux’s prefix followed by s) for switching sessions interactively.
Support a configuration file that sets key bindings, colours, and status bar content, like .tmux.conf.
Add zooming a pane to full screen and back with prefix followed by z.
Implement mouse support: clicking to select a pane, dragging borders to resize, and scrolling with the mouse wheel.
Add synchronised panes, where input is sent to every pane in the window at once.
Support layout presets such as even-horizontal, even-vertical, and tiled.
Share Your Solutions!
If you think your solution is an example other developers can learn from please share it, put it on GitHub, GitLab or elsewhere. Then let me know via Bluesky or LinkedIn or just post about it there and tag me. Alternately please add a link to it in the Coding Challenges Shared Solutions Github repo
Request for Feedback
I’m writing these challenges to help you develop your skills as a software engineer based on how I’ve approached my own personal learning and development. What works for me, might not be the best way for you - so if you have suggestions for how I can make these challenges more useful to you and others, please get in touch and let me know. All feedback is greatly appreciated.
You can reach me on Bluesky, LinkedIn or through SubStack
Thanks and happy coding!
John


Coding Challenge #126 - Background Removal Tool
John Crickett — Sat, 11 Jul 2026 08:01:20 GMT
Hi, this is John with this week’s Coding Challenge.
🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉
If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧
Coding Challenge #126 - Background Removal Tool
This challenge is to build your own image background removal tool that takes a photograph of a person and removes the background, keeping the person and making everything else transparent.
You have probably seen this feature everywhere by now. You give it a photo of yourself, and a moment later you have a clean cut-out that you can drop onto a new background, turn into a profile picture, or use in a design. It feels like magic, but underneath it is a satisfying mix of image decoding, machine learning, and careful pixel work. Getting the body right is the easy part. Handling the fine wisps of hair less so!
In this challenge you are going to build a tool that does all of this on the user’s own device, with no hosted service doing the heavy lifting for you. By the end you will have a tool that can process a single image or a whole directory tree of them.
The Challenge - Building a Background Removal Tool
You are going to build a tool that accepts a photograph of a person, works out which pixels belong to the person and which belong to the background, and writes out a new image where the person is preserved and everything else is fully transparent.
The interesting parts of this challenge are the details. You have to decode common image formats, automatically find the person without any help from the user, produce edges that are smooth enough to look natural against a new background, and do all of the clever work on the user’s own device rather than shipping the image off to someone else’s server/API. Once the single-image case works, you will scale it up to handle whole directories at once while behaving gracefully when one image causes trouble.
This is an intermediate to advanced challenge. The core pipeline is the same whatever you build it with, so pick whatever you are most comfortable with for image processing and, if you go down the machine learning route, running a model without calling out to a hosted service.
Step Zero
In this introductory step you are going to set your environment up ready to begin developing and testing your solution.
Choose your target platform and programming language. I would encourage you to pick a language that has good libraries for decoding and encoding images, because you do not want to be writing a JPG decoder by hand this week. You will also want to think ahead to the person detection step. Many languages have bindings for running pre-trained segmentation models, so it is worth checking what is available before you commit.
It is entirely up to you how the user interacts with your tool. A command-line tool, a native desktop application, and a web app are all perfectly good choices, so pick whichever suits you and the way you like to work.
One constraint to keep in mind from the very start is that the background removal itself must not be handed off to a hosted third-party API. The important thing is that no one else’s server does the work of finding the person and removing the background. Where that computation runs is up to you, as long as it is under your control: running a model you have downloaded on the user’s machine is fine, and so is compiling it to WebAssembly and running it entirely in the browser so the image never leaves the user’s device. What is not in the spirit of things is uploading the image to a hosted background removal service and getting the answer back. Part of the fun here is understanding how the magic actually works, so you want to be the one doing it.
If you go down the machine learning route, be aware that a good segmentation model can be a sizeable download, often in the region of a couple of hundred megabytes. If you are on a slow or metered connection it is worth pulling the model down early so it is ready when you reach the detection step. This is worth bearing in mind for a browser-based build too, where that download becomes something the user’s browser has to fetch.
Gather a small set of test photographs to work with. You will want a few pictures of people, ideally with a mix of easy cases (a person against a plain wall) and harder ones (someone with loose or curly hair, or a busy background). Keep them somewhere handy, because you will run your tool against them again and again.
Step 1
In this step your goal is to load an image and write it back out as a PNG with the same dimensions and an alpha channel.
Before we go any further, it is worth being clear about what the alpha channel is, because it is central to the whole challenge. A colour image is made up of pixels, and each pixel usually has three values: how much red, green, and blue it contains. Each of those values normally runs from 0 to 255.
The alpha channel adds a fourth value to each pixel, on that same 0 to 255 scale, that records how opaque or transparent the pixel is. An alpha of 255 means the pixel is fully opaque and you see its colour completely. An alpha of 0 means it is fully transparent and you see straight through it to whatever is behind, as if that pixel were not there at all. Values in between give partial transparency, which is exactly what you will need later for soft edges.
So when this step asks you to make the whole image fully opaque, you are giving every pixel an alpha of 255. JPG images do not have an alpha channel, which is why they can never be transparent, but PNG images do. That is the reason the output of this challenge is always a PNG: it is the transparency, stored in the alpha channel, that lets the background disappear while the person stays.
Your tool should accept a single input image in either JPG or PNG format. Once it has decoded the image, it should write out a PNG that has an alpha channel and exactly the same pixel dimensions as the input. For now, do not try to remove anything. Just keep every pixel as it is and make the whole image fully opaque, giving every pixel the maximum alpha of 255. This gets your decode and encode pipeline working end to end before you add any of the clever detection logic.
Getting this foundation right matters. The rest of the challenge builds on top of a reliable “read an image, produce a same-sized PNG with alpha” pipeline, so it is worth making sure this is solid.
Testing: Run your tool against a JPG and a PNG from your test set. Open the output files and confirm they look identical to the inputs. To check the dimensions and the alpha channel without having to eyeball them, reach for a command-line tool like exiftool:
exiftool -ImageWidth -ImageHeight -ColorType output.png
You should see the width and height matching your input exactly, and a colour type of RGB with Alpha, which confirms the alpha channel is present. If you prefer ImageMagick, magick identify -format '%wx%h %[channels]\n' output.png does the same job, printing something like 1200x800 srgba, where the a on the end tells you there is an alpha channel.
Step 2
In this step your goal is to automatically detect the person in the image and produce a mask.
This is the heart of the challenge. Your tool needs to work out, for every pixel, whether it belongs to the person or to the background, and it must do this automatically. The user should not have to click, draw, or mark anything to point out where the person is. Given a photo, your tool figures it out on its own.
The output of this step is a mask, which is simply a second image the same size as the input where each pixel says how much that location belongs to the person. A common approach is to run a pre-trained person segmentation model yourself and use its output as your mask. Remember the no-hosted-service rule from Step Zero applies here.
You do not have to invent the detection method from scratch, and there is a lot of prior art to lean on. Here are some starting points worth a look, and it is up to you which route you take:
U²-Net is a salient object detection network that powers a lot of open-source background removers. See the paper “U^2-Net: Going Deeper with Nested U-Structure for Salient Object Detection” (arxiv.org/abs/2005.09007) and the code at github.com/xuebinqin/U-2-Net. The popular rembg library (github.com/danielgatis/rembg) is built on it and makes a good reference point for what “good enough” looks like.
DeepLabv3 and DeepLabv3+ are general semantic segmentation models that include a “person” class and ship ready to use in libraries such as torchvision. The paper is “Rethinking Atrous Convolution for Semantic Image Segmentation” (arxiv.org/abs/1706.05587).
MediaPipe Image Segmenter and Selfie Segmentation from Google (ai.google.dev/edge/mediapipe/solutions/vision/image_segmenter) are designed to run efficiently on-device, including in the browser through WebAssembly, which makes them a natural fit if you are building a web app.
Segment Anything (SAM) from Meta (segment-anything.com, paper at arxiv.org/abs/2304.02643) is a powerful, more recent option that can produce very clean masks.
MODNet (arxiv.org/abs/2011.11961, github.com/ZHKKKe/MODNet) and BiRefNet (github.com/ZhengPeng7/BiRefNet) focus on high-quality matting and fine edges, which will be especially handy when you reach the hair in Step 4.
Whichever you pick, you will typically load and run it with a runtime such as ONNX Runtime, PyTorch, or TensorFlow, all of which can run on the user’s own device and so keep you within the no-hosted-service rule.
If you would rather build the detector yourself from scratch instead of reaching for a trained model, that is a brilliant way to learn, and the trick is to start with the easy case and work up. A good first option is to lean on the plain background in your easy test photo: treat the pixels around the border of the image as background, then grow outwards to every connected pixel of a similar colour, and whatever is left in the middle is your person. That is really just two classic ideas stitched together, colour keying and a flood fill, and it will give you a usable mask on a simple photo with no machine learning at all. From there, a natural step up is GrabCut, a well-known graph-cut foreground extraction algorithm (the paper is “GrabCut: Interactive Foreground Extraction using Iterated Graph Cuts”, dl.acm.org/doi/10.1145/1015706.1015720, and there is a clear walkthrough in the OpenCV docs at docs.opencv.org/4.x/d8/d83/tutorial_py_grabcut.html). GrabCut normally wants a rough box around the subject, which you can supply automatically by assuming the person is roughly central or by running a lightweight face detector such as an OpenCV Haar cascade to locate them. Other classic building blocks worth knowing are Otsu’s thresholding (en.wikipedia.org/wiki/Otsu%27s_method) and the watershed algorithm. A from-scratch approach will not match a modern model on messy backgrounds or fine hair, but it will teach you a great deal about why those models exist.
To make this easy to inspect, have your tool save the mask out as its own greyscale image while you are developing. That way you can look at it directly and see how well the detection is working before you use it for anything.
Testing: Run your detection against your test photos and save the masks. Open them and check that the person shows up as the bright, filled-in region and the background shows up as dark. Try your easy photo first (a person against a plain wall) and then a harder one. The mask does not have to be perfect yet, but the overall shape of the person should be clearly recognisable.
Step 3
In this step your goal is to use the mask to make the background transparent.
Now that you have a mask, combine it with the original image. Every pixel that the mask says belongs to the person should keep its original colour value untouched. Every pixel that belongs to the background should be made fully transparent by setting its alpha to zero. The result is a PNG, still the same dimensions as the input, where the person floats on a transparent background.
Testing: Run the full pipeline on your test photos and open the output PNGs. The quickest visual check is to composite each cut-out onto a bright, solid colour that contrasts with the original photo, for example a strong red or green. With ImageMagick you can build that composite from the command line:
magick output.png -background magenta -flatten check.png
Open check.png and the person should appear against magenta with none of the original background showing through, and their colours should match the original photo.
You can also automate a few checks with ImageMagick so you do not have to rely on your eyes at all:
# There should now be some transparent pixels, so this prints False
magick identify -format '%[opaque]\n' output.png

# A corner pixel is almost always background, so its alpha should be 0
magick output.png -format '%[pixel:p{0,0}]\n' info:

# The average alpha across the image should sit between 0 and 1,
# roughly the fraction of the picture the person fills
magick output.png -alpha extract -format '%[fx:mean]\n' info:
The first command should print False, confirming the image is no longer fully opaque. The corner pixel should come back fully transparent, something like srgba(0,0,0,0). The mean alpha should be greater than 0 and less than 1, which tells you some of the picture has been kept and some made transparent, rather than the whole thing being wiped out or left untouched.
Step 4
In this step your goal is to produce smooth edges around the person, including the tricky areas like hair.
If you composited your Step 3 output onto a new background, you probably noticed a hard, jagged edge, and hair almost certainly looked like it had been cut out with blunt scissors. Real photographs do not have a crisp line where a person ends and the background begins. Strands of hair are semi-transparent, and edges blend gradually. To make a cut-out that composites cleanly onto a new background, the alpha channel around the person needs to transition smoothly rather than jumping straight from fully opaque to fully transparent.
Refine the edges of your cut-out so that boundary pixels take on partial transparency. Pay special attention to hair, which is the classic hard case and the thing that separates a convincing cut-out from an obvious one.
Testing: Composite your refined output onto a new background again, ideally one that is quite different in colour from the original. The edges should look soft and natural, and wisps of hair should blend into the new background rather than showing a harsh outline or a fringe of the old background colour. Compare a before and after against your Step 3 result on a photo of someone with loose hair. The difference should be obvious. It is also worth peeking at the alpha channel on its own, for example with magick output.png -alpha extract edge-check.png, where you should see a soft grey halo around the person rather than a hard black-and-white boundary.
Step 5
In this step your goal is to give the user control over the output filename. We’re half way so this is an easy one to give you a quick rest.
Your tool should let the user specify where the output should be written. When they do not specify a name, your tool should choose a sensible default derived from the input filename. Crucially, the default must never overwrite the input file. Someone processing photo.jpg should get their cut-out saved somewhere else, not have their original silently replaced.
Testing: Run your tool on an input without specifying an output name and confirm a sensibly named output file appears and that the original input is untouched. Then run it again specifying an explicit output name and confirm the file lands exactly where you asked. For good measure, try an input that is already a PNG and confirm the default output name does not collide with it.
Step 6
In this step your goal is to handle invalid input files cleanly.
Not every file with a .jpg or .png extension is actually a valid image, and users will inevitably point your tool at something that is not an image at all. When your tool is given a file that is not a valid JPG or PNG, it should report a clear error message explaining what went wrong and fail with a non-zero exit status (or the equivalent error signal for whatever interface you built). It should not crash with an unhelpful stack trace, and it should certainly not write out a broken or empty output file.
One thing that catches people out here is truncated JPEGs. Many mainstream JPEG decoders are deliberately tolerant and will happily decode a truncated file into a partial image without raising any error at all, so a test you expect to fail passes instead. If you hit this, you may need to validate the file yourself rather than relying on the decoder, for example by checking that a JPEG ends with its end-of-image marker. Truncated PNGs, by contrast, tend to fail cleanly almost everywhere, so they are a gentler test case.
Testing: Start with the easy case. Create a text file, rename it to have a .jpg extension, and run your tool against it. You should see a clear error message and, if your tool is a command-line one, a non-zero exit status.
Next, make a truncated JPEG by keeping only the first slice of a valid one, which chops off the end of the image data and the end-of-image marker:
head -c 2000 valid.jpg > truncated.jpg
Do the same for a PNG:
head -c 500 valid.png > truncated.png
Run your tool against truncated.jpg and truncated.png. Both should be rejected with a clear error and a non-zero exit status, and no output file should be produced in any of these cases. The truncated JPEG is the one to watch, since a tolerant decoder may quietly accept it. If that happens, this is exactly the case the note above is warning you about, and it is a sign you need to validate the file yourself.
Step 7
In this step your goal is to process an entire directory of images.
Instead of just a single image, your tool should also accept a directory as input. When given a directory, it should find and process every JPG and PNG image within it, and it should do so recursively, descending into subdirectories to find images nested further down. Each image gets the same background removal treatment you built in the earlier steps.
Testing: Create a directory with a few images in it, plus a subdirectory containing a couple more. Point your tool at the top-level directory and confirm that every image, including the ones in the subdirectory, gets processed. Drop a non-image file into the directory as well and confirm your tool sensibly ignores it rather than trying to process it.
Step 8
In this step your goal is to mirror the input directory structure in the output.
When processing a directory, the output needs to be organised, not dumped into a single flat folder where files from different subdirectories collide. Your tool should mirror the input directory structure under the output directory. In other words, each output image should be written to the same relative path as its source image. An image at people/holiday/beach.jpg in the input should produce a output file at the matching relative location under the output directory.
Testing: Run your tool against the nested directory from Step 7. Inspect the output directory and confirm its structure mirrors the input. The output image for the image in the subdirectory should sit inside a matching subdirectory in the output folder, at the same relative path as its source. There is a subtle collision to watch for as well: because every output is a PNG, an input folder containing both portrait.jpg and portrait.png would map both output images to the same output name and one would clobber the other. Put a matching pair like this in a folder, run your tool, and decide how you want to handle it so that no image is silently lost.
Step 9
In this step your goal is to keep going when one image fails.
When you are batch processing a whole directory, it is frustrating if the entire run stops dead because one image out of a hundred was corrupt. Your tool should continue processing the remaining images when one of them fails, rather than aborting the whole run. Then, once it has finished working through everything, it should report the failures at the end so the user knows exactly which images did not get processed and why. Since a single bad file fails with a non-zero exit status (as you built in Step 6), a batch run that had any failures should also finish with a non-zero exit status once it has processed everything, so that scripts calling your tool can tell the run was not completely clean.
Testing: Build a directory containing several valid images plus one invalid file (reuse the corrupt file from Step 6). Run your tool over the directory and confirm that all of the valid images are processed and written out correctly. At the end of the run, you should see a clear summary listing the file that failed, and, for a command-line tool, a non-zero exit status. Confirm that the one bad file did not prevent any of the good ones from being processed.
Going Further
Once you have the core tool working, here are some ideas to take it further:
Add a preview or “trimap” mode that shows the mask and the refined edges side by side so you can debug tricky images.
Let the user replace the transparent background with a solid colour or another image, turning your tool into a full background replacement tool.
Support additional input formats such as WebP or HEIC.
Add a progress indicator when batch processing large directories, and parallelise the work across multiple CPU cores or a GPU.
Try more than one segmentation model and let the user choose, or compare their results to see which handles hair and fine detail best.
Handle photos with more than one person in them, and give the user a way to keep only a specific person.
Benchmark how long each image takes and see where the time goes, then look for ways to speed up the slowest stage.
If you built a native tool, try a browser-based version compiled to WebAssembly (or the other way round) so people can use it without installing anything.
Share Your Solutions!
If you think your solution is an example other developers can learn from please share it, put it on GitHub, GitLab or elsewhere. Then let me know via Bluesky or LinkedIn or just post about it there and tag me. Alternately please add a link to it in the Coding Challenges Shared Solutions Github repo
Request for Feedback
I’m writing these challenges to help you develop your skills as a software engineer based on how I’ve approached my own personal learning and development. What works for me, might not be the best way for you - so if you have suggestions for how I can make these challenges more useful to you and others, please get in touch and let me know. All feedback is greatly appreciated.
You can reach me on Bluesky, LinkedIn or through SubStack
Thanks and happy coding!
John


Coding Challenge #125 - Online Diff Viewer
John Crickett — Sat, 04 Jul 2026 08:01:27 GMT
Hi, this is John with this week’s Coding Challenge.
🙏 Thank you for being a subscriber, I’m honoured to have you as a reader. 🎉
If there is a Coding Challenge you’d like to see, please let me know by replying to this email📧
Thank You For All The Feedback!
Before we kick of this week’s coding challenge, I’d like to thank everyone for all the feedback. I got a lot and am still working my way through it. I really appreciate everyone taking the time to get let me know your thoughts.
Thank you! 🙏😍
Coding Challenge #125 - Online Diff Viewer
This challenge is to build your own online diff viewer that compares two text inputs and displays the differences in a clear, visual format.
If you’ve ever used GitHub, GitLab, or any code review tool, you’ve seen a diff viewer. It’s the side-by-side or unified view that shows you exactly what changed between two versions of a file - green for additions, red for deletions. But how do these tools actually work? In this challenge you’ll find out by building one yourself. You’ll implement a diff algorithm, render the results in multiple visual formats, and add all the quality-of-life features that make a diff viewer truly useful.
The Challenge - Building Your Own Online Diff Viewer
You’re going to build an online diff viewer that runs entirely in the browser. Users will paste, upload, or drag-and-drop two pieces of text, and your tool will show them exactly what changed. Over several steps you’ll add side-by-side and unified views, syntax highlighting, navigation tools, export options, and accessibility features.
Step Zero
In this introductory step you’re going to set your environment up ready to begin developing and testing your solution.
This is a web application, so you’ll need HTML, CSS, and JavaScript (or a framework you’re comfortable with). You’ll also need to understand how a diff algorithm works.
Take some time to study the Myers diff algorithm. It’s the algorithm used by Git and many other tools. Your diff viewer will need to take two sequences of lines, compute the shortest edit script that transforms one into the other, and produce a set of additions, deletions, and unchanged lines.
Step 1
In this step your goal is to compute and display a basic line-level diff between two text inputs.
Create a simple interface with two text areas for input and a diff button. When the user clicks the button, your tool should compute the diff between the two inputs and display the result. Colour-code additions in green, deletions in red, and leave unchanged lines uncoloured or in a neutral colour.
At this stage a simple vertical, unified-style output is fine - we’ll add proper views in the next steps.
Testing: Paste the following into your two inputs:
Left (original):
function greet(name) {
  console.log("Hello, " + name);
}

function farewell(name) {
  console.log("Goodbye, " + name);
}
Right (modified):
function greet(name) {
  console.log("Hello, " + name + "!");
  console.log("Have a great day!");
}

function farewell(name) {
  console.log("Goodbye, " + name + "!");
}
You should see the added lines in green and any lines that exist only in the original in red. Unchanged lines like function greet(name) { should appear without colour.
Step 2
In this step your goal is to add a side-by-side diff view with properly aligned rows.
Side-by-side views show both inputs next to each other, with matching lines on the same row and gaps where lines were added or removed. This is the most intuitive way to view diffs for many people.
Your side-by-side view should:
Show the original on the left and the modified version on the right.
Align unchanged lines on the same row.
Leave blank gaps on one side when lines are added or removed.
Show line numbers for both sides.
Testing: Use the same test data from Step 1. In the side-by-side view, the two console.log lines in the modified version should appear opposite blank space on the left, and the original console.log("Goodbye, " + name) line should appear opposite blank space on the right.
Step 3
In this step your goal is to implement a unified diff view and let users toggle between the two views.
The unified diff view is the format used by Git and many command-line tools. It shows a single continuous output where additions are prefixed with +, deletions with -, and context lines with a space. Hunks are separated by @@ headers showing the line ranges.
Your tool should allow the user to switch between side-by-side and unified views with a simple toggle button or tab.
Testing: Switch between views with the same test data. In unified view, verify that added lines start with +, deleted lines with -, and context lines with a space. The hunk header format should show something like @@ -2,5 +2,6 @@.
Step 4
In this step your goal is to display diff summary statistics.
Users want to quickly understand the scope of changes. Your viewer should show a summary panel that displays:
Lines added
Lines removed
Lines unchanged
Total number of changes
Update this summary whenever the diff is recomputed.
Testing: With the test data from Step 1, verify your summary shows 2 lines added, 1 line removed, and the correct number of unchanged lines. Change the inputs and confirm the statistics update accordingly.
Step 5
In this step your goal is to add syntax highlighting for at least five common programming languages.
Diff output is much easier to read when the code is syntax-highlighted. Your tool should highlight at least JavaScript, Python, HTML, CSS, and JSON.
The syntax highlighting should apply to both the original and modified sides. It should also work with the colour coding from the diff - so a highlighted Python keyword that appears in an added line would show with both the syntax colour and a green background.
Your viewer should attempt to auto-detect the language based on file extension or content, and also allow the user to manually override the language selection.
Testing: Create test files in each supported language and verify the highlighting works correctly. Try mixing file types (JavaScript on the left, Python on the right) and verify the language override lets you pick the correct one. Test auto-detection by uploading a .py file and confirming Python highlighting is applied.
Step 6
In this step your goal is to support multiple input methods for loading text into the diff viewer.
Typing or pasting into text areas works, but users will also want to:
Upload files from their computer using a file picker.
Drag and drop files directly onto the viewer.
Fetch content from a URL.
When a file is loaded, display basic metadata such as the filename, file size, detected language, and line count.
Testing: Create two text files on your computer and upload them using the file picker. Verify the content appears correctly in both sides and the metadata is displayed. Test drag and drop by dragging a file from your desktop onto the viewer. Test URL fetch by providing the URL of a publicly accessible text file.
Step 7
In this step your goal is to add diff precision modes: smart, word, and character-level highlighting.
So far your diff works at the line level. But within a changed line, only part of the line might have changed. Precision modes let users see exactly which words or characters changed:
Smart mode: Your best guess at what changed - typically word-level changes.
Word mode: Highlight changed words within a line.
Character mode: Highlight individual changed characters within a line.
Testing: Use a line like changing Hello World to Hello Universe. In word mode, only World should be highlighted on the left and Universe on the right. In character mode, individual characters like W vs U should be highlighted. Verify smart mode makes a sensible choice.
Step 8
In this step your goal is to add diff control options that let users customise what counts as a change.
Sometimes you want to focus on meaningful changes and ignore formatting differences. Add toggleable options for:
Ignoring whitespace changes (e.g., extra spaces that don’t affect the code).
Ignoring case differences (e.g., HELLO vs hello).
Ignoring blank lines (empty lines added or removed).
Ignoring indentation-only changes (tabs vs spaces, changes in indent level).
Ignoring line ending differences (CRLF vs LF).
These options should be available as checkboxes or a settings panel and take effect immediately when changed.
Testing: Create two inputs that differ only in whitespace. With “ignore whitespace” enabled, the diff should show no changes. Disable it and the changes should reappear. Repeat for each option.
Step 9
In this step your goal is to improve large diff readability by letting users hide unchanged sections.
When there are hundreds of lines of unchanged code between changes, scrolling through all of them is tedious. Add the ability to collapse unchanged sections, showing a clickable indicator like “... 47 unchanged lines ...”. Users should be able to click the indicator to expand the section.
Testing: Create two files with at least 50 unchanged lines between two change blocks. Verify the middle section is collapsed by default or can be collapsed, and that clicking it expands to show the full content.
Step 10
In this step your goal is to add a line wrap toggle and synchronised scrolling.
When lines are long, users need to be able to toggle line wrapping on and off. With wrapping off, a horizontal scrollbar lets them view long lines without breaking formatting.
Synchronised scrolling keeps both sides of the side-by-side view scrolling together. When the user scrolls one pane, the other follows. Users should also be able to disable this if they prefer independent scrolling.
Testing: Create a file with very long lines (200+ characters) and verify toggling line wrap works correctly. In side-by-side view, scroll one pane and verify the other scrolls in sync. Disable sync scrolling and verify the panes scroll independently.
Step 11
In this step your goal is to add comprehensive navigation features.
Navigating a large diff efficiently is critical. Add the following:
Next change and previous change buttons that jump between diff hunks.
First change and last change buttons that jump to the start and end of the diff.
A change navigator panel that lists all change blocks, showing the line range and a preview. Clicking a block in the panel should jump to that location.
Gutter markers (coloured indicators in the margin) for additions, deletions, and modifications.
Keyboard shortcuts for all navigation actions (e.g., J for next, K for previous).
Testing: Create a diff with at least 10 change blocks spread across the document. Verify each navigation control works correctly. Test all keyboard shortcuts and confirm the change navigator panel updates to highlight the current change as you navigate.
Step 12
In this step your goal is to handle large inputs efficiently.
Diffs of 10,000+ lines can freeze the browser if not handled carefully. To keep the UI responsive:
Run the diff computation in a Web Worker so the main thread stays responsive.
Use virtualised rendering - only render the lines currently visible in the viewport instead of all 10,000 at once.
Show a progress indicator while the diff is being computed.
Testing: Generate two large text files (10,000+ lines) with differences scattered throughout. Verify the diff computation doesn’t freeze the browser - you should be able to click buttons and scroll while it’s processing. Verify scrolling through the output is smooth.
Step 13
In this step your goal is to add export and copy options.
Users need to get the diff output out of your tool and into other tools or documents. Add the ability to:
Copy the full diff output to the clipboard.
Copy individual change blocks.
Export the diff as a unified patch file, HTML, Markdown, and JSON.
Generate Git-compatible patch output that can be applied with git apply.
Testing: Create a diff and test each export format. For unified patch, verify you can save it to a file and apply it with git apply. For HTML and Markdown, verify the output renders correctly with colour coding preserved. For JSON, verify the structure includes all change information.
Step 14
In this step your goal is to make your diff viewer a Progressive Web App (PWA) that works offline.
Turn your diff viewer into a PWA with a service worker so users can use it without an internet connection. Additionally:
Persist the user’s recent sessions using localStorage or IndexedDB.
Show a history of previous diffs the user can revisit.
Let users save named diff sessions they can come back to later.
Testing: Load your diff viewer, then disconnect from the internet. Verify the page still loads and the diff viewer works. Run some diffs, close the browser, reopen it offline, and verify your history is still there.
Step 15
In this step your goal is to ensure your diff viewer is fully accessible and works well on all devices.
Your viewer should be usable by everyone, regardless of ability or device. This means:
All functionality should be keyboard-accessible.
Proper ARIA labels and roles should be used throughout.
Screen readers should announce change summaries when the diff is computed.
Line numbers and file headers should remain visible (stick to the top) when scrolling.
The layout should be responsive - usable on desktop, tablet, and mobile.
Clear empty states and error messages should be shown when something goes wrong.
Testing: Navigate the entire viewer using only the keyboard. Run a screen reader and verify it announces the diff results. Resize the browser to mobile width and verify everything remains usable. Test with an empty input to verify the empty state message is shown.
Step 16
In this step your goal is to add theme support with light, dark, and high-contrast modes.
Your diff viewer should respect the user’s system theme preference by default. Add a theme selector that lets users choose between:
Light mode
Dark mode
High-contrast mode (for users with visual impairments)
The theme should apply to all UI elements including the diff output, syntax highlighting colours, and control panels.
Testing: Change your system theme and verify the viewer matches. Manually switch themes and verify all colours update correctly. Test high-contrast mode with a screen reader or accessibility testing tool.
Going Further
Once you’ve built the core diff viewer, consider adding these advanced features:
AI-powered diff explanation: Use an LLM to explain what a change does in plain English.
Code-review mode: Let users add comments and annotations to specific lines or change blocks.
Semantic diffs: For JSON, compare the structure rather than the text. The same for HTML - compare the DOM tree.
Syntax validation: Highlight JSON or HTML that is syntactically invalid in the input.
Three-way merge view: Show a base version and two modified versions, useful for resolving merge conflicts.
Image diff: Support uploading two images and showing a visual diff (pixel-by-pixel or structural comparison).
Share Your Solutions!
If you think your solution is an example other developers can learn from please share it, put it on GitHub, GitLab or elsewhere. Then let me know via Bluesky or LinkedIn or just post about it there and tag me. Alternately please add a link to it in the Coding Challenges Shared Solutions Github repo
Request for Feedback
I’m writing these challenges to help you develop your skills as a software engineer based on how I’ve approached my own personal learning and development. What works for me, might not be the best way for you - so if you have suggestions for how I can make these challenges more useful to you and others, please get in touch and let me know. All feedback is greatly appreciated.
You can reach me on Bluesky, LinkedIn or through SubStack
Thanks and happy coding!
John