These are my notes on the 2025 Advent of Code.

All my solutions are on my GitHub here. And here is the disclaimer I've been using with each post:

Disclaimer on my solutions

I use Python because I find it easiest for this type of coding. I treat solving these as a write-only exercise. I do it for the problem-solving bit, so I don't comment the code & once I find the solution I consider it done - I don’t revisit and try to optimize even though sometimes I strongly feel like there is a better solution. I don't even share code between part 1 and part 2 - once part 1 is solved, I copy/paste the solution and change it to solve part 2, so each can be run independently. I also rarely use libraries, and when I do it's some standard ones like re, itertools, or math. The code has no comments and is littered with magic numbers and strange variable names. This is not how I usually code, rather my decadent holiday indulgence. I wasn't thinking I will end up writing a blog post discussing my solutions so I would like to apologize for the code being hard to read.

Some thoughts first: this year's Advent of Code was shorter - only 12 days instead of the usual 25 days. I also have mixed feelings about a couple of the problems. Day 10 made me break my rule of not using external libraries. Day 12 was more of a prank. I'll get into details below.

Day 1: Secret Entrance

Problem statement is here.

This was a very easy problem, not worth covering.

Day 2: Gift Shop

Problem statement is here.

This one had potential, I was disappointed you can just count through each number in a range and check if it's invalid.

I'm pretty sure there's a very efficient way to do it even for very large ranges. E.g. between 12340000 and 12349999 there's a single invalid 12341234. There must be a formula that yields the count of invalid numbers for an arbitrary range just by doing the math on the range bounds + account for corner cases. But I didn't spend the time on it since I could just check every single number in the range.

Day 3: Lobby

Problem statement is here.

Another easy one - for part 1, I simply checked all combinations of 2 digits and picked the maximum.

For part 2, looking at all combinations doesn't work as we need to pick 12 digits out of each number. Luckily, a greedy approach works. I split the number into a head (initially empty), and tail (all digits) and we repeat the following algorithm 12 times: pick the largest digits from the tail that still leaves enough digits in the tail for us to pick 12 digits total, add it to the head, and cut the tail at the selected digit.

In other words, we are guaranteed to form the largest number if we keep picking the largest available highest-order digit.

Day 4: Printing Department

Problem statement is here.

Part 1 is trivial.

Part 2 is pretty easy too - the only trick is to not update the grid in-place when removing rolls. Like a game of life simulation.

Day 5: Cafeteria

Problem statement is here.

Part 1 is again trivial.

For part 2, we want to merge overlapping ranges first, then just count the length of each range to arrive at the solution.

Day 6: Trash Compactor

Problem statement is here.

In part 1, based on whether the operation is addition or multiplication, we start with 0 or 1 then simply apply the operation (+ or *) to all the numbers in a column.

In part 2, we also go column by column, but we do it by digit rather than by number. The right-to-left arrangement is a red herring - both addition and multiplication are commutative so it doesn't matter whether we start from the left or from the right.

Day 7: Laboratories

Problem statement is here.

Part 1 - we just go down row by row from the top, counting hits and splitting the beam when we encounter a ^:

hits = 0

for line in lines:
    new_beams = set()
    for beam in beams:
        if line[beam] == "^":
            hits += 1
            new_beams.add(beam - 1)
            new_beams.add(beam + 1)
        else:
            new_beams.add(beam)
    beams = new_beams

Part 2 is similar, the only addition being we need to keep a running tally of how many beams (from different timelines) are at a given position.

beams = {lines[0].index("S"): 1}

for line in lines: 
    new_beams = defaultdict(int)
    for beam in beams:
        if line[beam] == "^":
            new_beams[beam - 1] += beams[beam]
            new_beams[beam + 1] += beams[beam]
        else:
            new_beams[beam] += beams[beam]
    beams = new_beams

Day 8: Playground

Problem statement is here.

This was a nice graph problem. For part 1, we can compute the distance between each pair of nodes (junction boxes), sort by distance, pick the smallest 1000 pairs and add edges between them. Now we have our final graph. The next step is to identify all the connected components of the graph and pick the three with the largest number of nodes.

For part 2, note we can't just add edges to all except the last pair of nodes in the solution for part 1, as those two nodes might already be part of the same component. My solution here was to also precompute the distances between nodes then, as I add edges between them, keep track of how many connected components we have. Instead of adding 1000 edges, we keep connecting pairs of nodes until we are left with two connected components.

Day 9: Movie Theater

Problem statement is here.

Part 1 was easy, as we can just compute the area for every pair of points and pick the largest one.

I found Part 2 very nice. I'm not sure I have the optimal solution, but here's how I solved it: My initial idea was to draw lines between the points, then flood fill the area they describe. Then we can check whether a pair of points describes an area that is fully within the filled surface or not, in which case it is invalid. If we do this, we can pick the largest valid area (fully within) the filled surface.

The only problem with this approach is that the distances between points are very large, so going point by point to connect the surface and fill it gets too expensive. My solution was to scale down the grid.

Here's an example based on the smaller-sized sample input. The sample input is:

..............
.......#...#..
..............
..#....#......
..............
..#......#....
..............
.........#.#..
..............

We can scale this down to:

..#...#
.......
#.#....
.......
#...#..
.......
....#.#

Here's how we do it: we take the set of X coordinates of all points, sort it then map \(x_0 \rightarrow 0\), \(x_1 \rightarrow 2\), \(x_2 \rightarrow 4\) etc. We do the same for the Y coordinates.

Now connecting the points and filling the surface becomes much more tractable. We can simply update the grid with #s to connect a pair of points and we can similarly flood-fill with # since the surface area is significantly scaled down. We're no longer dealing with tens of thousands of points on the grid between two points we have to connect.

