Martin Lysk Blog RSS Feed

Markleft: How I review claude plans in Markdown

Sun, 09 Aug 2026 00:00:00 GMT

AI output seldom meets the intent on the first prompt, so iteration is necessary. Today, iteration usually means providing feedback in a follow-up prompt, which leads to a rewrite of the whole document. The prompt that explains the intent behind the revision remains buried in the chat.

Imagine sending a colleague a five page document. They read it and have some concerns. The workflow would not be:

Email me a prose description of everything you dislike

I send you a completely rewritten document

Then compare the two files and figure out whether I understood you

That is absurd—this workflow has been solved for decades by comments and tracked changes in Word, or by Suggesting mode in Google Docs.

Want to see it in action? spoiler

Working with AI in Markdown and where it breaks

Let's play through the process of creating a document—and iterate once.

A prompt to Claude:

Please write a little story about a pelican on a bike in Markdown, and add a small SVG illustration of the pelican.

This results in:

Markdown

Markdown
`### A Poor Pelican Perry the pelican found a bright red bicycle leaning against the pier—and, after one curious glance, decided it was exactly the sort of adventure the morning required. He wobbled past the fishing boats, rang the tiny bell with his beak, and rolled onto the beach—just in time for breakfast. ![pelican](./pelican-on-a-bycicle-v1.svg)`
Rendered
A Poor Pelican Perry the pelican found a bright red bicycle leaning against the pier—and, after one curious glance, decided it was exactly the sort of adventure the morning required. He wobbled past the fishing boats, rang the tiny bell with his beak, and rolled onto the beach—just in time for breakfast.

### A Poor Pelican
Perry the pelican found a bright
red bicycle leaning against the pier—and,
after one curious glance,
decided it was exactly the sort of adventure
the morning required.
He wobbled past the fishing boats,
rang the tiny bell with his beak,
and rolled onto the beach—just in time for breakfast.
![pelican](./pelican-on-a-bycicle-v1.svg)

Rendered

A Poor Pelican

Perry the pelican found a bright red bicycle leaning against the pier—and, after one curious glance, decided it was exactly the sort of adventure the morning required. He wobbled past the fishing boats, rang the tiny bell with his beak, and rolled onto the beach—just in time for breakfast.

Step one: Collecting and formulating the critique

Turning your feedback into useful instructions is already a precision problem.

The headline promises the wrong story. Remove the em dashes, shorten the second sentence, fix the pelican's head, put the left foot on a pedal, and make the bird look sportier.

That sounds specific. It is not.

“The headline” works only because this toy document has one obvious headline. In a longer article you need to describe the headline you want to change.

“The second sentence” is way more specific, but it makes both the reviewer and the AI count sentences, hoping both count them the same way.

“The left foot” is worse: prose cannot point to the exact shape in the SVG that broke the illusion. That is why tools such as Figma allow comments directly on the design surface.

Now try giving the same kind of feedback on a multi-page document with repeated headings, nested tables, diagrams, and code.

Please update the second image in the third paragraph that displays the network architecture. Move the backup server to the top right, next to the second database server, in read-only mode.

In larger documents, another problem emerges: collecting the feedback in the first place. While reading paragraph 1, one may think, “This doesn't make sense,” but maybe paragraph 3 explains it. When such a thought comes up, I don't want to stop reading and formulate a prompt. I want to leave a mark, continue reading, and come back later.

Step two: Understand the change

Several approaches can help, but they share the same weakness: the AI produces a new document before the author can review the proposed changes in context.

We are still in the first iteration. An update executed by an LLM does not mean that our feedback was taken into account or that our intent was met. We are left with two tasks:

Find the change. One round of “spot the difference” across the whole document. Git can show diffs, but changes hidden behind rendered Mermaid diagrams, tables, and SVGs are much harder to grasp.
Recover the intent. Once we know what changed, we still have to remember which part of our original prompt the change was meant to address and decide whether the result actually satisfies the feedback.

Remember that more specific prompt:

shorten the second sentence

What if the first sentence is dropped in the rework by the AI? Mapping this prompt to the intent means:

What was sentence 2 before the change?
How did this sentence change?
Does this reflect the intent of being shorter?

We should only care whether that sentence is now shorter.

The Idea—Suggestion Mode for Markdown

What is needed is a way to annotate parts of the document directly instead of describing their location vaguely, along with a way to review proposed changes against those annotations.

This is exactly what Markleft provides. It is based on three main components:

A WYSIWYG Markdown editor for humans to create and edit comments, propose changes, and apply suggestions without thinking about the underlying format.
A Markdown-compatible annotation spec consumable by AI, allowing users to comment on text, code, tables, Mermaid diagrams, images, and SVGs, and to propose suggestions.
A prompt that tells the AI how to address the comments and instructs it to append suggestions only in Markleft.

