Kimu

Kimu is a project I made to solve a problem that I think is more and more frequent. Working with Agents, it’s common to start reading, reviewing and correcting a ton of local Markdown files. After a while, I started to hate reading the files in plain text (or inside the IDE) instead of a pretty HTML page that’s easy to scan. And that’s how Kimu was born.

The motivation behind Kimu

If you’d rather read about what Kimu does, go to the But what is Kimu? section. This section tells the story of how the project was born.

I noticed that the Agent (and me!) starts generating a bunch of Markdown files that I then have to Review (the famous little Human-in-the-Loop). This quickly became a tedious chore I didn’t want to do, which I partly blame on how ugly it is to read Markdowns in plain text. And so I started using pandoc to turn the Markdown files into HTML:

pandoc -i input.md -o output.html

The result was a simple HTML file that I could read, but it was still a bit flat, no personality, so I started using water.css to format the files. It was much better, I had local files I could read with a much nicer interface… but even so it wasn’t enough:

Sure, the result was better now:

{begin compare size=1 ratio=1.5/1} pandoc water.css {end compare}

So I got the idea to make a small Markdown viewer. At first it was a tiny mini-project inside my bigger project, Invntry, I did it in one go (one-shot) with an Agent and that was it, it was just a quick tool.

My idea was to have a viewer for the main project I was working on, one I could easily run with a command like uv run docs/serve.py. The problem was that I quickly started adding more and more features to it, so I moved it to its own repo, came up with a name for it and kept adding things. The polished product struck me as so useful, pretty and fast, that I thought maybe the world (or maybe the void??) would benefit a lot from it. I am proud to announce that both my dad and my girlfriend like the app, maybe that’s enough.

But what is Kimu?

Ok, so now we’ve got the why: I needed to read my Markdown files and I wanted to treat myself to a prettier interface instead of a boring text editor. But what IS Kimu?

The name Kimu

If you’re curious about the name, it’s nothing too serious, I needed a placeholder name for the GitHub repo, but I ended up really liking it. I needed something short, so I could do something like kimu docs quickly from the terminal, instead of kimu-beautiful-simple-and-fast-reader docs. And Kimu sounds like Kimün, a Mapuche word that means knowledge. Nice, right?

The logo tried to represent a tree, I was thinking something like how knowledge is like the roots of a tree that keep it strong and standing. I don’t know, it’s not that deep, but I think the logo turned out pretty enough. Days later, with a quick Google search, I found Kumu, which I think is something like a knowledge base, which also uses a tree with roots as its logo, with a kinda digital idea. Small world, I guess?

{begin compare size=0.9} Kimu logo Kumu logo {end compare}

Anyway, I was looking for a short word with a meaning close to knowledge, and I found it.

Features

Ok, and why would I use Kimu?, an astute reader might ask. Well, I think it has a couple of features that make it a very pretty little app, I’ll list them and maybe we can discuss them:

There are many other features, like the 7 themes it has, the auto-generated table of contents in the sidebar, the resizable sidebar, LaTeX and Mermaid support, etc. But I don’t think they’re star features, more like what’s expected for this app to even get to call itself an app. The features above are the ones I think make you turn your head like in that distracted boyfriend meme. I’ll describe it because I don’t want this page to look dated with a meme from 2016: the angry partner has the text “Reading Markdown in plain text” and the distractor woman has “Reading Markdown with Kimu”.

Speaking of the themes, I’d like to show you the work of art that is the themes showcase in the project’s Readme:

themes

Let me tell you how I made this showcase, maybe you’ll find inspiration for your next project: I took 7 screenshots in the same position but with different themes, and then I tried to describe the effect to Gemini so it would build a quick JS script to show the images. I recorded it with OBS, edited it with DaVinci Resolve so it would loop perfectly, and finally turned it into a gif using ffmpeg. I really like the effect, but what I liked most was that going from idea to result took me like 15 minutes, between Agents and wiring things together by hand. The effect is much prettier if you clone the project and open the index.html file I linked above, so you can see it at a glorious <many> FPS, instead of that gif compressed to 15 FPS and full of artifacts.

Future work

I think Kimu is almost finished. If you have suggestions, I’ll gladly read them, but I really like how Kimu is right now.

Some things I’ve been thinking about, and will probably end up building, in no particular order:

And that’s it.

Thanks for reading.