Once we have this, we can again iterate over each pair of points and see if the area they describe contains any . (which would make the area invalid), or not. To determine which of the valid areas is the largest, we simply need to map back the \((x_i, y_i)\) and \((x_j, y_j)\) from our scaled down grid to the actual coordinate values. This will give us the real area size and by this point we are guaranteed the area is valid (no . within its bounds).

Day 10: Factory

Problem statement is here.

For part 1, note that pushing a button toggles a set of lights. With lights being either on or off, the toggle is an XOR applied to these lights. For each available button, we either press it or we don't. Applying XOR twice simply undoes its effect. The order in which we press buttons also doesn't matter, since XOR is commutative. Solving part 1, for each button, we try pressing it and not pressing it. We keep track of the number minimum number of presses when we reach the desired end state, which is our solution.

I represented the lights as a bitmask, so [.##.] becomes 0b0110. Similarly, a button that toggles (0, 2, 3) becomes 0b1101.

Here's the full solution:

def solve(goal, state, tail, presses=0):
    global best

    if goal == state:
        best = min(best, presses)
        return

    if not tail:
        return

    h = tail[0]
    solve(goal, state ^ h, tail[1:], presses + 1)
    solve(goal, state, tail[1:], presses)

goal is the end state we want to reach, state is the current state, initially 0. tail are the buttons we haven't tried pressing yet (initially this contains all the buttons), and presses is the number of buttons we pressed so far.

Part 2 was a lot more difficult. This is a linear optimization problem. Our target is expressed by the joltages \({j_0, j_1, ... j_m}\). We have \(n\) buttons. A button press increments some joltages. Let's define a matrix \(options\) such that \(options_(button, joltage)\) is \(0\) if pressing the button \(button\) doesn't increase the joltage \(joltage\) and \(1\) if it does.

Then our problem becomes:

Given the system of equations

\[\begin{bmatrix}\mathrm{options}_{0,0}&\mathrm{options}_{1,0}&\cdots&\mathrm{options}_{n-1,0}\\\mathrm{options}_{0,1}&\mathrm{options}_{1,1}&\cdots&\mathrm{options}_{n-1,1}\\\vdots&\vdots&\ddots&\vdots\\\mathrm{options}_{0,m-1}&\mathrm{options}_{1,m-1}&\cdots&\mathrm{options}_{n-1,m-1}\end{bmatrix}\begin{bmatrix}x_0\\x_1\\\vdots\\x_{n-1}\end{bmatrix}=\begin{bmatrix}j_0\\j_1\\\vdots\\j_{m-1}\end{bmatrix}\]

find the smallest sum \(x_0 + x_1 + ... x_{n-1}\) where all of the \(x\)s are positive integers.

This is where I broke my rule of not taking dependencies on external libraries and reached out for scipy. I used milp (Mixed-Integer Linear Programming):

def solve(options, joltage):
    n = len(options)
    matrix = [[options[j][i] for j in range(n)]
         for i in range(len(joltage))]

    res = milp(
        c=[1] * n,
        constraints=LinearConstraint(matrix, joltage, joltage),
        bounds=Bounds(lb=[0] * n, ub=[max(joltage)] * n),
        integrality=[1] * n,
    )

    return sum([int(round(x)) for x in res.x])

options here is our matrix of which button increments which joltages and joltage is the target state.

We invoke milp with coefficients 1 (c), specifying the linear constraint joltage <= matrix.dot(x) <= joltage - we want the solution to be exactly joltage. The bounds are between 0 and maximum joltage - we can press a button at least 0 times and as most the target joltage times. The integrality parameter enforces all \(x\)s are integers.

This produces the optimal vector.

Day 11: Reactor

Problem statement is here.

The first part is easy. I implemented a traverse that starts from you and recursively traverses all connected nodes. Whenever we hit the out node we increment a running total:

total = 0

def traverse(node):
    global total

    if node == "out":
        total += 1
        return

    for n in graph[node]:
        traverse(n)

traverse("you")

The graph we need to traverse is much larger in part 2. Here, I used a 2-step approach. First, I sorted the nodes topologically:

topological_order = []
visited = set()

def dfs(node):
    if node in visited:
        return
    visited.add(node)
    for neighbor in graph.get(node, []):
        dfs(neighbor)
    topological_order.append(node)

for node in graph:
    dfs(node)

From these, I generated the reverse of the graph:

topological_order.reverse()

reverse_graph = {}
for node, neighbors in graph.items():
    for neighbor in neighbors:
        reverse_graph.setdefault(neighbor, []).append(node)

With these, we can compute the number of paths between a start and end node with:

def paths(start, end):
    paths = {node: 0 for node in graph}
    paths[start] = 1
    for node in topological_order[topological_order.index(start)+1:topological_order.index(end)+1]:
        paths[node] = sum(paths[prev] for prev in reverse_graph.get(node, []))
    return paths[end]

The solution is:

paths("svr", "fft") * paths("fft", "dac") * paths("dac", "out")

Day 12: Christmas Tree Farm

Problem statement is here.

This last one was more of a prank in my opinion. Reading the problem statement, it's obvious the problem explodes combinatorially: we can rotate and flip shapes, try to fit them together in various ways, the number of each type of shape is different for each region. We obviously can't use backtracking for this.

I first started looking at the inputs to see if there is maybe some optimal combination of shapes that simplifies things, but the fact that we get different numbers of each shape would make this not work.

Is there a case in which the shapes are guaranteed to fit without us having to do any flipping/combining? Yes, there is - each shape is in a 3x3 grid, even if it doesn't fully cover it. For a given region, if we can fit the pieces one after another, making each take a 3x3 spot, then we can safely ignore any rotations or packing. In other words, if the region is large enough, we have a trivial solution.

Well, it turns out a large portion of the input is trivially solved like this. As for the rest, let's look at the reverse - is there a case in which the shapes are guaranteed not to fit regardless of how we combine them? Yes, there is - for this case, we count the exact number of points a shape takes. So

..#
.##
##.

takes 5 points, the 5 #. If the total number of points the shapes we want to fit is larger than the number of points in the region, it means that regardless of how we try to rotate and arrange our shapes, they will not fit. Well, it turns out the rest of the input cases fall in this bucket.

So even though the general case explodes combinatorially and to my knowledge there is no practical solution for it, the input cases given are all trivially solvable as they are either way too small or large enough for us to compute the fit without doing any work.

All in all, it was a fun set of problems. I am a bit bummed that this year Advent of Code ran shorter than previous years. Problem 10 was strange, it was the first one where I reached for scipy. Most problems I can solve without external libraries but there was no way I was going to roll my own milp. And problem 12 was straight up annoying - I spent an embarrassing amount of time to arrive at the trivial solution. Eleven more months till the next Advent of Code!

This post marks the tenth year of my technical blog. I started in 2016, ended up writing exactly 9 posts during that year, and made it a point to consistently stick to that number. You are reading post #90. This will be a self-indulgent look back at the past decade.

Why 9 posts per year? While sometimes I have plenty of things to write about, other times I get busy and don’t have the time. Maybe something like a post per month would’ve been nicer, but harder to achieve. I’m still happy I was able to stick to this for so long.

I started self-hosting the blog on my own engine, Tinkerer, which is now archived here. Tinkerer relied heavily on Sphinx and Jinja, relying on the Sphinx plugin system to turn it into a blog. Extensions provided post metadata, ordering and pagination, RSS-feed generation and so on. That worked well until it didn’t. Updates to Sphinx irrevocably broke things, plus Markdown was gaining momentum - who even remembers the cumbersome ReStrctured Text syntax? I implemented Baku, the spiritual successor to Tinkerer, and used PanDoc to migrate my old posts from RST to Markdown.

Baku, which I’m using to this day, is here. It completely drops the Sphinx dependency and replaces Jinja with a 100 LoC templating engine which I’m still very proud of - my VerySimpleTemplate. Lesson learned: the fewer dependencies the better.

Throughout the years I covered various topics I was digging into at the time. When I started the blog in 2016, I was working on the Office C++ clients. The very first two posts are based on a Clean Code talk I used to do (see Clean Code Part - 1 and Clean Code Part - 2).

I was digging deep into modern C++ at the time. Some posts, like Arguments and Smart Pointers and Notes on Types provide best practices. Others covered some of my own R&D. A version of the efficient stack-allocated data structure I describe in (Ab)using Maps made its way into the Office core libraries and became a standard for applicable scenarios. The Composable Generators post became this small library that enables generator chaining in C++: https://github.com/vladris/pipe. This was back when generators were still an experimental language feature.

Around that time, I was starting to dig into types and type systems. I wrote an initial Notes on Types post, and a while later one covering the Idris programming language - Idris: Totality, Dependent Types, Proofs. Then Notes on OOP and Clean Code: Types, all around the topic of types. This became my first published book, Programming with Types in 2019.

Several posts from around that time were topics that I was researching and which made their way in the book, like Arithmetic Overflow and Underflow and Notes on Encoding Text, or excerpts from the book once it was ready:

• A Switchless State Machine
• Common Algorithms
• Higher Kinded Types: Functors
• Higher Kinded Types: Monads
• Variance

I switched jobs in 2019, going from Office to Azure and trading in C++ for data platform architecture. My first post on the subject was Notes on Data Engineering. It was a new space for me, with plenty to learn, and during 2020 I wrote a bunch about it:

• Self-Serve Analytics
• Azure Data Explorer
• Machine Learning at Scale
• Data Quality Testing Patterns
• Changing Data Classification Through Processing
• Ingesting Data Machine Learning on Azure Part 1, Part 2, and Part 3

Like the previous type rabbit hole, I ended up publishing Data Engineering on Azure in 2021.

At the same time, I switched teams again, moving from Azure back to Office to work on Fluid Framework and then Loop. I wrote the first Mental Poker post in December 2021, while thinking through how one could implement a game over Fluid Framework. This became an on-and-off side project which resulted into the Mental Poker series of posts:

• Mental Poker Part 0: An Overview
• Mental Poker Part 1: Cryptography
• Mental Poker Part 2: Fluid Ledger
• Mental Poker Part 3: Transport
• Mental Poker Part 4: Actions and Async Queue
• Mental Poker Part 5: State Machine
• Mental Poker Part 6: Shuffling Implementation
• Mental Poker Part 7: Primitives
• Mental Poker Part 8: Rock-Paper-Scissors
• Mental Poker Part 9: Discard Game
• Mental Poker Part 10: Conclusions

I wrote these over the span of two years, from early 2023 to late 2024, while creating this open source library: https://github.com/vladris/mental-poker-toolkit.

Before Mental Poker, I spent 2022 digging into computability. I always found the subject fascinating:

• Computability Part 1: A Short History
• Computability Part 2: Turing Machines
• Computability Part 3: Tag Systems
• Computability Part 4: Conway’s Game of Live
• Computability Part 5: Elementary Cellular Automata
• Computability Part 6: Von Neumann Architecture
• Computability Part 7: Machine Implementation Details
• Computability Part 8: Lambda Calculus
• Computability Part 9: LISP

After wrapping up the Mental Poker toolkit, I spent 2025 implementing a text editor and wrote several DevLog posts about it - Flow, Formatting, Commanding, Theming and Footguns, Markdown and WYSIWYG.

Sometime in 2023, when GPT3 took the world by storm, I wrote another book, Large Language Models at Work. I didn’t publish excerpts on my blog as I made it freely available at https://vladris.com/llm-book. Fun fact, the book website is also built using Baku, just like this blog.

The industry moved fast, and what was state of the art in 2023 became mostly obsolete by 2025. I reflect on that in Agent Integration Patterns.

With the holiday season coming, I’m excited about Advent of Code. I’ve been solving puzzles since its inception and since 2023, I made it a tradition to start the year with a post covering the past December’s Advent of Code, focusing on the problems I found most interesting.

Not everything requires series of posts, sometimes I write a self-contained just-for-fun thing. Like how I implemented a digital pendulum clock, a solver for an iPhone game called Kami 2, or a solver for the game 24. Or that time I implemented Timsort to get a better sense of how it works.

The above is not a complete list of what I wrote here over the past 10 years, rather a recap of some of the major themes. It’s been a fun ride so far. As for the next 10 years - who knows? I know my next post will cover Advent of Code 2025. The sky is the limit beyond that.

I have plenty of things I still want to cover:

• More on Flow - Turns out you learn a lot when you implement a text editor. Also on Flow’s successor. Electron is too much of a hog so I started experimenting with an editor based on Tauri, geared towards long-form writing.
• More on AI - We’re still evolving the ways we integrate AI into software and there’s plenty of learning to cover there.
• Webdev - For the past 5 years or so, my day job had me using TypeScript, React, and the wonderful JS ecosystem. I have many thoughts here.
• Building product - I scratched the surface of this with Shipping a Feature. There’s a lot more to cover. I learned a lot shipping software to millions of users while working on Office.
• Other areas of interest, like programming languages, compilers and runtimes, pragmatic functional programming etc.

Happy holidays and see you in 2026! Thank you for reading!

A couple of years ago, when LLMs started taking off, I wrote a whole book about how to integrate models into larger applications. I knew going in that the book will get outdated very fast due to the speed at which the industry is moving. In fact, a few months after I finished it, the model I used throughout the book for code examples was deprecated by OpenAI. This broke all code samples. The API itself changed significantly since then. I guess I could use a model to upgrade them, but the way we use models today is already very different - simply getting the code working again is not enough.

Agents and Patterns

I won't attempt another applied AI book, not at this time, but I am writing this blog post to reflect on some of the advancements and modern ways of leveraging models. Beyond just chat, agents are becoming more and more capable and thus useful. I want to focus on that.

I also believe, at some point, we will have the equivalent of the famous Design Patterns, but focused on creating and integrating agents. We're still early, the technology is going to advance by a few more leaps and bounds before we can pin some things down. Or we go singularity, in which case who cares, AI will figure everything out for us.

With the caveat that things might still change dramatically, let's look at how agents are built today and how the field advanced since I wrote Large Language Models at Work.

LLMs @ Work Teardown

Here's the table of contents of my now quite stale book:

1. A New Paradigm - Mostly introducing what was then a very new and emerging field.
2. Large Language Models - Covering the basics - models, tokens, API calls and responses.
3. Prompt Engineering - Discussing prompt creation and tuning.
4. Learning and Tuning - Covering in-prompt, N-shot learning and fine tuning.
5. Memory and Embeddings - Going over context limitations and memory implementations.
6. Interacting with External Systems - About function calling.
7. Planning - Multi-turn execution of a plan - remember this was written before reasoning models and agents were the norm.
8. Safety and Security - Pretty self-explanatory.
9. Frameworks - Talking about LangChain and Semantic Kernel.
10. Closing Thoughts - Again, self-explanatory. GPT4 was the new hot model when I wrapped up the book.

Looking back at this, it's quite impressive how much has changes since.

Starting with Chapter 2, the correct term today is foundational model, the large models are multi-model, not limited to language.

Prompt engineering (Chapter 3) fell out of favor, the modern term is context engineering, which is a superset of that: it's not only about the wording of the prompt we give the model, but all the other things we stuff into its context window - relevant instructions, documents, available tools - to produce the optimal response.

My Chapter 4 was called Learning and Tuning. I think a better name would be In-context Learning vs Tuning. This is still an interesting debate, where the different approaches work better for different scenarios. To quickly summarize: if you want your model to do X, do you craft a solid prompt or fine-tune it? The tradeoff is there's only so much you can do with a prompt vs. fine-tuning is expensive and you have to redo it for every new foundational model. An interesting deciding factor is the complexity of X. How much domain knowledge does X require? How divergent are your expected answers from what the model tends to output?

Memory (Chapter 5) is a very interesting topic. For one, models today have much larger context windows and they keep growing, so for a lot of small-scale scenarios, this might be a non-issue. E.g. you can stuff a whole novel into the context, something that wasn't possible two years ago. Industry leaders are now offering memory built into their chat experiences, so I wouldn't be surprised if in the near future memory gets abstracted away and handled underneath the API. For the cases where we do have too much data to fit into the context, handling this is now part of the context engineering discipline - determining what is relevant, retrieving it, and putting it into the context.

Interacting with External Systems (Chapter 6), is the fastest moving. This is no surprise, as model interactions with side effects produce the most value. When I started writing the book, there was no standardized function calling in the OpenAI API. You had to prompt context engineer the model into telling it what it can do and give it some examples of JSON functions calls. Before I got to Chapter 6, OpenAI introduced functions as part of the API. Nowadays MCP is the standard, providing complex capabilities to models. I will talk more at length about this below.

Chapter 7 was about Planning. Multi-turn execution was pretty novel two years ago but today in underpins all agentic workflows.

Safety and Security (Chapter 8) remains a concerns. The attack surface only grew. Two years ago, one of the biggest concerns was prompt leaking - an attacker stealing your carefully crafted prompt. Today, with multi-turn execution and MCP tools, the attack surface and opportunities for data exfil is significantly larger.

As for Frameworks (Chapter 9), they kind of fell out of favor lately. As the major players are pulling more capabilities within their APIs and models are becoming smarter, generic frameworks are becoming maybe less popular.

As I wrote at the start of this post, if the field eventually slows down, there will be plenty of opportunity to create frameworks capturing the latest patterns and formalizing them into easy-to-use systems. But we're not there yet. After this whirlwind review of how my last book is not so much relevant today, let me talk a bit about the state of the art. This is going to be less of a how to, more of a top of mind.

Agent Engineering

The biggest leap over the past two years has been giving model-based solutions a lot more autonomy. An agent is usually doing multi-turn work, with a plethora of tools at its disposal. A key learning was that new models provide such giant leaps in capabilities that today's scaffolding need to accommodate for that, which we call model-forward engineering. I'll cover these and a few other concepts below.

MCP

The Model Context Protocol introduced by Anthropic provides a standard way of capability providers to advertise their capabilities to a model and, vice-versa, a common way for models to invoke tools. While MCP is not an official standard, the fact that both Anthropic and OpenAI embraced it made it the de-facto standard in the industry.

Whatever service you build, if it can speak MCP, agents can use it.

If you are building an agent, there's now a standard way to tell it what are all the various tools it can use via MCP.

I expect very broad adoption of MCP. Most service will support this and you would be missing out if you're building a service that wouldn't.

If you're building an agent, you'd want to supply its tools via MCP.

The part that I find most interesting is specialized agents exposing their capabilities via MCP to other agents.

Multi-Turn Workflows

In the world of agents, multi-turn is the norm. There are few serious jobs you can achieve with a single model call. The model will either ask for a tool call, revise its plan, or even prompt the user for input.

Tool use is the easiest to solve: you offer the model the buffet of MCP tools available, it responds by describing a function invocation, your code runs the function and gives it the response.

Plan revisions are more interesting: with a multi-turn agent, the agent should usually starts by creating a to-do list, then go through it turn by turn. What happens when new information causes the plan to change? What is the right combination of prompt, tuning, context that will make the model realize oh, I'm going down the wrong path, let me step back and try something else?

Prompting the user for input is another very interesting one. Here I am not talking about permissions. I've been using a lot of coding agents which, for security reasons, prompt you before running bash commands etc. I'm talking about the model realizing it needs some more input from you, stopping, and asking you a clarifying question. I've rarely seen this done well with existing agents, I think the field is ripe for opportunity and I'm looking forward to advancements here. As a concrete example, coding agents are still writing at a junior engineer level. I would much prefer them to stop early and ask clarifying questions rather than doing odd things to get things to work. I also realize this is a very hard problem.

The bottom-line, as we're talking about agents, is you will probably need a bunch of code to support long-running, multi-turn workflows.

Tactical Fine-Tuning

Fine-tuning is taking a pre-trained model and teaching it some new stuff in the form of prompts and expected replies. This works well for domain-specific tasks, but it has some important trade-offs.

One trade-off is the fact that you'll have to fine-tune any new foundational model you'll upgrade to. Fine-tuning is not cheap, it's an involved process, and as new models come out quite often, there's an ongoing tax to pay to have a bleeding-edge fine-tuned model ready to go.

An even bigger trade-off is a fine-tuned model will behave differently than an off-the-shelf one. In a complex system, users might expect similar behavior across surfaces but if one of the surfaces behaves differently the overall experience will seem off. The way to mitigate this is to use multi-agent workflows.

Multi-Agent Workflows

The concept of multi-agent workflows is what got me to write this post. We looked at MCP, multi-turn, fine-tuning - the combination of these is mind-bending. With the state of the art, an ideal agent implementation has the following ingredients:

• Specialized agents fine-tuned on specific tasks.
• Having these specialized agents implement the MCP protocol as servers.
• An entry-point agent that can leverage these other specialized agents via MCP.

This idea is what got me thinking of design patterns and what those mean in the AI world. It's a very interesting horizontal scaling concept - rather than having a one-size-fits-all solution, have a bunch of specialists ready and an entry point that can leverage them as needed.

Coincidentally, I was procrastinating writing this blog post for a week or so as Anthropic just announced Claude Code supports subagents, one specializing in code review, on specializing in debugging etc.

I'm positive we're entering the era of horizontal scaling where a solution will involved a set of specialized agents rather than a know-it-all.

Model-Forward

This is a very interesting concept which means How can we write software that doesn't incur a tax when the new model comes out, rather it gets better as model capabilities improve?

The hard-learned lesson here was that, after building frameworks, scaffolding, prompts, and sinking a ton of engineering cost into an AI-powered solution, when the new model came out, it could do all (most?) of that stuff out-of-the-box, no crutches needed. Model-forward design is about future-proofing and thinking a move ahead.

Can we build solutions that will just get better as the models get better? Fine-tuning is a controversial example of this - it's costly and different, and maybe a new, smarter model can do whatever we want to achieve without fine-tuning.

Predicting the future is impossible, so what can we do to be model-forward? What we can do is offload more of the work to the model. The smarter it gets, the more it can do for us. We can give it more tools, better context, and let it do its thing.

The key point behind model-forward development is to focus less on complex scaffolding around model workflows and more on giving the model the tools it needs and letting it work. Rather than creating a complex, multi-step orchestration, just hand the model the right context, MCPs available, and listen to its response.

Summary

In this post I looked at the analogy between AI model integration patterns and the classic Design Patterns. I also did a teardown of my Large Language Models at Work book, and looked at some of the emerging patterns:

• MCP as a standard.
• Multi-turn as the norm.
• Fine-tuning for specialized tasks.
• Multiple agents working together.
• Future-proofing with a model-forward approach.

No book for now, and not any time soon. I'll either write a book on how to use AI when we reach stable state, or we pass the event horizon and AI will write the book much better than I ever could. I've been refocusing on writing fiction lately.

In this post I want to cover one of the foundational features of Flow: its Markdown handling. I will not show a lot of code, because most of it is boring parsing code and special-case handling.

Different editors tackle Markdown in different ways. Some support a subset of Markdown formatting on insertion, but don't preserve any markup. For example, typing a * would toggle Italics on then, once the user types the closing *, not only are Italics toggled off, but both * markups are removed from the document. This is the behavior of editors that don't natively support Markdown.

Other editors support Markdown natively, like some of the apps that inspired Flow - Obsidian and Bear. The problem with these apps is that Markdown has its own quirks which impact the overall authoring experience. One simple example is handling of paragraphs: in Markdown, a new paragraph starts after two newline characters. A single newline doesn't affect the rendered document.

For Flow, I wanted to fully support Markdown, but also hide some of its quirks from the user. If the user is not familiar with it at all, they should still be able to intuitively use the app and have the best possible experience.

Pre- and post- processing

Flow uses pure Markdown and can load and save .md files. To smoothen things out, the first thing it does when loading a document is convert it into a series of paragraphs by handling some of the whitespace particularities of Markdown.

It converts a piece of text like the following

This is considered a single
paragraph in Markdown even though each
line ends with a newline character.

* This is a list item
* This is another list item

into something like

<p>This is considered a single paragraph in Markdown even though each line ends with a newline character.</p>
<p>* This is a list item</p>
<p>* This is another list item</p>

The above is just to illustrate the type of transformation, we don't go straight to <p> HTML elements, rather these are ProseMirror paragraphs.

The preprocessor is fairly simple, stripping single newlines where appropriate, handling whitespace at the end of lines etc. It is also aware of lists, codeblocks and block quotes, which have different rules. For example, a codeblock is a single entity regardless of how many consecutive newlines appear in its content.

The preprocessor runs when opening a new file. Conversely, the postprocessor runs on save and converts the ProseMirror document back to Markdown by doubling newlines where appropriate.

These are implemented by two functions:

export function markdownToDoc(markdown: string): ProseMirrorNode {
    /* ... */
}

export function docToMarkdown(
    doc: ProseMirrorNode
): MarkdownSerializationResult {
    /* ... */
}

The MarkdownSerializationResult is defined as:

export interface MarkdownSerializationResult {
    markdownText: string;
    positionMap: (processedPos: number) => number;
}

The first function takes a Markdown string as input and creates the ProseMirror document (returning the root node).

The serialization function takes the document and returns the Markdown as a string. In addition, it also returns a mapping from position in the Markdown string back into the document. That is used by the parser, which we'll look at below. First, let's look at the internal document representation.

Internal representation

ProseMirror allows for rich document schemas. In fact, the ProseMirror Markdown plugin can translate a Markdown document into its HTML representation and vice-versa, where a paragraph of text becomes a <p> element, a list becomes an <ol> or <ul> consisting of multiple <li> elements, and so on.

I did not use this plugin because it strips the markup during conversion. I wanted to leave all the markdown in the document. To achieve this, Flow uses a very simple document schema consisting exclusively of paragraphs which translate to <p> elements. All styling is done via decorations. I talked about ProseMirror decorations in previous posts, but to recap, at a high level, decorations add attributes to a range of text. If my paragraph is There are *italics* in this sentence, we can add a decoration from the starting * to the closing *. The rendered HTML will look something like this <p>There are <span>*italics*</span> in this sentence. The <span> will have whatever attributes we want to attach to it.

The document schema is just:

export const docSchema = new Schema({
    nodes: {
        doc: { content: "block+" },
        paragraph: {
            group: "block",
            content: "inline*",
            attrs: {
                type: { default: "paragraph" },
                widgetId: { default: null },
            },
            toDOM(node) {
                return [
                    "p",
                    {
                        type: node.attrs.type,
                        widgetId: node.attrs.widgetId,
                    },
                    0,
                ];
            },
        },
        text: { group: "inline" },
    },
});

While the schema of Flow documents is simple, consisting of just paragraph nodes, a lot happens at runtime to properly decorate the document.

Markdown processing

Flow uses markdown-it internally to parse the Markdown document and decorate it for rendering. There's quite a lot of parsing logic, and since this is one of the core capabilities of the app, I have a lot of tests around it. Properly parsing Markdown is not easy!

I mentioned above that There are *istalics* in this sentence roughly translated to <p>There are <span>*italics*</span> in this sentences</p>. To be more precise, this translates into <p>There are <span class="em markup hide-markup">*</span><span class="em">italics</span><span class="em markup hide-markup">*</span> in this sentences</p>.

The parser adds the markup and hide-markup decorations around the *s and the em around the whole thing. ProseMirror maps these to the right spans on render. We're also aware of the cursor position: if the cursor is within the range of the decoration, we tag the markup with show-markup instead of hide-markup.

Then everything is CSS: we simply get the em class to be italicized, markup to be muted, hide-markup to be hidden etc. That's for the standard editor mode. When we switch Flow to Source mode, both hide-markup and show-markup are visible.

Here is where the positionMap comes in handy. Our ProseMirror-to-Markdown conversion returns a string and a mapping. We briefly looked at this above:

export interface MarkdownSerializationResult {
    markdownText: string;
    positionMap: (processedPos: number) => number;
}

export function docToMarkdown(doc: ProseMirrorNode) {
    /* ... */
}

The reason we need this mapping is we don't only convert the document from a ProseMirror schema to a Markdown string on save, but also to parse it and add decorations. When we parse the Markdown and find positions where we need to add decorations, we need to map these back to positions in the ProseMirror document. These aren't exactly identical.

Positions

A quick side-note on positions: in ProseMirror, when indexing by position, we need to account for non-text nodes (paragraphs in our case). A ProseMirrorNode that is not a leaf text node has a before position and an after position. This offsets things, so without maintaining a positionMap we end up indexing the wrong document fragments. During serialization via docToMarkdown(), we not only produce the Markdown string, but also track offsets to account for this.

Lists

The story is simple for basic markup. It gets a bit more complex for things like lists. Because I wanted to Flow to have a WYSIWYG experience, I'm using single-line lists. That is, each list item gets converted to a separate paragraph inside the document schema. We also want to preserve the markup, so for an unordered list, if the cursor is on it, we want to show the * markup. If the cursor is on a different line, then we want to hide the * markup but show the usual • symbol.

For numbered lists, we also need to extract the number and make it available an attribute for rendering, since ultimately lists don't translate to <ol>, <ul>, and <li> elements, rather to <p> elements.

Plugins

The Markdown parsing library Flow is using, markdown-it, has its own plugin system, which allows us to extend the parser with custom syntax. For example, underlying with ~ is done with a plugin.

Widgets

Some elements, like code blocks and images, are represented as UI widgets in the editor (unless in Source mode). The parser adds special decorations for these such that, if widgets are available, we can completely hide the content and instead inject a UI widget in the canvas.

I will cover widgets in detail in a future post, as they are not as interesting from the Markdown parsing perspective, but do have a lot of code behind.

Tables

Flow does not support tables yet. The CommonMark spec does not include tables. Tables are an extension introduced by the GitHub Flavored Markdown spec. I will probably end up implementing support as specified by GitHub.

The reason I didn't make this part of the MVP is that tables are not critical for creative writing. That said, as I'm using Flow to author blog posts like the one you are reading now, I will need support for both tables and equations.

Conclusion

I would've very much preferred not to get into the business of parsing Markdown, as Markdown nowadays is quite complex, which makes custom parsing logic error-prone. That said, I couldn't find a better solution for my requirements, namely:

• Load and save Markdown.
• Provide a WYSIWYG authoring experience, which includes hiding/showing the markup as needed.

Summary

In this post I covered how Flow implements a Markdown WYSIWYG authoring experience:

• Pre- and post- processing the Markdown document into a simple ProseMirror schema.
• The document schema, which consists of paragraphs and decorations.
• A custom Markdown-parser based on markdown-it that parses the document and adds decorations.
• Lists, widgets etc. require special handling.

This post was written with Flow. Try it out here.

This is going to be a fun post! First, I want to show how I implemented theming for Flow. With its focus on providing an inspiring environment, theming was min-bar for the app. Fortunately, implementing theming is fairly straight-foward. Until it isn't. In the first part I'll go over how I gave the Electron app its unique look and feel. In the second part, I'll cover the strange snag I hit.

Theming

Making something themeable in the web world is easy with CSS variables:

:root {
    --color-bg-primary: #fff;
    --color-bg-secondary: #fff;
    --color-bg-tertiary: #fff;

    --color-fg-primary: #000;
    --color-fg-secondary: #000;
    --color-fg-accent: #000;

    /* ... */
}

.latte-theme {
    --color-bg-primary: #f9f5f0;
    --color-bg-secondary: #e6dfd3;
    --color-bg-tertiary: #f0ebe0;

    --color-fg-primary: #5a4534;
    --color-fg-secondary: #7a6b4f;
    --color-fg-accent: #c74343;

    /* ... */
}

The :root style will provide the defaults while subsequent classes can override it. In the above example, .latte-theme is a fragment of the app's Latte theme.

On first boot, before the user can configure the theme, I want the app to respect the operating system's dark mode. We can do this with the prefers-color-scheme: dark media query:

:root {
    --color-bg-primary: #fff;
    --color-bg-secondary: #fff;
    --color-bg-tertiary: #fff;

    --color-fg-primary: #000;
    --color-fg-secondary: #000;
    --color-fg-accent: #000;

    /* ... */

    @media (prefers-color-scheme: dark) {
        --color-bg-primary: #000;
        --color-bg-secondary: #000;
        --color-bg-tertiary: #000;

        --color-fg-primary: #fff;
        --color-fg-secondary: #fff;
        --color-fg-accent: #fff;

        /* ... */
    }
}

With this, on first boot the app should use the dark mode colors if the OS is set to dark mode.

Now all this happens on the render thread. Electron boots up fairly fast, but users might still see a blank window for an instant between the time the main process has started but the render processes hasn't finished booting. For that case, I wanted the blank window to still respect the OS setting, otherwise when in dark mode, users might see a flashing white window. That's because Electron's default background color is white.

The following code sets up the main window:

const mainWindow = new BrowserWindow({
  width: 1200,
  height: 800,
  minWidth: 300,
  minHeight: 400,
  titleBarStyle: "hiddenInset",
  backgroundColor: nativeTheme.shouldUseDarkColors ? "#000" : "#fff",
  /* ... */
});

The relevant part is the backgroundColor. The nativeTheme.shouldUseDarkColors API is the way to check whether the OS is in dark more inside the main process (as opposed to the render process where we can use media queries).

Settings

The app's theme is one of its many settings. The way settings work in general is also an interesting topic. I've been using electron-store to store the app settings. This package abstracts a native store which supports typed schemas and version migrations of settings: https://github.com/sindresorhus/electron-store.

The store works on the main process, which means I had to implement IPC to get/set settings on the render process. This type of IPC is common for Electron apps and follows the same pattern as I describe in the Commanding post. As a quick recap, the render process talks to the main process via window.electronAPI.invoke and the main process receives and handles these events. Here's how the render process asks for a setting item:

function getStoreItem<K extends keyof StoreType>(
    key: K
): Promise<StoreType[K] | undefined> {
    return window.electronAPI.invoke(GET_STORE_ITEM, key);
}

Here StoreType is the strongly typed store schema and GET_STORE_ITEM is just a string to identify the event type.

On the main process side, this is handled via:

ipcMain.handle(GET_STORE_ITEM, (_, key: keyof StoreType) => {
    const value = store.get(key);
    return value;
});

With IPC taken care of, I implemented a React provider that wraps the IPC code and exposes the settings via a SettingsContext. Theming becomes super-easy with this. For example, inside the React component implementing the main view:

const EditorContent: React.FC = () => {
    const { theme, font, fontSize, autoIndent, lineHeight, paragraphSpacing } = 
        useSettings();

    /* ... */

    return (
        <div className={`app-container ${theme}`}>
            <TitleBar />
            <SideBar />

            <Editor {...editorProps} />
            <StatusBar />
        </div>);
    );
}