AI gives you a Markdown . By clicking a bookmark you can review it as a Markup. You have remarks? Leave a note and save the Markdown. The file has a Markleft now. Pass it back to AI. Instead of a rewrite it makes Suggestions you can check and see if they cover your Markright.

Markdown remains the document format.

Markleft

The spec uses ordinary Markdown constructs to enable suggestion mode.

Markleft - the editor

The Markleft editor operates on local Markdown files. It runs as a bookmarklet in Chrome, so you can open a Markdown file, activate the bookmarklet, and get a full-featured editor with comments and suggestions.

It reads the Markdown file, parses its footnotes into Markleft annotations, comments, and suggestions, and renders them.

If a user comments on a selection or places a marker inside an image, the editor injects a corresponding Markleft footnote. When the user saves the file, the editor compiles a prompt that explains Markleft to the AI and describes how to compose suggestions that address the comments.

The AI composes suggestions and appends them to the Markdown file. The editor detects those changes and renders the new suggestions with links to the comments they address. Text is diffed within corresponding rendered elements. List items and table cells are paired before their text is compared, avoiding one meaningless diff across an entire structure. Image-only replacements become a before-and-after slider.

See it in action

Markleft - the spec

Annotations are just Markdown footnotes

An annotation—like a comment—consists of two parts: an anchor that identifies what it comments on and the comment itself. Markdown has a concept of footnotes that most Markdown renderers support. An anchor uses the format [^id-of-the-footnote], while its definition appears on a separate line in the format [^id-of-the-footnote]: body of the footnote. To encode additional information—such as selected words or x/y coordinates inside an image—we use a schema in the footnote ID itself.

For a text range:

This sentence needs less ceremony.[^range-prev-12-chars-14824-a1b2]

[^range-prev-12-chars-14824-a1b2]: Make this more direct.

range-prev-12-chars says that the annotation covers the previous twelve visible, non-whitespace characters. The remaining components provide identity and a content fingerprint so Markleft can detect when an anchor has become stale.

Other IDs encode other kinds of anchors:

image-X-Y-* stores normalized image coordinates.
code-line-L-col-C-len-N-* identifies a code range.
block-* addresses the containing block.
comment-* represents a reply to another comment.

Because the comment is a footnote, Markdown tools preserve it even when they do not understand Markleft. To a normal renderer such as GitHub, it is just a footnote. To the AI and the Markleft editor, it identifies a point on an image or a highlighted sentence inside a text block.

Stable block IDs make structural changes addressable

To allow suggestions to target blocks reliably, we need stable identifiers. Markleft injects an HTML comment immediately before each real document block:

<!- - markleft:block id="babf825b" -->

Suggestions are unreferenced, append-only footnotes

A suggestion is a footnote definition with a reserved ID and intentionally no inline footnote anchor in the original body.

[^suggestion-s2-update-block-babf825b]: replacement Markdown

The ID says:

this is suggestion s2;
the operation is update;
the target is block babf825b.

Insert-before, insert-after, and delete operations use the same pattern. The last line of a suggestion body contains footnote anchors for the comments the suggestion addresses; that line is metadata, not part of the proposed content.

This is the crucial append-only property: an AI can add a proposal without receiving permission to alter the document it is reviewing.

Give it a try

Show the bookmarks bar (⌘⇧B on macOS or Ctrl+Shift+B on Windows/Linux) in chrome
Drag this link: Open in M← into chromes bookmark bar.
Open a local Markdown file in chrome and click the bookmark

Find the source code and a full installation instruction here: https://github.com/martin-lysk/markleft

SQLite on Git, Part II: Unlocking Zlib's less known Feature

Mon, 06 Apr 2026 00:00:00 GMT

import { describe, it, expect } from "vitest";
import { execSync } from "child_process";

import fs from "fs";
import { tmpdir } from "os";
import { join } from "path";
import * as pako from "pako";
import { BlockInflate, ChunkBlockDeflate } from "@talepack/zlib-random-access";

describe("loose object test", () => {
	it("should create a simple git blob and verify its content", () => {
		// Create a temp dir
		const tempDir = fs.mkdtempSync(join(tmpdir(), "git-simple-test-"));

		try {

			// ------------------------------------------------------------------
			// 1. Create a normal git object containing 
            // `Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.`
			// ------------------------------------------------------------------

			// Create a git repo in it using init
			execSync(`git init "${tempDir}"`, { encoding: "utf-8", cwd: tempDir });

			// Create a readme containing "Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on."
			const readmePath = join(tempDir, "readme.md");
			fs.writeFileSync(readmePath, "Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.");

			// Use git add to add the readme
			execSync(`git add readme.md`, { encoding: "utf-8", cwd: tempDir });

			// Use `git hash-object readme.md` to get the hash
			const hashOutput = execSync(`git hash-object readme.md`, {
				encoding: "utf-8",
				cwd: tempDir,
			}).trim();
			const blobHash = hashOutput;

			// ------------------------------------------------------------------
			// 2. Read the deflated blob content and inflate it using pako and split the content into `header`, `block 1` and `block 2`
			// ------------------------------------------------------------------

			// Read the compressed blob file content
			const objectPath = join(
				tempDir,
				".git",
				"objects",
				blobHash.slice(0, 2),
				blobHash.slice(2)
			);
			const compressedData = fs.readFileSync(objectPath);

			// Use pako to inflate the blob file into a buffer
			const inflated = pako.inflate(compressedData);
			const inflatedString = Buffer.from(inflated).toString("utf-8");
			
			// Verify the content matches "blob 12\0hello world"
			// The format is: "blob \0"
			// "hello world" is 12 bytes
			console.log("inflatedString should be: 'blob 97\0Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.'\n", inflatedString === 'blob 97\0Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.', '');
			expect(inflatedString).toBe("blob 97\0Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.");

			const header = inflatedString.split("\0")[0]! + "\0";
			const block1 = inflatedString.substring(header.length, header.length + 61);
			const block2 = inflatedString.substring(header.length +  61);

			expect(header).toBe("blob 97\0");
			console.log("header", header);

			expect(block1).toBe("Hi beautiful World, how you are doing on this beautiful World");
			console.log("block1", block1);
			
			expect(block2).toBe(", what a beautiful World to live on.");
			console.log("block2", block2);	

			// ------------------------------------------------------------------
			// 3. Create a ChunkBlockDeflator and push the header, then push block 1, then push block 2 with `Z_FULL_FLUSH`
			// ------------------------------------------------------------------


			const deflate = new ChunkBlockDeflate({ level: 6 });
			deflate.pushChunk(Buffer.from(header), "this-magic-parameter-comes-later");
			deflate.pushChunk(Buffer.from(block1), "this-magic-parameter-comes-later");
			deflate.pushChunk(Buffer.from(block2), "this-magic-parameter-comes-later", true);

			const deflationInfo = deflate.deflationInfo


			// ------------------------------------------------------------------
			// 4. Store the deflated result back into the blob
			// ------------------------------------------------------------------

			// remove the original blob file to make sure we are not just reading the same file again
			fs.unlinkSync(objectPath);

			// Write the block deflated blob
			fs.writeFileSync(objectPath, deflate.result);
			execSync(`chmod 444 "${objectPath}"`, { encoding: "utf-8" });

			// ------------------------------------------------------------------
			// 5. Check if git still reads the object
			// ------------------------------------------------------------------

			// Verify with git cat-file -p
			const catFileOutput = execSync(
				`git cat-file -p ${blobHash}`,
				{ encoding: "utf-8", cwd: tempDir }
			);

			expect(compressedData.length).not.toBe(deflate.result.length);
			const gitContent = Buffer.from(catFileOutput);
			const gitContentStr = gitContent.toString("utf-8");

			expect(gitContentStr).toBe("Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.");
			console.log("gitContentStr should be: 'Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.'\n", gitContentStr === 'Hi beautiful World, how you are doing on this beautiful World, what a beautiful World to live on.', '');

			// ------------------------------------------------------------------
			// 6. Read the deflated bytes from block 2 and inflate them independently
			// ------------------------------------------------------------------
			const objectFileHandle = fs.openSync(objectPath, 'r');
			const block2Deflated = new Uint8Array(deflationInfo.blocks[2]!.end - deflationInfo.blocks[2]!.start);
			fs.readSync(objectFileHandle, block2Deflated, 0, block2Deflated.length, deflationInfo.blocks[2]!.start);

			const inflatedBlock = BlockInflate.inflateBlockChunk(block2Deflated, {
				deflationInfo: deflationInfo ,
			});

			
			const block2DeflatedString = new TextDecoder().decode(inflatedBlock as Uint8Array)

			expect(block2DeflatedString).toBe(", what a beautiful World to live on.");
			console.log("block2DeflatedString should be: ', what a beautiful World to live on.'\n", block2DeflatedString === ', what a beautiful World to live on.', '');

		} finally {
			// Clean up temp directory
			execSync(`rm -rf "${tempDir}"`, { encoding: "utf-8" });
		}
	});

});

How I manage Images for my Blog

Sun, 29 Mar 2026 00:00:00 GMT

TL;DR I use an Excalidraw, wrap the elements of interest with a frame, name it with export_ prefix, my forked excalidraw extension automatically generates SVGs for light and dark mode.

Using Excalidraw

I used Excalidraw a lot in the past.

When breaking down a technical problem for myself
When explaining a concept or an architecture to my coworkers.

Just recently a new usecase evolved.

Expressing my thoughts in my Blog.

While writing my first article the dependency between graphics and the text lead to a lot frustration. Fine-tuning the graphic led to an easier text. Changes in the text made me realize that some information in the graphic is not needed to grasp what should land.

The Problem

Every change in a graphic in Excalidraw meant 9 clicks in Excalidraw.

Selecting the frame
pressing export
choose the right name + darkmode/lightmode postfix
export
switch light/dark mode
choose the right name + darkmode/lightmode postfix
export again
realize that one label crossed the frame boundary
starting at 1 again.

It took me about 45 seconds.

The solution

Automate it :-) .

Image © Randall Munroe, XKCD.com

First approach - the GitHub action

...20 minutes later... A bit of bash thanks to open source (specifically JonRC's excalirender) - it worked...

A little GitHub action that:

looks for changed excalidraw files in the last push,
uses jq to find frames inside of those,
exports them in dark and light mode as [framename]-[light/dark],
commits those new svg files to the repo again.

See code here:

SQLite on Git, Part I: The .git folder - Falling down the Rabbithole

Tue, 24 Mar 2026 00:00:00 GMT

npx node -e '

const { readFileSync } = require("fs");
const { inflateSync } = require("zlib");

const compressedData = readFileSync(".git/objects/5e/1c309dae7f45e0f39b1bf3ac3cd9db12e7d689");

const inflated = inflateSync(compressedData);
console.log(inflated.toString("utf-8"));

SQLite on Git, Prologue: Why do we need random access in git

Mon, 23 Mar 2026 00:00:00 GMT

In the upcoming series of blogposts I'm going to share the results of my research over the last years.

The result: A way to enable random read and write access in git's storage, driving a version controlled fs that allows to run versioned sqlite database on top of git's internal storage.

Prologue

Random what? - an analogy

Do you recall the walkman and how much fun it was to find that one track on your mix tape? The Discman (with anti-shock ;-) is random access.

⁠

Photo by Florian Schmetz on Unsplash

Too Young? You are watching this livestream and you're waiting for a specific topic that should get covered today. The recording is random access.

Random access is a core feature of every filesystem - It allows you to jump to your favorite second in a song (.mp3 file) or a scene in your Movie (.mpeg file), skim through huge PDF files. It is the primitive that enables SQLite – a file based database – to return that one row you are interested in from a gigabyte-sized file even on small devices.

The Problem - git doesn't have random access

In git it's only possible to read and write a file as a whole - if you would want to access only parts of your file, like skipping to the last chapter of a movie inside of a video file, when stored in git, you have to read the whole file once - it's like your Walkman's fast forward button - compared to Discman's next button - slow. File formats that are designed on the concept of random access face a bottleneck - and fall back to the good old "fast" forward button.

Why Random access in git in the first place?

The original motivation behind the research: Sqlite inside git to get a local first, distributed Database with version control. Think of it as dolt but inside of your repository - alongside your code.

Note

The need to store structured data in git came from my previous work on Inlang. This involved various crazy approaches like mergeable file formats in git. We concluded we need a database - and shouldn't reinvent one.

What if you could combine the query capabilities of a database with the version control and distribution of git? What if your SQLite database could live alongside your code, tracked through commits and branches, mergeable and distributable like the rest of your repository?

This requires a filesystem layer backed by block storage with random access. Git as a storage layer misses exactly that.

Can it be added?

This question sent me down a rabbit hole: looking at how researchers in nucleotide sequence alignments deal with a similar problem, finding a flag in a thirty year old spec of a widely used compression algorithm, unearthing nerdy conversation histories from git creator Linus Torvalds and the maintainers of git and a lot of digital duct tape - and finally how this could solve some scaling issues Git faces today.

If this sounds interesting - follow me 🐇.

Combining a filesystem with a solid git backed storage actually solves a much broader problem. Read more here

Making NFS3 reactive

Mon, 23 Mar 2026 00:00:00 GMT

Network File System (NFS) provides a powerful way to built a vfs on OSx, but it has a fundamental limitation when it comes to event asdasdpropagation. This article explores how event delegation works in NFS, the challenges with remote changes, and an approach to ensure proper notificatioasdn delivery to client applications using a side-channel.

The topic outlined here is part of a bigger research on a Gerneral Network Filesystem (GNFS) together with the braid.org group - If you want to learn more checkout https://braid.org/apps/gnfs

Standard File System Event Flow

Before diving into NFS specifics, let's understand how file system events work in a local environment:

Application Write: An application (e.g., Emacs) writes to a file
File System Update: The file system modifies the inode content
FSEvent Trigger: On macOS, the FSEvent system detects this change
Event Propagation: FSEvents propagates an event with the flag itemModified (or similar)
Observer Notification: Registered observers (Finder, Quick Look, etc.) react to these changes

This flow ensures changes made by Emacs are immediately propagated to applications listening to file system changes lik Finder's Quick Look and other applications.

NFS Event Delegation Architecture

When working with files on an NFS-mounted drive, the event flow becomes more complex. The delegation pattern involves multiple layers:

Local Change Flow (Client-Initiated)

When a change originates from the client itself, the flow works as expected:

In this scenario, the complete event chain functions correctly. When you work locally on an NFS drive, changes made in Emacs will eventually reach Finder and other observers.

The Problem: Remote Changes

An issue arises when changes originate from outside the client's local filesystem:

The Breakdown: The NFS3 protocol lacks a function to propagate changes on the server back to the client. There is no reverse notification channel, meaning the client remains unaware of changes happening remote.

Workarounds and Limitations

Applications have developed various workarounds to cope with this limitation:

Polling: Some applications poll at regular intervals to check for changes
Focus-based Checks: Applications like VSCode check for file changes when the window regains focus

Limitations:

The NFS client may caches file attirbutes locally even with polling the client may misses changes
Some applications do not poll - Finder, for example, relies entirely on attribute change events

The Solution: Event Side Channel

To address this architectural limitation, below, I describe a way to use a "side channel" approach to address these limitations and ensures remote changes properly propagate to client observers.

Architecture

The side channel inserts an additional layer into the NFS server's event processing:

How It Works

Remote Detection: A remote actor performs a change remotely - here a put on the backing state
Backing State Update: the NFS server reconises the change - The backing state notifies the server via send()
Side Channel Activation: Instead of doing nothing, the side channel:
- Generates a synthetic file write operation on the file system
- registers a sidechannle write on the NFS Server
- This write targets the specific file that was remotely changed
NFS Client Processing: The NFS Client forwards the write operation to the NFS Server
NFS Server Processing: The NFS Server receives the write operation and
- It recognizes this as a side channel operation
- Does not forward the write back to the backing state (preventing loops)
- And returns a success result for the write operation, together with the latest attributes of the changed file state from the backing state
Event Generation: The NFS client, having seen a "write" on the file, now triggers an FSEvents like the write was comming from just another local application
Observer Notification: All registered observers receive the change notification

Key Characteristics

Transparent to Applications: The change appears exactly as if it originated locally
No Redundant Operations: The side channel write is intercepted before reaching the backing state
Event Loop Prevention: By intercepting the write, we prevent infinite loops
Standard Event Semantics: Applications receive standard FSEvents with proper flags

Benefits

This side channel approach ensures that:

Consistency: Remote changes appear identical to local changes from the perspective of client applications
Real-time Updates: No need for polling or delayed checks
Universal Coverage: All FSEvent observers receive notifications, regardless of whether they implement polling
Standard Compliance: The solution works within existing file system event frameworks without requiring application changes

Conclusion

The NFS event delegation side channel can bridges a critical gap in distributed file system event propagation. By leveraging the existing client-side event generation mechanisms through synthetic writes, remote changes are properly notify all observers, maintaining the expected file system behavior across local and network boundaries.

Martin Lysk Blog RSS Feed

Markleft: How I review claude plans in Markdown

Working with AI in Markdown and where it breaks​

A Poor Pelican​

Step one: Collecting and formulating the critique​

Step two: Understand the change​

The Idea—Suggestion Mode for Markdown​

Markleft​

Markleft - the editor​

See it in action​

Markleft - the spec​

Annotations are just Markdown footnotes​

Stable block IDs make structural changes addressable​

Suggestions are unreferenced, append-only footnotes​

Give it a try​

SQLite on Git, Part II: Unlocking Zlib's less known Feature

How I manage Images for my Blog

Using Excalidraw​

The Problem​

The solution​

First approach - the GitHub action​

SQLite on Git, Part I: The .git folder - Falling down the Rabbithole

SQLite on Git, Prologue: Why do we need random access in git

Prologue​

Random what? - an analogy​

The Problem - git doesn't have random access​

Why Random access in git in the first place?​

Can it be added?​