Note any component can easily get the settings from the provider and, in the case of theming, we simply use it as a className prop inside the JSX.

The provider also allows consumers to update the various settings. For example, for theming, it exposes an updateTheme() API that allows components to update the setting.

Multiple windows

When working with theming though, a reasonable expectation would be to have the theme change across the all open app windows. So as soon as I select the Latte theme from the theme picker in the Settings window, the main window should change colors.

The existing IPC mechanism I described so far isn't sufficient for that: the render process can get and set settings, but a key missing piece is that, as soon as a setting changes, the main process needs to broadcast this to all window instances.

Previously I shared the implementation of the main process's GET_ITEM handler:

ipcMain.handle(GET_STORE_ITEM, (_, key: keyof StoreType) => {
    const value = store.get(key);
    return value;
});

The SET_ITEM handler does a bit more work:

ipcMain.handle(
    SET_STORE_ITEM,
    <K extends keyof StoreType>(
    _: unknown,
    key: K,
    value?: StoreType[K]
) => {
    store.set(key, value);

    BrowserWindow.getAllWindows().forEach((win) => {
        win.webContents.send(SETTING_CHANGED, { key, value });
    });
}

The function takes a key of type K which needs to be part of the store schema and an optional value of that type. This is the standard to call the store API, which happens on the first lie (store.set(key, value);). Then, once the value is stored, I use the Electron API to sent a SETTING_CHANGED event to all windows and pass them the key that changed and the new value.

On the render process side, we listen to the event on the window, and update the corresponding setting in the provider:

window.electronAPI.on(SETTING_CHANGED, data => {
    const { key, value } = data;
    /* Update setting */
}

This way, changes reflect instantly across the app.

Additional considerations

A benefit of using CSS variables for themes is that it's super easy to implement the different theme cards in the Settings window. A theme card is a React component to which we apply the theme we want it to display, and since we have a CSS class for each theme, we can put together the gallery with very little code:

const ThemeCard: React.FC<ThemeCardProps> = ({ title, className, current, onClick }) => {
    return (
        <div className={`theme-card ${className}`} onClick={onClick} data-current={current}>
            <div className="theme-card-content">
                <h2 className="theme-card-title">{title}</h2>
                <p>"The universe is made of stories, not atoms."</p>
                {/* Rest of card content */}
            </div>
        </div>
    );
};

The gallery becomes just a sequence of ThemeCards with different props.

On footguns

This brings me to the funny part of the journey. I started building Flow as a macOS app but based it on Electron on the idea that it will be easy to bring it to Windows. As I started looking into a Windows version, I hit a strange snag I didn't consider when I was focused on macOS: the menu.

On macOS, the menu bar shows at the top of the screen. I described in the Commanding post how the commands end up in a registry which I serialize and send to the main process to set up the native menu.

On Windows on the other hand, the menu bar appears on the window itself. And, of course, the native menu is not themeable. Worse, because I'm theming the whole app, I use a custom title bar since it would otherwise get the default system colors. The menu bar is part of the browser window on Windows, so there is no way to put anything before it.

The only reasonable conclusion, which I guess all Electron apps that support theming do, is that I need a custom menu bar implementation for Windows. That is, a full React menu system that binds to the commanding infrastructure.

The reason I find this extremely funny is that I picked Electron to write once and run everywhere, and it seems I'll end up with a ton of platform-specific code: on macOS, set up the native menu on the main process; on Windows, set up a custom menu on the render process.

Summary

In this post I talked about how I implemented theming in Flow, and settings more generally:

• Themes are implemented as CSS classes overriding CSS variables.
• Some boot considerations: being aware of dark mode before user picked a specific theme.
• I use electron-store to store the settings.
• A SettingsProvider on the render process handles IPC.
• The main process broadcasts all setting changes to all active windows so any change is reflected instantly across the whole app.
• The interesting issue I ran into where on Mac the menu is handled by the main
• process but on Windows, as long as I want custom theming throughout the app, the menu must be custom-built thus run in the render process.

This post was written with Flow. Try it out here.

I started getting ads for Klydoclock on Instagram. The product looks really neat: