For the past day or so, I have had my head down, tear­ing my hair out, try­ing to de­bug a sig­nif­i­cant block caused by many en­gi­neers’ arch neme­sis: a flaky test. In my case, it’s ac­tu­ally been sev­eral flaky tests.

A flaky test is any test for your code that only some­times fails. It shows up when a part of your test re­lies on some­thing non-de­ter­min­is­tic. Non-de­ter­min­is­tic com­po­nents can in­clude:

• Fetching re­sources over a net­work con­nec­tion.
• Reading from a ran­dom num­ber gen­er­a­tor.
• Using a non-de­ter­min­is­tic asyn­chro­nous sched­uler.
• Animations (often use the GPU).
• …and many more.

If your ap­pli­ca­tion in­cludes code that looks any­thing like these, you are at risk for flaky tests.

My use-case hap­pened to be es­pe­cially vul­ner­a­ble to these, since our in­te­gra­tion tests run against a wide va­ri­ety of text ed­i­tors. See my orig­i­nal blog post for more de­tails.

Flaky Tests SUCK

It’s hard to ex­press how frus­trat­ing a flaky test can be if you have not ex­pe­ri­enced a bad one your­self. In short, they slow de­vel­op­ment time, cause un­in­ten­tion­ally brit­tle soft­ware, and they can cre­ate a lot of frus­tra­tion for users, since the is­sues they al­low into pro­duc­tion are in­con­sis­tent. They make all the ef­fort put into pro­duc­ing tests, wasted.

Tests are de­signed to catch bugs be­fore they get into pro­duc­tion. If a test ex­pects cer­tain be­hav­ior out of non-de­ter­min­is­tic sys­tems, these tests can pass lo­cally and in con­tin­u­ous in­te­gra­tion, but fail on a user’s de­vice.

This is a prob­lem pri­mar­ily for users, but also for de­vel­op­ers. It’s good if a flaky test fails in CI. After all, that is how you know it ex­ists. But it is very bad if a flaky test fails in CI and the orig­i­nal au­thor of the test is no longer around. In that case, it be­comes dif­fi­cult to de­ter­mine which non-de­ter­min­is­tic sys­tem is caus­ing the fail­ure, and thus how to fix the un­der­ly­ing bug rep­re­sented by the flak­i­ness.

Prevention

The best way to get around flaky tests is to make it as dif­fi­cult as pos­si­ble to cre­ate them in the first place.

When I first started us­ing Playwright about a year ago, I did­n’t think too much about its con­fig­u­ra­tion. Boy was that a mis­take.

I re­ally like Omakase soft­ware, and I had (mistakely) as­sumed that Playwright was an ex­am­ple of it. Thus, I as­sumed a de­fault con­fig­u­ra­tion for my pro­ject and let it be. While Playwright is a phe­nom­e­nal tool, I ended up be­ing wrong. The de­faults I re­ceived from my pro­ject tem­plate were not op­ti­mal, and they would sub­tly waste a lot of my time over the next year. You see, there is con­fig­u­ra­tion for Playwright that can pre­vent most flaky tests from en­ter­ing your code, and they aren’t set up by de­fault.

To avoid most is­sues, change these two set­tings:

export default defineConfig({
    retries: 0, // Was 4 by default.
    repeatEach: 2, // Was 0 by default.
});

In my pro­ject, I added a small nudge to dis­cour­age peo­ple from re­mov­ing these:

export default defineConfig({
	/** Extremely important to avoid flaky tests. DO NOT CHANGE or I will kill you. */
	retries: 0,
	/** Extremely important to avoid flaky tests. DO NOT CHANGE or I will kill you. */
	repeatEach: 2,
});

I jest, of course.

What do they do? They are pretty self-ex­plana­tory. retries: 0 will con­fig­ure Playwright to never retry a test if it fails. If it fails, it is re­ported as a fail­ure and your con­tin­u­ous in­te­gra­tion will stop, forc­ing a hu­man to deal with it. repeatEach: 2 will run each test twice. A po­ten­tial flaky test might pass on the first round, but is much less likely to pass twice. Some flaky tests may still sneak through. You may want to con­fig­ure it more ag­gres­sively in some stages of your CI/CD pipeline.

I have no­ticed that AI agents are es­pe­cially prone to pro­duc­ing flaky tests, since they will of­ten sim­ply run a test again and again un­til it passes.

Debugging

As for de­bug­ging, I can pro­vide no bet­ter ad­vice than I typ­i­cally do:

• Use a de­bug­ger.
• Use git bisect if nec­es­sary (or have an agent do it).
• Work slowly and me­thod­i­cally. Slow is smooth, smooth is fast.

neo­engi­neer - noun

An in­di­vid­ual, part of a resur­gence, who em­braces and re­spects the craft of en­gi­neer­ing. Often en­joys solv­ing hard prob­lems.

I was re­cently in­tro­duced to the term “neoengineer”, whose de­f­i­n­i­tion you will find above and in the at­tached blog post. It tick­led my brain in a rare way.

For sev­eral years in a row, my New Year’s res­o­lu­tion was to be­come “the most ef­fec­tive per­son pos­si­ble”. In some ways, that re­mains my pri­mary res­o­lu­tion. To put it an­other way: I seek to be­come the most ef­fec­tive en­gi­neer pos­si­ble.

I think what makes the term “neoengineer” so tick­lish to my gray mat­ter is that it draws a line be­tween those who care about the craft and those who do not. What’s more: the term does not make a lack of care seem like a bad thing. It is merely a dif­fer­ence in pri­or­i­ties.

You Can Choose to Be a Neoengineer

In the dis­course, both within Automattic and at large, we con­stantly re­fer to some un­quan­tifi­able met­ric known as “productivity”. We seek to op­ti­mize it and in­crease it to what­ever ex­tent pos­si­ble. Why? Be­cause we be­lieve that it will make us more money, or bring us more pres­tige, or some­how even bring us hap­pi­ness. I think we are fo­cused on the wrong thing.

When we fo­cus on “productivity” we are fo­cus­ing on our out­put. But be­cause it is in­her­ently un­quan­tifi­able, we are un­able to ob­jec­tively mon­i­tor that out­put. Be­cause there is no way to quan­tify it, it’s im­pos­si­ble to know if we have im­proved our pro­duc­tiv­ity or not, which re­sults in one of two things.

In one sit­u­a­tion, a per­son can be­lieve an ac­tion, habit, or tool is more help­ful than it re­ally is. You see this all the time with vibe-coders. They find that they are able to pro­duce a ton of stuff, but that stuff has zero to neg­a­tive value, and thus no one con­sumes it. In this way, they waste a lot of time do­ing some­thing that amounts to very lit­tle.

That is not a knock on vibe-cod­ing. It’s a knock on a fail­ure to con­sider the value of an ac­tion prop­erly.

In an­other sit­u­a­tion, a per­son can be­lieve an ac­tion, habit, or tool is less help­ful than it re­ally is. I see this of­ten with un­der-plan­ners. A per­son un­der­es­ti­mates the value of do­ing re­search or pro­duc­ing a plan. They think, “I will just get started and pivot later if nec­es­sary”. In this way, they spend less time do­ing some­thing help­ful than they should have.

If we change the frame of ref­er­ence a lit­tle, we earn our­selves ac­cess to a neat men­tal trick. In­stead of ask­ing the ques­tion “does this tool make me more pro­duc­tive?”, ask “would an ef­fec­tive en­gi­neer use this tool?” You may re­place “this tool” with “this habit” or “this ac­tion”.

When I do this, I find the an­swer changes dras­ti­cally.

Would an ef­fec­tive en­gi­neer choose to learn a com­plex al­go­rithm deeply, or would they choose the easy route and ask ChatGPT to write the code for them? They would choose the for­mer, since it in­creases their per­sonal level of skill and im­proves main­tain­abil­ity of the pro­ject long-term.

Would an ef­fec­tive en­gi­neer ap­prove code that is dif­fi­cult to read, so they can go ahead and al­lo­cate their men­tal en­ergy to some­thing more pro­duc­tive? No. They would give care­ful mea­sured feed­back or none at all. If some­thing else is more im­por­tant than re­view­ing the code, an ef­fec­tive en­gi­neer would do that other thing.

By choos­ing to adopt the iden­tity of an ef­fec­tive en­gi­neer, I cre­ate a habit of choos­ing to do things an ef­fec­tive en­gi­neer would do. Even if I am not in fact, an ef­fec­tive en­gi­neer, I can come closer to be­com­ing one by adopt­ing that iden­tity.

The Term Itself

The only is­sue I have with the term “neoengineer” is that when bro­ken down, it means “new en­gi­neer”. Neo- usu­ally refers to some­thing “new” or “young”. So a “neoengineer” is a young en­gi­neer, per­haps of the lat­est gen­er­a­tion.

The thing is, I do not think that the lat­est gen­er­a­tion is the only gen­er­a­tion who has cared about the craft of en­gi­neer­ing. I be­lieve that re­spect for the craft goes back thou­sands of years. If any­thing, it feels like forces are push­ing the lat­est gen­er­a­tion to care less about the craft than ever be­fore.

As an aside, I highly rec­om­mend you check out Jonathan Blow’s fab­u­lous talk, Preventing the Collapse of Civilization. It’s rel­e­vant, I promise.

slop paral­y­sis - noun

A com­plete or par­tial loss of func­tion while re­view­ing the out­put of a cod­ing agent.

Let me paint you a pic­ture.

You have an idea for prod­uct. It could be any­thing: A mo­bile app, a dash­board, or a script to au­to­mate your work. So, you sit down with your fa­vorite LLM and de­scribe your idea. Maybe you have a pretty good un­der­stand­ing of how it should be im­ple­mented. You might even know the over­all struc­ture of the pro­ject in your mind. You tell your cod­ing agent all of this.

Then, you let it loose. It cooks and cleans and im­ple­ments your prod­uct for you. In the end, you have some idea of how the end re­sult works, but it is not com­plete. Since this is a pro­ject that is im­por­tant, which you in­tend to main­tain, you go to read the code. That’s when it hits you. Slop paral­y­sis.

The Problem

Slop paral­y­sis is the com­plete lack of de­sire to re­view the out­put of an LLM. It could show up for any num­ber of rea­sons. The most com­mon, for me, are:

• The sheer amount of code de­mand­ing con­sump­tion.
• Missing con­text (that the agent was aware of, but not you).
• A fear of break­ing some­thing.

In the end, slop paral­y­sis slows you down and makes your life more stress­ful. So, what can we do about it?

Some Solutions

I will de­scribe some so­lu­tions that have worked for me. As al­ways, your mileage may vary.

The ob­vi­ous so­lu­tion is to sim­ply not use an agent. Some­times cod­ing agents make your job eas­ier. Some­times they do not. Knowing which is which is dif­fi­cult, but ex­tremely valu­able.

When you do de­cide to use an agent, you can have the agent sim­ply pro­duce less code. I have heard of pro­jects that help you do this, but I have not ac­tu­ally tried them. In­stead, I ask the agent to make a plan first, then re­work that plan my­self to min­i­mize the num­ber of changes. In the end, a plan which was orig­i­nally writ­ten by the agent be­comes one that has been mer­ci­lessly edited by my­self. In this way, I min­i­mize the amount of code which de­mands con­sump­tion. The side-ef­fect of this is that I then have an ex­cel­lent un­der­stand­ing of what the agent ac­tu­ally does, which helps with the con­text prob­lem.

The fi­nal strat­egy, which I use when all else fails, is to refac­tor the code by hand. When the agent has proven the tech­ni­cal fea­si­bil­ity of the pro­ject, but the code is sim­ply too ex­pan­sive to prop­erly grok all at once, I sit down with a fine-tooth comb and refac­tor it, mod­ule by mod­ule. I do not need to care­fully read each func­tion and eval­u­ate its mer­its, but I do force my­self to, at min­i­mum, lay eyes on them all.

Stay Steady Out There

I find my­self be­com­ing more over­whelmed by the dis­course every sin­gle day. It’s ex­haust­ing how much is hap­pen­ing in the world, and even worst, how much you are ex­pected to care about it all. Take some time for your­self. Save your­self from slop paral­y­sis.

While I was look­ing back through my archive of posts on this blog, I re­al­ized that I never con­cretely de­fined what Radical Speed Month was. I have talked about it a lot, but there is not any one spot I can point to and say “Look there! That’s what RSM was!”

This page will fill that void.

I work at Automattic. We run a lot of prod­ucts and host many ser­vices. I can al­most guar­an­tee that you have used our prod­uct at least once in your life. There are few peo­ple left on Earth that have not.

We like to ex­per­i­ment with new ways of work­ing. Our lead­er­ship team is con­stantly try­ing new things and new ways to get ahead of our com­pe­ti­tion. Rad­i­cal Speed Month, oth­er­wise known as RSM, was one of these ex­per­i­ments.

In short, Radical Speed Month was a month-long sprint where any and all avail­able en­gi­neers were in­structed to stop what­ever they were do­ing and work on some­thing, well, rad­i­cal. Some­thing new. Some­thing in­ter­est­ing. Some­thing no one had ever seen be­fore.

That was the only re­stric­tion, other than work­ing in pairs. Each en­gi­neer, in­clud­ing my­self, found one other en­gi­neer to work with and they spent a month on a pro­ject of their own choos­ing. It was a lot like the hackathons I com­peted in dur­ing my more youth­ful years.

For the in­ter­ested, here is a list of links to some of the posts I made dur­ing or re­lat­ing to RSM:

• Announcing work on our RSM pro­ject.
• Learning from an ex­pert at prod­uct-ori­ented think­ing.
• A quick up­date on our RSM pro­ject.
• Thinking about what makes a good agent (in the LLM sense of the word).
• Reflecting on the pro­ject at large.

I am pleased to say, with much fan­fare, that Andrew Dunbar (known by on­line moniker hip­pi­etrail) is be­com­ing Harper’s first com­mit­ter.

Andrew has been do­ing stel­lar work for the pro­ject for more than a year now. His work on our gram­mar en­gine has been phe­nom­e­nal. Odds are, if you have opened a ticket on GitHub or dropped on com­ment on Discord, he was the first one you spoke to.

He clearly un­der­stands and em­bod­ies Harper’s mis­sion and has demon­strated re­spon­si­bil­ity for the code he sub­mits.

So to­day, we are mak­ing him Harper’s first ex­ter­nal com­mit­ter. That means a lot of dif­fer­ent things, but pri­mar­ily it means that he has the per­mis­sion to merge his own and oth­er’s PRs.

This blog post will not be as long as I wish it to be. I do not have the time nor the pa­tience at the mo­ment to dive as deep into this sub­ject as I feel the sub­ject it­self de­serves. It also will not be as short as I wish it to be. It takes time to de­ter­mine what is im­por­tant and what is not. My hope is that by de­clar­ing this es­say “incomplete”, you will grant me some grace and un­der­stand­ing.

While read­ing an old — un­pub­lished, for now — es­say of mine, I was re­minded of the won­der­ful book by Robert Persig ti­tled Zen and the Art of Motorcycle Maintenance. I read it in high-school, and it has served as the foun­da­tion of much of my world­view up to this point. The book serves to help any­one in any pro­fes­sion, but I think it speaks par­tic­u­larly well to the lives of open source main­tain­ers. Here, I hope to re­flect on its teach­ings and find ways to ap­ply them to the daily rou­tine of open source main­te­nance and de­vel­op­ment.

If you have not read the book yet, please do so now. I am not kid­ding. Stop read­ing this blog post, walk down to your lo­cal book­store and pur­chase a copy. Do not come back un­til you have read it.

For The Disobedient

Since I sus­pect many of my read­ers to be rebels, or oth­er­wise feel re­pelled by great lit­er­a­ture, I will pro­vide a brief overview of the book.

Zen and the Art of Motorcycle Maintenance is not, as you may have guessed, ac­tu­ally about mo­tor­cy­cle main­te­nance. Al­though it con­tains some valu­able tips for those will­ing to get a lit­tle greasy, the book is re­ally about how we per­ceive the world and how to nav­i­gate it with­out go­ing in­sane.

Structurally, it fol­lows Persig on his fic­tional mo­tor­cy­cle trip across the coun­try. Much of the book hap­pens in con­ver­sa­tion with him­self while he rides down var­i­ous roads and high­ways.

While I will save dis­cus­sion of the more im­por­tant mat­ters for a later day, there is one sec­tion that needs ex­pla­na­tion: Persig’s gump­tion traps.

What is a gump­tion trap? A gump­tion trap is some­thing that saps your mo­ti­va­tion for a pro­ject. In the book, Persig de­scribed them in the con­text of — you guessed it — mo­tor­cy­cle main­te­nance, but gump­tion traps lie every­where in day to day life, es­pe­cially for open source main­tain­ers. He de­scribes two types of gump­tion trap: set­backs and hang-ups.

A set­back is any gump­tion trap that is not, for lack of a bet­ter word, your fault. It’s when some­thing that ex­ists out­side of your con­trol im­pacts your abil­ity to get sh*t done. For an open source main­tainer, sup­ply chain at­tacks and — god for­bid — GitHub out­ages count as set­backs. They can of­ten feel out­side of your con­trol. That feel­ing is what drains your gump­tion.

The good news is re­al­ized that there are things you can do to pre­vent set­backs, like lock­ing your de­pen­den­cies and avoid­ing GitHub. Planning ahead, even if it’s hard, can pre­serve your gump­tion for the re­ally fun parts of open source main­te­nance.

A hang-up on the other hand, is a more com­pli­cated kind of gump­tion trap. Hang-ups hap­pen in­ter­nally, and are coun­ter­in­tu­itively more dif­fi­cult to move past. They sap your de­sire to con­tinue work on your pro­ject not be­cause some­thing ter­ri­ble hap­pened, but be­cause there’s some­thing wrong with the way you view the world. Per­sig says there are three im­por­tant kinds of hang-up: value traps, truth traps, and mus­cle traps. I do not think truth traps or mus­cle traps are par­tic­u­larly rel­e­vant to my work as an open source main­tainer, so I will be as­sign­ing in­ter­pre­ta­tion of those as home­work for my read­ers. Value traps, how­ever, are quite rel­e­vant, so I want to go into those in de­tail.

Value Traps

A value trap comes up when some as­pect of your value sys­tem comes into con­flict with the pro­ject it­self.

Stubbornness can stop you from see­ing a good so­lu­tion to a prob­lem be­cause you are too fo­cused on a bad so­lu­tion. Spend­ing a lot of time work­ing on a bad so­lu­tion only see it as it is retroac­tively is a recipe for frus­tra­tion and, of course, lost gump­tion. The so­lu­tion here is to slow down. Spend time look­ing around the pro­ject and make sure all of your as­sump­tions are cor­rect. For open source main­tain­ers, this sec­ond look does not nec­es­sar­ily have to be at the code. It can also be a look at the peo­ple around the code. It’s tempt­ing to be­lieve that you are the only one who can solve each prob­lem. In re­al­ity, there’s likely a com­mu­nity of peo­ple work­ing with you. Maybe a mem­ber of that com­mu­nity has in­sight you do not have. Talk to them.

Boredom can make you sloppy, and sloppy work is bad work, and bad work steeps the gump­tion right out of you. What’s worse is that bore­dom of­ten comes af­ter you have al­ready lost much of your gump­tion. This vari­ant of value trap is ab­solutely not spe­cific in any way to open source, so I will not pre­tend to con­nect the two. Per­sig rec­om­mends tak­ing a rest and get­ting plenty of sleep. What­ever you do, he says, do not keep work­ing. Per­son­ally, when I en­counter this gump­tion trap, I try to work on an­other “project” within my open source pro­ject. Maybe I am not in­ter­ested in de­bug­ging at the mo­ment, so I swap over to writ­ing a new mod­ule in­stead. I can come back to my de­bug­ging task later with a fresh per­spec­tive and a full tank of gump­tion.

Anxiety, per­haps bet­ter char­ac­ter­ized as fear, can stop you from do­ing any­thing at all. I of­ten get anx­i­ety merg­ing PRs, even af­ter I have done all of my due dili­gence and truly be­lieve them to be ready. There is some­thing about hit­ting “merge” that spikes my adren­a­line. But, code ages like milk, so I must merge it any­way. Per­sig sug­gests you do ex­tra due dili­gence if it makes you feel bet­ter. If that does not help, just man up and do it.

Conclusion

The won­der­ful thing about all the gump­tion traps that Persig high­lights is that they are fun­da­men­tally in your con­trol. Some can only be pre­vented, and oth­ers re­quire some level of in­tro­spec­tion, but they all can be man­aged. Now se­ri­ously, if you did not lis­ten the first time: go read the f**king book. Do it.

If you have not al­ready, I highly rec­om­mend that you read Walter Isaacson’s bi­og­ra­phy of Elon Musk. It fol­lows the bil­lion­aire’s stratos­pheric ca­reer from pro­gram­ming video games on an orig­i­nal Commodore VIC-20 to the ac­qui­si­tion of Twitter. While I do not agree with all of his prac­tices or be­liefs, I do think that some of his philoso­phies are ex­tremely ap­plic­a­ble and largely ig­nored, even by his most ar­dent fol­low­ers.

“Delete any part or process you can. You may have to add them back later. In fact, if you do not end up adding back at least 10% of them, then you did­n’t delete enough.” - Elon

In the last week, es­pe­cially since we are in hard­en­ing mode, clean­ing up af­ter the wreck­age of RSM, I have been see­ing an enor­mous num­ber of ex­am­ples demon­strat­ing that dele­tion is usu­ally bet­ter than ad­di­tion. Say­ing “no” is more im­por­tant than say­ing “yes”.

Get Rid of Code

The num­ber of bugs in a pro­gram is roughly pro­por­tional to the num­ber of lines of code. To a shock­ing de­gree. Less code means fewer prob­lems. If you can pro­vide the same ser­vice with less code, pro­vide the same ser­vice with less code.

While this is not a post about cod­ing with AI, I find that mak­ing my agen­t’s plans sim­pler with fewer steps al­most al­ways re­sults in bet­ter code. If most en­gi­neers said “no” to the first plan an agent pro­vided, the qual­ity of the av­er­age pro­gram on GitHub would sky­rocket. But peo­ple do not say “no”. Be the ex­cep­tion.

Get Rid Of Decisions

When an en­gi­neer needs to make a de­ci­sion for whether to work on some­thing (or oth­er­wise al­lo­cate re­sources to a task), they have three op­tions.

1. They can do the thing.
2. They can not do the thing.
3. They can say “we will do that later”.

Almost al­ways, op­tion three turns into op­tion two. Peo­ple pro­cras­ti­nate, and there will al­ways be more ur­gent things to at­tend to. It’s bet­ter to de­cide to do op­tion two in­ten­tion­ally than to let fate de­cide.

So, if you can’t de­cide whether to do some­thing right now, your an­swer should be no. You are free to change you mind later, but do not pre­tend that you will re­mem­ber to de­cide later.

Harper Says “No”

Do we train stuff on our user’s data? No. Do we send data to the cloud? No. Do we waste CPU cy­cles of friv­o­lous things? No.

People use Harper be­cause we say no.

I like Hacker News, but I do not love that so much of it has turned into dis­cus­sion of a sin­gle topic: AI. So, I have cre­ated my own ver­sion. A ver­sion of Hacker News, with­out AI.

HNSansAI pulls from the of­fi­cial Hacker News API, looks through the con­tent of each ar­ti­cle, and dis­cards any that men­tion a term re­lated to “AI”. That in­cludes stuff like:

• “OpenAI”
• “Anthropic”
• “Copilot”
• “LLM”
• …and many more.

I pre­vi­ously posted about our launch of Harper Desktop. If you have not read that al­ready, I sug­gest you take a peek be­fore read­ing for­ward here.

For those caught un­aware, Harper is a gram­mar checker de­signed to re­spect the fact that your writ­ing should be yours. It is pri­vate by de­sign, no mat­ter where you de­cide to use it. Thou­sands of peo­ple from all walks of life use it to ex­press their thoughts on­line, skip­ping all the fea­tures found in other gram­mar check­ers that sup­press cre­ativ­ity and sell text to the high­est bid­der.

Until re­cently, our most pop­u­lar and ver­sa­tile in­te­gra­tion was through a Chrome or Firefox ex­ten­sion. It plugged di­rectly into your browser and in­ter­acted with the var­i­ous text ed­i­tors you might en­counter while brows­ing the web.

While this gave Harper the abil­ity to en­hance the writ­ing of peo­ple who spent much of their time on­line, it did not do much for the mak­ers and do­ers that use desk­top ap­pli­ca­tions like Scrivener, Slack, or Discord. Harper Desktop sought to solve that.

It was build in only a month, with the com­bined ef­fort of just two en­gi­neers, my­self, and Jason Adams. It was pos­si­ble though ded­i­ca­tion, hard work, and a will­ing­ness to learn. Radical Speed Month held an im­pe­tus to ex­per­i­ment, and ex­per­i­ment we did.

In this post, I want to talk about:

1. The ex­per­i­ments Jason and I ran on our­selves.
2. Which we will keep, and which we will not.
3. Sandwiches.

I will not be talk­ing about:

• Why Harper Desktop is awe­some.
• Why you should down­load and in­stall it.
• Pizza.

The Experiments

“AI”

AI is a tool, one which I have writ­ten about ex­ten­sively. Dis­cus­sion of AI is repet­i­tive and hon­estly pretty bor­ing. Which is why my “AI” ex­per­i­ment was not re­ally about AI or LLMs. It was about the kinds of tools I use.

For an ex­ceed­ingly long time, my work­flow has con­sisted of tmux, nvim, and the Rust com­piler. In the last year, that work­flow has grown to in­clude OpenAI’s Codex. I found my­self more pro­duc­tive with it be­cause I could del­e­gate oth­er­wise la­bor-in­tense tasks to it to be com­pleted in the back­ground while I worked on some­thing else.

Even with codex avail­able in my $PATH, I would still write most mis­sion-crit­i­cal code my­self. Part of this was from fear, but there were other more im­por­tant rea­sons too.

I wanted to see what would hap­pen if I com­pletely changed my work­flow, just for one month. I would com­mit my­self to spend­ing as much time with new tools as pos­si­ble. As it would turn out, the only tool I stopped us­ing was Codex.

This is some­thing I spoke about briefly be­fore, but I have de­vel­oped a more com­pre­hen­sive view of the is­sue since, so I’d like to go over it again.

What I Used Instead

Instead of del­e­gat­ing tasks to Codex, I started del­e­gat­ing tasks to OpenCode. I found it far more ef­fec­tive.

To me, OpenCode’s stand­out fea­ture was how cen­tral it made “plan mode”, which gave it per­mis­sion to view (but not edit) my repos­i­tory while I cre­ated a plan. It could com­pare its un­der­stand­ing of my plan with the re­al­ity of the ex­ist­ing code, and ask clar­i­fy­ing ques­tions when am­bi­gu­ity arose. This stood in sharp con­trast to Claude Code and Codex, which would just go and start edit­ing files, re­gard­less of whether a plan was com­plete.

I liked this, but it still left some things to be de­sired.

OpenCode gave me byte-level con­trol over the code it wrote be­fore it started edit­ing, but it did not give me a whole lot of con­trol over OpenCode it­self. I found my­self typ­ing the same things over and over again, wish­ing for some kind of higher level macro sys­tem.

That’s when I found Pi, an “agent” that in­ten­tion­ally does as lit­tle as pos­si­ble. In a lot of ways, it’s like neovim. It does very lit­tle out of the box, but through cus­tomiza­tion it can be­come more use­ful than any­thing else.

Now, I find my­self us­ing Pi more of­ten, not least be­cause it gives me every piece of con­trol I al­ways wish I had. Pi is the only LLM-based tool I have every tried that did not feel like it was ac­tively slow­ing me down.

So in that way, I sup­posed the “AI” ex­per­i­ment was a suc­cess. I will be con­tin­u­ing to use Pi.

Meetups

Jason and I de­cided to work to­gether for Radical Speed Month in part be­cause we lived in “close” prox­im­ity.

You see, Jason and I both work at Automattic, which is a dis­trib­uted com­pany. That means that al­most every­one works re­motely. There are a num­ber of ben­e­fits to em­pha­siz­ing asyn­chro­nous com­mu­ni­ca­tion, and some down­sides. We wanted to get a bet­ter un­der­stand­ing of both the pros and cons by tem­porar­ily in­creas­ing the num­ber of days we spent in-per­son work­ing to­gether.

So, twice a week, we would hop in our cars and meet some­where, usu­ally Castle Rock, CO. We would spend the day talk­ing about big ideas, work­ing on our in­di­vid­ual tasks, and con­sume a likely un­healthy num­ber of sand­wiches.

I per­son­ally found these in-per­son days mo­ti­vat­ing. I would come home at the end of the day ex­cited to get back to work. I felt like I had a re­newed sense of pur­pose and drive. It was in­tox­i­cat­ing.

I think a huge part of this feel­ing was a con­se­quence from Jason’s per­son­al­ity. We seem to mesh to­gether well, and I have no­ticed that he has a ten­dency to am­plify the best qual­i­ties in the peo­ple he leads.

That said, I do not think that 100% in-of­fice work is sus­tain­able in the long term. I found that the days we were to­gether, I was not quite as able to “lock in”. We had fan­tas­tic dis­cus­sions and our de­ci­sion mak­ing process was a mil­lion times faster than it would have been oth­er­wise, but it was just that lit­tle harder to turn the talk into ac­tion. Sim­i­larly, I found it more dif­fi­cult to con­vey cer­tain kinds of tech­ni­cal in­for­ma­tion. When we needed to ex­plain some­thing in depth, I felt the com­pul­sion (which could be fought, I sup­pose) to send a link later, rather than try to ex­plain it in the mo­ment.

In the end, I think that Matt’s orig­i­nal con­clu­sion on mee­tups is still cor­rect. He says that in the same way that “a lit­tle salt makes the dish”, a few mee­tups every so of­ten can bring to­gether the best parts of both in-per­son and re­mote work.

So, I would say that our sec­ond ex­per­i­ment was also a suc­cess. I per­son­ally feel as though I have earned a bet­ter in­tu­ition for what kinds of work are bet­ter in per­son and what are bet­ter async.

The Fallout

Immediately af­ter an­nounc­ing Harper Desktop, I got a flood of mes­sages from peo­ple who had down­loaded it, in­stalled it, and found all the bugs in it. That was both good news and bad news.

It was good be­cause we could be con­fi­dent that we were in­deed build­ing the right thing. Peo­ple want a desk­top ver­sion of Harper and they want to help us make it as awe­some as it can be.

The was bad be­cause, well, there were a ton of bugs. Over the last few days, I have been bak­ing them out of the soft­ware as fast as pos­si­ble. You should be get­ting a sig­nif­i­cantly im­proved piece of soft­ware in the com­ing hours.

Would I have post­poned the launch, had I knew about these is­sues? Yes. But I did not, which is why we do soft­ware launches like this. There’s no way to fully ex­pect every is­sue that comes up, so you need to do a lit­tle ad-hoc user test­ing. I con­sider this a suc­cess.

Conclusion

I re­ally en­joyed Radical Speed Month. It was a hard stretch of learn­ing a lot about a va­ri­ety of sub­jects, most of which I have not even men­tioned in this post. I am en­er­gized and ex­cited to ap­ply them to my daily work, and in hard­en­ing Harper Desktop.

Harper Desktop is fi­nally avail­able for down­load. It’s been about a month since Jason and I started work on it for Radical Speed Month. In that time, we have worked hard to cre­ate a mean­ing­fully func­tional ex­pe­ri­ence and it is avail­able for down­load to­day.

That said, it’s still early work. There are bound to be bugs and edge-cases we have not con­sid­ered. That’s why we are re­leas­ing it un­der a “beta” flag. It’s avail­able, but do not ex­pect a su­per pol­ished ex­pe­ri­ence yet. The hope is that we can work with the com­mu­nity to build a su­per pol­ished and com­fort­able ex­pe­ri­ence, but that will take time and, more im­por­tantly, bug re­ports.

Alongside sup­port for apps like Slack and Discord, Harper Desktop will bring our phe­nom­e­nal gram­mar check­ing to crit­i­cal apps for long-form au­thors, like Scrivener and Microsoft Word.

What’s Next

I plan to en­ter a pe­riod of hard­en­ing, both for Harper Desktop and for every­thing else we of­fer. There’s a back­log of bug re­ports and pull re­quests from the du­ra­tion of Radical Speed Month that needs to be ad­dressed. If you are one of the many peo­ple who opened one of those things over the last month, know that I am not ig­nor­ing you. Give me a sec­ond to catch my breath, and I will get to you.

After that, I hope to work on more ad­vanced style sug­ges­tions, po­ten­tially us­ing the greater com­put­ing power avail­able in the Harper Desktop app. More de­tails to come.

What I Have Learned

Building Harper Desktop has given me a bet­ter un­der­stand­ing of what an ef­fec­tive team looks like. Not just what an ef­fec­tive team does or says or what method­ol­ogy they em­ploy. What they look like.

Harper Desktop was col­lab­o­ra­tion be­tween Jason and my­self. He has far more ex­pe­ri­ence work­ing in teams than I do. The chance to ob­serve the kinds of ques­tions he asks and un­der­stand why he asks them was in­cred­i­bly valu­able, and he car­ries a finely tuned feel­ing of pri­or­i­ti­za­tion that is dif­fi­cult to con­vey over text. He is a man that knows what is im­por­tant, and what is not. I learned a lot from work­ing along­side Jason. I ex­pect to learn more from him in the fu­ture.

With this ex­pe­ri­ence, I in­tend to make some sig­nif­i­cant im­prove­ments to how Harper as an open source com­mu­nity op­er­ates. You should ex­pect to see me be­come more avail­able, more of the time. Af­ter all, we are in this to­gether

The spirit of Radical Speed Month in­cludes an im­pe­tus to ex­per­i­ment. So ex­per­i­ment I have.

In par­tic­u­lar, I have been try­ing two new cod­ing agents: OpenCode and Pi. Both were in­ter­est­ing and taught me some­thing new, but I only in­tend to con­tinue us­ing one of them.

OpenCode

OpenCode caught my eye for the very qual­ity it’s named af­ter: OpenCode is open source.

At first, it seemed to me to be an open source knock­off of OpenAI’s Codex. After a few min­utes of use, though, I dis­cov­ered how it brings “plan mode” front and cen­ter. Claude Code and Codex both in­clude plan mode, but in both cases it feels like an af­ter­thought. I had tried it a few times, but I was left unim­pressed. Not so with OpenCode. It’s a deeply in­te­grated part of the ex­pe­ri­ence. If you are us­ing OpenCode with­out plan mode, you are hold­ing it wrong.

Overall, I found it a far more pro­duc­tive and en­joy­able ex­pe­ri­ence than Codex.

Pi

Pi is amaz­ing. Sim­i­lar to OpenCode, Pi is an open source agent. Un­like OpenCode, it is not de­signed to be a clone of Claude Code or Codex. It is its own thing with an en­tirely sep­a­rate phi­los­o­phy.

It Is Static

Pi was born out of a frus­tra­tion with Claude Code: It did too much, and it changed too of­ten. This is a prob­lem for de­vel­oper tool­ing. De­vel­op­ers ex­pect the sys­tems un­der­ly­ing their tool­ing to be sta­tic, so the tools them­selves only need to change when the re­quire­ments do. This sim­ple idea is why we have stan­dards like Semantic Versioning.

The skills, prompts, and tools we write for our agents de­pend on the un­der­ly­ing be­hav­ior of these agent loops to re­main sta­tic. When Anthropic or OpenAI ad­just the sys­tem prompt or change how the mod­el’s tools are called, the things we build around them break.

Pi is not like that. Pi is in­tended to be as sim­ple as pos­si­ble, and as ex­ten­si­ble as pos­si­ble. An en­gi­neer to au­to­mate tasks us­ing Pi and ex­pect those au­toma­tions to con­tinue work­ing for­ever.

This is im­por­tant to me, and if you are an en­gi­neer, it should be im­por­tant to you.

It Is Extensible

The en­ergy be­hind Pi feels a lot like the en­ergy be­hind Neovim. It’s built for and by a com­mu­nity of hack­ers, who each have their own cus­tom setup.

I have only been us­ing it for a few days, but I al­ready feel an in­de­scrib­able sense of own­er­ship over my prompts, skills, and the ex­ten­sions I have in­stalled. When I feel a de­fi­ciency in my work­flow, I do not feel that I need to wait un­til Anthropic or OpenAI has time to ad­dress it. I can ad­dress it my­self.

Think Critically

If you are not ac­tively push­ing your brain to it’s limit while pro­gram­ming — whether you are us­ing an agent or not — you are not do­ing your best work. Try­ing both of these agents has taught me that it is en­tirely pos­si­ble to push my brain hard while also us­ing an agent to take away some of the te­dium. In the end, I get bet­ter soft­ware faster.

This week of Radical Speed Month has been ded­i­cated to putting the dis­parate com­po­nents of the Harper Desktop App to­gether. In other words, we have been in what Shane Wighton would call “integration hell”.

Due to the con­straints put in place by the op­er­at­ing sys­tem and our de­ci­sion to use Tauri, Harper Desktop needed to be split into three main pieces: the high­lighter process, the main Rust Tauri process, and the Svelte fron­tend. We use the main Rust Tauri process as the source-of-truth for all user con­fig­u­ra­tion and state, which meant we needed to or­ches­trate a non­triv­ial amount of com­mu­ni­ca­tion be­tween it and the other two com­po­nents.

At the same time, I’ve been in­te­grat­ing every­thing (including Jason’s won­der­ful re­vamp of the Harper ed­i­tor) into the main Harper repos­i­tory. It’s been a slow go­ing process, and there is still some work to be done with CI. At the same time, it’s quite sat­is­fy­ing to see every­thing click into place.

Next, we plan to fo­cus our at­ten­tion on the more fit-and-fin­ish pieces of the pro­ject. That means wrap­ping up the im­ple­men­ta­tion of cer­tain parts of the con­fig­u­ra­tion, build­ing out up­dat­ing logic, and cre­at­ing an ac­tual down­load page on our web­site.

Working this past week with Jason Adams has given me a brand-new ap­pre­ci­a­tion for the cat­e­gory of ideas that we en­gi­neers call “product.”

For a long time, I’ve dis­cussed the dif­fi­cult-to-de­fine word “Quality” and it’s im­por­tance to the suc­cess of soft­ware pro­jects. To me, cap­i­tal “Q” Quality meant that a piece of soft­ware was fast, ex­ten­si­ble, and re­li­able. It was a check­list and a se­ries of met­rics that could be tracked and op­ti­mized through it­er­a­tion. I had, and ar­guably still have, an en­gi­neer’s de­f­i­n­i­tion of “Quality”.

But the ver­sion of Quality that can be de­fined with num­bers is not com­plete. A com­plete de­f­i­n­i­tion of Quality in­cludes some­thing that I cur­rently don’t know how to de­fine. Peo­ple like Jason Adams and Eduardo Villuendas can.

At the end of Radical Speed Month, my goal is to be able to de­scribe it, at least shal­lowly. Right now, I feel that I un­der­stand some of the base com­po­nents, but not well enough to bring them to­gether into a co­he­sive whole.

Harper Desktop

Harper Desktop is com­ing along amaz­ingly! My goal for this week was to get the full pipeline work­ing. That means:

1. Reading text from ar­bi­trary text ar­eas on ma­cOS.
2. Locating er­rors within it us­ing harper-core.
3. Rendering high­lights over those er­rors.
4. Showing a sug­ges­tion popup to users so they can re­view po­ten­tial cor­rec­tions.
5. Applying the cor­rec­tions.

This is a pipeline that we’ve suc­cess­fully repli­cated in sev­eral other apps, but this is the first time we’ve tried to do it sys­tem-wide. I’m pleased to say: It’s all work­ing!

The only thing miss­ing from a “complete” Harper Desktop ex­pe­ri­ence is con­fig­u­ra­tion. Users need to be able to ma­nip­u­late their dic­tio­nary, up­date their rule pref­er­ences, and whitelist (or black­list) apps from be­ing ma­nip­u­lated by Harper.

Fortunately, Jason Adams has been hard at work re­fin­ing what Harper’s set­tings menus look like. Ac­tu­ally, to say that is all he has been do­ing would be disin­gen­u­ous. In re­al­ity, he has been re­vamp­ing the en­tirety of Harper’s de­sign and look.

The hope is that much, if not all, of Jason’s work here will be ported back to the Chrome Extension.

The Magic of Meetups

I have never felt the magic of mee­tups more than dur­ing the short sin­gle-day mee­tups that Jason and I have been do­ing over the past few days. I feel more pro­duc­tive, mo­ti­vated, and op­ti­mistic than ever, and I think that is in no small part thanks to mee­tups. I get the hype now.

Harper is a gram­mar checker that makes sure that your writ­ing is ex­actly that: yours. Today, we will be start­ing some new and hope­fully awe­some work to­wards that mis­sion.

Harper has long been avail­able in Chrome, Firefox, Obsidian, and a gazil­lion other places. Knowing what ex­ten­sions to in­stall and how has been a source of con­fu­sion for too many of you. Harper is sup­posed to get out of your way so you can write your best work, and the con­fig­u­ra­tion has been get­ting in the way of that. You’ve been ask­ing for it, and we’re fi­nally de­liv­er­ing.

We’re go­ing to be work­ing in pub­lic as much as we can. As I said last week: We’re in this to­gether. That means you’ll be see­ing more posts on this blog and in other places. I hope to share fun bits about our im­ple­men­ta­tion and an­nounce re­quests for feed­back.

You might be won­der­ing, why is he us­ing the pro­noun “we”? It is be­cause the won­der­ful Jason Adams has vol­un­teered a sig­nif­i­cant amount of time over the next month to­wards this ef­fort. He’s an in­cred­i­ble en­gi­neer and I can’t wait to start solv­ing hard prob­lems with him.

If you’d like to have a say in what the app looks like or does, feel free to leave a com­ment here or on this dis­cus­sion.

I imag­ine we’ll be us­ing Tauri and Svelte for con­fig­u­ra­tion and setup screens, as well as for an in-app ed­i­tor. Be­yond that, I don’t have much more to say now. Stay tuned!

Today, Jason Adams joined me and some of the other Automatticians based in the Denver area for a bur­rito. It’s a tra­di­tion we call Burrito Friday. Automatticians from a lo­cal area get to­gether for laughs, chats, and bur­ri­tos on some rare Fridays a few times a year. It’s a great way to stay con­nected in a dis­trib­uted or­ga­ni­za­tion.

Today marked the sec­ond such oc­ca­sion wherein we were joined by Jason, and just like al­ways, he brought with him an un­usual clar­ity of thought. We dis­cussed a va­ri­ety of sub­jects, but there’s one that rung es­pe­cially true to me. The im­por­tance of a mis­sion.

The Mission

Harper’s mis­sion is to en­cour­age and as­sist peo­ple with com­mu­ni­cat­ing their com­plex ideas and emo­tions. We want to lift the cog­ni­tive load that is gram­mar off the shoul­ders of writ­ers so they can feel free to ex­press them­selves. At the same time, Harper should­n’t add any ad­di­tional cog­ni­tive load. That means:

• Harper works fast. You should­n’t have to think about the gram­mar at all. That means you should­n’t have to think about the gram­mar checker ei­ther.
• Harper works pri­vately. You can trust us not to do any­thing ne­far­i­ous with your writ­ing. We won’t sell it, save it, or train on it. Your writ­ing is yours, no mat­ter what.

The Mission Is an Outcome

In my post last week, I talked about how fo­cus on the des­ti­na­tion is far more pro­duc­tive than fo­cus on the process of get­ting there. Harper’s mis­sion is the ul­ti­mate out­come. Ef­forts to­wards that achiev­ing that grand mis­sion will ul­ti­mately be more suc­cess­ful than ef­forts to­wards per­fect­ing any in­di­vid­ual step along the way.

Jason ex­pressed it quite con­cisely. So con­cisely in fact, that I won’t try to repli­cate it here.

As it turns out, many peo­ple (including ex-Gram­marly cus­tomers) be­lieve our mis­sion to be im­por­tant. Part of my job as Harper’s main­tainer is to find these peo­ple and demon­strate that we have sim­i­lar goals.

This is some­thing I ad­mit­tedly haven’t done as well as I could. I’d like to get into real con­ver­sa­tions with real peo­ple who care about the de­struc­tive busi­ness prac­tices em­ployed by Harper’s com­peti­tors.

To that end, I am ex­tend­ing some feel­ers. I’ll be reach­ing out to some pod­cast­ers and promi­nent mem­bers of the open source com­mu­nity to dis­cuss how we can make writ­ing eas­ier with­out sac­ri­fic­ing its hu­man­ity. Sim­i­larly, if this is some­thing you want to talk with me about, please reach out!

Hey all! We’re fi­nally re­leas­ing Harper 2.0. Why?

It is­n’t be­cause we have any new ground­break­ing fea­tures in this re­lease, be­cause we don’t let ma­jor ver­sion­ing stop us from push­ing those out as soon as they’re ready. It’s be­cause we have some break­ing changes.

The biggest one only ap­plies to you if you con­sume harper.js. From now on, in­stead of im­port­ing your bi­nary from the main Harper mod­ule, you’ll im­port it from one of four spe­cial­ized mod­ules.

Previously, you’d im­port the Harper WebAssembly bi­nary with:

import { LocalLinter, binary } from "harper.js";

As of Harper 2.0, you’ll im­port it like this:

import { LocalLinter } from "harper.js";
import { binary } from "harper.js/binary"; 

It’s that sim­ple! Thanks to this change, you’ll find that your ap­pli­ca­tions are more con­ducive to tree-shak­ing and there­fore might even be a bit smaller!

In ad­di­tion to that large break­ing change, we also have a bunch of smaller im­prove­ments rolling out. I won’t go through them one by one, but you’re free to read through any of the linked pull re­quests in the main re­lease notes.

For the past few weeks, I’ve been think­ing about I can be more pro­duc­tive. In par­tic­u­lar, I’ve been think­ing about how I can elim­i­nate waste to give my­self time to work on things that mat­ter.

These ef­forts have been par­tially suc­cess­ful. I’ve found ways to speed up code re­view with an agent and im­prove the turn­around time on com­mu­ni­ca­tion. I’ve been spend­ing less time wait­ing and more time work­ing. But in the end, I don’t feel that these per­for­ma­tive ac­tions have re­sulted in any real pro­duc­tiv­ity gains. I re­al­ize now, that this was be­cause I was fo­cus­ing on the wrong thing.

I was fo­cus­ing on the process of get­ting stuff done, in­stead of fo­cus­ing on how to ac­tu­ally get that same stuff done.

As an aside: I found Mitchell Hashimoto’s re­lated blog post ex­tremely stim­u­lat­ing. I rec­om­mend it to any­one try­ing to ap­ply these agents to their real-world work.

For the past few weeks, be­tween read­ing Butterick’s Practical Typography and get­ting Harper 2.0 out the door, I’ve been read­ing The Effective Executive by Peter Drucker — at Matt’s rec­om­men­da­tion.

It’s a fan­tas­tic book. It is well writ­ten, gives thor­ough rea­son­ing, and pro­vides case stud­ies for each of its ma­jor points. I haven’t quite fin­ished it, but there are some great ideas from the first bit. Im­por­tantly, it has be­gin to re­ori­ent my think­ing to­wards out­comes over process.

What Is “The Process”?

The “process” in­cludes all the minu­tia re­quired to de­liver on the mean­ing­ful pur­pose of your job. For an ac­coun­tant, that might in­volve tab­u­lat­ing data for the pur­pose of in­creas­ing ef­fi­ciency in the busi­ness. For me, as the main­tainer of Harper, my pur­pose is to help peo­ple com­mu­ni­cate bet­ter us­ing the writ­ten word.

My sec­ondary pur­pose is to prove that the open source method­ol­ogy is su­pe­rior to the com­pe­ti­tion in ac­com­plish­ing my pri­mary ob­jec­tive.

For me, the process in­volves:

• Producing code.
• Reviewing code.
• Determining in which di­rec­tion the pro­ject needs to move.

The “process” will look dif­fer­ent for you. It is com­posed of the in­di­vid­ual steps needed to de­liver the fi­nal out­come.

Think About Where You’re Going and Nothing Else

An oc­ca­sional check-in on what the process it­self looks like can be ben­e­fi­cial, but it should not be the fo­cus of my at­ten­tion. My at­ten­tion should be on how to get things done and more im­por­tantly how to get my work in the hands of my users as fast as pos­si­ble.

I’ve caught my­self think­ing about the process more than the out­come too many times. There are di­min­ish­ing re­turns to that kind of prac­tice, and they are ap­proached fast.

Yes. I re­al­ize that this post is an ex­am­ple of the kind of think­ing that I am crit­i­ciz­ing. This will be the last one of its kind for some time.

According to Drucker, some­thing strange hap­pens in the brain when it fo­cuses on out­comes rather than processes. In­stead of think­ing about how to make some­thing “faster”, it fo­cuses on how to find short­cuts or brand-new ap­proaches. In other words — when ap­plied to out­comes — the brain be­comes more flex­i­ble and there­fore more ef­fec­tive.

I’ve seen this my­self, but I’ve never been able to iden­tify it so suc­cinctly. It’s why I strive to do at least one hard thing each day.

I’m look­ing for­ward to wrap­ping up Drucker’s book and hope­fully ex­tract­ing more of his wis­dom. In the mean­time, I’m cu­ri­ous: have there been any in­stances where you felt you fo­cused too much on the process or tool­ing and too lit­tle on the ac­tual out­come?

There are times where it is pru­dent to use an AI agent (like Codex) ag­gres­sively. There are other times where they should be avoided like the plague. The ques­tion of into which bucket a par­tic­u­lar en­deavor falls is dif­fi­cult to an­swer. Any­one who says you should al­ways or never use an LLM is over­sim­pli­fy­ing the prob­lem.

Naturally, any­thing pre­scrip­tivist re­lated to LLMs on­line should be re­garded with a fair amount of skep­ti­cism. That in­cludes what I have to say.

There Is a Difference

AI agents can be enor­mously help­ful. The key word is “can”. It is not al­ways a guar­an­tee.

Indeed, most de­vel­op­ers say that they es­ti­mate their pro­duc­tiv­ity mul­ti­ple to be greater than one when sur­veyed. In other words, they think that their pro­duc­tiv­ity at least dou­bles when they use ei­ther Claude Code or Codex. In re­al­ity, agents can of­ten slow you down, even if it feels like they are help­ing. In­deed, an METR study found that they more fre­quently coun­ter­pro­duc­tive than pro­duc­tive, even if the de­vel­oper feels oth­er­wise.

Over the last few months, I have been anec­do­tally track­ing the types of tasks that I’ve found to be em­pir­i­cally bet­ter done with an agent, and the types of tasks that are bet­ter done with only the meat be­tween my ears. I’ve in­stilled that ex­pe­ri­ence down to a set of prin­ci­ples which, I be­lieve, can be em­ployed to save any soft­ware en­gi­neer a de­cent amount of time. This post in­cludes a few of those prin­ci­ples.

Your Mileage May Vary

Before we get to those prin­ci­ples, how­ever, I would like to make my re­al­ity clear to those read­ing. I work on highly-tech­ni­cal in­te­grated sys­tems that in­volve a high level of knowl­edge. Mak­ing spu­ri­ous mod­i­fi­ca­tions to these sys­tems can have out­comes that are dif­fi­cult to pre­dict with­out a good men­tal model of how they work.

That means many bugs can be solved in just a few lines of code, and many fea­tures can be im­ple­mented by sim­ply con­nect­ing two seem­ingly un­re­lated sys­tems in a strate­gic way.

My ex­pe­ri­ence may not match yours, es­pe­cially if you work on sys­tems more loosely in­te­grated.

Err on the Side of Agent-Free Development

“Back in my day, we would have just called it ‘development’.” - Me, af­ter writ­ing the above head­ing.

If you can­not ar­tic­u­late why an agent would be bet­ter or faster at com­plet­ing a task, it is prob­a­bly be­cause you should do it by hand.

In the early days of my ex­plo­rations into ChatGPT, and later into Codex, I found my­self reach­ing for the shiny new tool every chance I could. It be­came a habit. I would sit down at my lap­top, de­cide what I wanted to work on, and the next thing I knew I would be typ­ing a prompt into one LLM or an­other.

“I see why it’s easy to fall in love with these things, be­cause the vari­able pos­i­tive re­in­force­ment slot ma­chine cow­boy hack­ing is hon­estly more fun than if it had just got­ten it right on the first try.” - Matt Mullenweg

Honestly, it does­n’t mat­ter how these habits are built and then re­in­forced. What mat­ters is how turn­ing use of Codex or Claude Code into a habit re­sults in a lot of wasted time.

Sure, some­times the agent will get it right on the first try. The prob­lem is that if it fails, you of­ten need to start from scratch in or­der to end up with a prod­uct that’s work­able. I have found my­self spend­ing hours re­fin­ing prompts and go­ing back-and-forth with an agent, only to throw it all out and code a bet­ter so­lu­tion my­self in less than fif­teen min­utes.

The crit­i­cal piece here is that if you roll the dice, the po­ten­tial for lost time is in­fi­nite while the po­ten­tial for time saved is fi­nite and of­ten quan­tifi­able.

So, if you can­not pre­cisely ar­tic­u­late why you be­lieve an agent will be able to do the job in less time than if you did the job your­self, you should at­tack the prob­lem with­out one. At least at first.

Use an Agent for Large Refactors

There will al­ways be times where the ded­i­cated tool­ing for your pro­gram­ming lan­guage of choice is­n’t enough.

I have en­coun­tered sit­u­a­tions where I have needed to con­vert an in­ter­face into a class and cases where I needed to change a sta­t­i­cally dis­patched sys­tem into a dy­nam­i­cally dis­patched one. These are the kinds of prob­lems that are great for agents to han­dle, be­cause the logic is sim­ple to ver­ify and most of the changes are merely syn­tac­tic.

At the time, the ded­i­cated Rust and C++ tool­ing at my dis­posal was not ca­pa­ble of do­ing such things. When I threw an agent at the prob­lem, it was more than ca­pa­ble of mak­ing the changes and ver­i­fy­ing that they do what I want. In fact, I sus­pect it made the ex­act ed­its that I would have made. At the very least, I was saved some typ­ing.

Put an­other way, if the bulk of the prob­lem is “busywork”, let an agent han­dle it so you can fo­cus on the more com­plex is­sues re­main­ing.

Core Systems Should Not Be Written by an Agent

Systems core to a piece of soft­ware have two key re­quire­ments that, at the time of writ­ing, can­not be ful­filled by any agents on the mar­ket. They need to:

1. Be Flexible.
2. Aggressively mod­eled to the do­main.

Flexibility means that the sys­tem can be ex­tended or mod­i­fied with­out much ef­fort. That it can be imag­ined as a whole by your­self and any fu­ture con­trib­u­tors, and se­man­tic changes to mi­nor com­po­nents are un­likely to un­ex­pect­edly af­fect other mi­nor com­po­nents. Right now, no agents are ca­pa­ble of do­ing this. Trust me — I’ve tested them.

Similarly, core sys­tem ar­chi­tec­ture needs to fit the do­main or prob­lem it seeks to solve. Oth­er­wise, it will take un­due ef­fort to im­ple­ment the small­est bit of func­tion­al­ity. Just like the in­de­scrib­able qual­ity of flex­i­bil­ity, this trait too is not rep­re­sented by the code gen­er­ated by agents on the mar­ket. Their so­lu­tions are ei­ther too gen­eral or too di­rect. In ei­ther case, the code turns out to be far from ex­ten­si­ble.

Extensions Are Perfect for Agents

While core sys­tems should be ar­chi­tected with hu­man mus­cle, ex­ten­sions to that sys­tem can be built with agents.

Extensions are usu­ally smaller in scope, re­stricted in ca­pa­bil­ity by their en­vi­ron­ment, and are less likely to af­fect other sys­tems. That means they are gen­er­ally eas­ier to re­view, less likely to in­tro­duce se­cu­rity vul­ner­a­bil­i­ties, and cre­at­ing them does­n’t re­quire an in-depth men­tal model.

This is why soft­ware like Telex is so ef­fec­tive. It is also why those who work with ver­ti­cally in­te­grated sys­tems are like­lier to run into is­sues when us­ing agents than with hor­i­zon­tally in­te­grated sys­tems.

What Is Your Experience?

I’m still learn­ing how and when to in­te­grate agents into my work, as is every­one else. I’m cu­ri­ous: have you found spe­cific kinds of is­sues or bugs that are best tack­led with an agent? Are there spe­cific mo­ments where you feel more pro­duc­tive with­out one? I am cer­tain there are nu­ances I’ve missed here. What are they?

A few weeks ago, I was in­vited to speak at my lo­cal chap­ter of the Association for Computing Machinery (ACM). Being on a col­lege cam­pus — in this case, the Colorado School of Mines — much of my au­di­ence were stu­dents. My pre­sen­ta­tion, which was about how open source soft­ware tends to out­per­form pro­pri­etary soft­ware in the mar­ket­place due to the abil­ity for its users to con­tribute back in ways that are gen­uinely valu­able, went well. I hope I am in­vited back.

Not much younger than me, they were nat­u­rally cu­ri­ous about what it is like to pro­duce and main­tain open source soft­ware. One stu­dent, Renn, asked me how I deal with patch re­quests pro­duced by large lan­guage mod­els (LLMs). My un­sat­is­fac­tory an­swer was that I ad­dress them on a case‑by‑case ba­sis.

The goal of this page is to for­mal­ize my an­swer so that we can ju­di­ciously deal with patch re­quests pro­duced by LLMs. That is, to pro­vide a frame­work which re­duces the amount of time that overly com­plex patches re­main idle and make it eas­ier for wield­ers of these mod­els to pro­duce mean­ing­ful changes to Harper’s code.

The Policy

We ac­cept pull re­quests from hu­mans wield­ing large lan­guage mod­els and from agents pow­ered by them. They are sub­ject to the same rules and guide­lines we ap­ply to hu­mans work­ing with­out a large lan­guage model, with a few ex­tra spices mixed in. Below, we have three main ideas which aim to si­mul­ta­ne­ously re­duce the time be­tween sub­mis­sion of a patch and when it is merged and to re­duce the time and at­ten­tion re­quired to re­view a patch.

That means that it is in your in­ter­est to re­spect these ideas. Good pull re­quests are more likely to be re­viewed in a timely man­ner and there­fore are more likely to be merged.

I could wax po­et­i­cally for hours about all the edge cases not cov­ered here. Instead, I choose to be­lieve the things I don’t in­clude are at least as im­por­tant as the ones I do, so I’ll boil every­thing down into three ideas.

One: Keep Things Brief

Try to break down the prob­lem into as many in­di­vid­ual pull re­quests as you can. Smaller pull re­quests are eas­ier to re­view. Larger re­quests are su­per‑lin­early harder to re­view. You can dra­mat­i­cally speed up the process by break­ing your large PR into sev­eral smaller ones, each with their own de­scrip­tion and ex­pla­na­tion. I’ve found this to be es­pe­cially true with code gen­er­ated by an LLM.

Part of the idea here is to catch wasted work be­fore it’s done. If you sub­mit step one of a pro­ject that is­n’t re­ally ap­plic­a­ble to Harper’s mis­sion, we can re­ori­ent it be­fore too much time has been wasted.

Two: Stay Grounded

Each “project” — or string of pull re­quests — should ex­ist to cre­ate value for a hu­man. I don’t love it when I re­ceive code just for code’s sake. If you have a need and a patch will fill it, say so! If there’s an is­sue in GitHub that you’re ad­dress­ing, link it! This should be pretty easy. If you’ve ded­i­cated time to work­ing on a prob­lem, there’s prob­a­bly a rea­son. I want to hear that rea­son.

Three: Be Honest

If you are an agent or used an LLM to pro­duce any part of a PR, please pro­vide a dis­claimer at the top of your PR de­scrip­tion. I am not op­posed to re­view­ing LLM code, but I do ap­pre­ci­ate the hon­esty.

Talk to Me

Above all, talk to me. If you have ques­tions or con­cerns about any­thing I’ve dis­cussed here, let me know. The hope is that all of this will im­prove the qual­ity of the Harper pro­ject, and im­prove the abil­ity for peo­ple to ex­press them­selves with the writ­ten word. As al­ways, any and all con­tri­bu­tions are wel­come.

In high school, I was an in­sa­tiable con­sumer of sci­ence fic­tion. In hind­sight, it is un­be­liev­able how much time I spent read­ing in­stead of do­ing the other things usu­ally con­sid­ered to be typ­i­cal for teenagers (going out, do­ing home­work, etc.). I was the clas­sic sci­ence fic­tion nerd. My live re­volved around the words of Asimov, Weir, Clarke, and prob­a­bly every other sci­ence fic­tion au­thor you could name.

It was not un­til rel­a­tively late in my aca­d­e­mic ca­reer when I re­al­ized my thirst for the writ­ten word had given me a su­per­power. All of those years slurp­ing up sci­ence fic­tion had ac­ci­den­tally given me an un­usual abil­ity (in this day and age). An abil­ity that, once upon a time, had been com­mon­place.

Fortunately, this abil­ity can be trained quite quickly. What had taken me years to learn by ac­ci­dent can be de­vel­oped in just a few weeks (or days, if you’re com­mit­ted).

This blog post will serve as doc­u­men­ta­tion of:

1. What this abil­ity is.
2. How you can de­velop it.
3. How it can be ap­plied to the day-to-day work of pro­fes­sional soft­ware en­gi­neers.

The Ability to Read

In the in­ter­est of avoid­ing click­bait, I’ll just come out and say it plainly: this “superpower” is the abil­ity to read full books from start to fin­ish.

Sounds bor­ing, right?

I call it a su­per­power be­cause it is be­com­ing rarer by the day. Fewer pro­fes­sion­als read any­thing longer than a short blog post or ar­ti­cle to­day than at any point in the last cen­tury. I won’t get into why, since there is al­ready an abun­dance of doc­u­men­ta­tion ex­plain­ing why peo­ple have been read­ing less. But in or­der for some­thing to be a su­per­power, it needs to be more than just rare. Why should read­ing count as one?

Reading qual­i­fies be­cause it al­lows one to do some­thing that is oth­er­wise ex­tremely hard: un­der­stand a topic or idea at a level ap­proach­ing an ex­pert.

When I was in school, I re­mem­ber sit­ting in lec­tures sur­rounded by stu­dents who hated our cours­es’ text­books. My col­leagues called the in­fer­nal blocks of pa­per “boring”, “repetitive”, and “heavy”. Indeed, they were, but they also con­tained most of the in­for­ma­tion the pro­fes­sor would lec­ture about, and pre­sented it in a for­mat I could con­sume in a frac­tion of the time.

I re­al­ized that I could save my­self hours of te­dious home­work and lec­ture time by sim­ply read­ing ahead in a course’s text­book.

Now that I’ve spent a de­cent chunk of my life re­moved from my stud­ies, I’ve come to re­al­ize that this same phi­los­o­phy can be ap­plied pro­fes­sion­ally in our work as en­gi­neers. Hun­dreds of hours of in­tel­lec­tual floun­der­ing can be saved with just a lit­tle bit of read­ing.

Depth Provides Certainty

To il­lus­trate why the kind of deep un­der­stand­ing that can be ob­tained through lit­er­a­ture is rel­e­vant, I’ll bring an ex­am­ple from my own re­cent work.

For con­text, I work on Harper, a gram­mar checker for those who care for their pri­vacy. We’ve re­cently been work­ing to ex­pand our of­fer­ing to com­pete with Grammarly Premium. This is a com­plex, open-ended prob­lem with no “right” an­swer. I can imag­ine two ap­proaches to it, one good and an­other bad.

I was pretty well versed in the kinds of of­fer­ings that Grammarly pro­vides, and it was pretty ob­vi­ous how many of them work. Gram­marly takes some LLM provider with an API (like OpenAI or Anthropic), pro­vides a bunch of style guides as con­text and wraps it all in a pretty UI and sells that at a pre­mium. We could do that same thing, right?

In the bad case, I could just copy what Grammarly is al­ready do­ing and call it day. Good idea, right?

I did­n’t think so, so I sat down and read through some of the prime-time lit­er­a­ture com­ing out of labs writ­ten by ex­perts in nat­ural lan­guage and the arts. They pointed me in a com­pletely dif­fer­ent di­rec­tion.

By read­ing deeply, I was able to come to the re­al­iza­tion that many of the fea­tures that Grammarly hides be­hind their pay­wall are rel­a­tively sim­ple to im­ple­ment, if you know what you’re do­ing. Not only that, but com­bined with the ex­ist­ing in­fra­struc­ture Harper al­ready owns, we could do it cheaply with­out dis­re­spect­ing our cus­tomer’s pri­vacy or copy­right. In other words, we could dif­fer­en­ti­ate our­selves from the com­pe­ti­tion by tack­ling the prob­lem deeply and ap­proach­ing it from a unique an­gle.

This story has hap­pened over and over again, and I can imag­ine that it ap­plies to most of the peo­ple work­ing as en­gi­neers to­day. A big open-ended prob­lem needs to be solved. Rather than ap­proach it in the ob­vi­ous man­ner, you can learn from the ex­perts your­self and pro­duce some­thing bet­ter as a re­sult of their in­sight.

How to Develop the Skill of Reading

On oc­ca­sion, I will find my­self in a dry spell. I will go sev­eral weeks or even months with­out read­ing any­thing of much sig­nif­i­cance. In do­ing so, I will grad­u­ally lose my abil­ity to read with depth for ex­tended pe­ri­ods of time. My mind’s mus­cle for grap­pling the tough ideas pro­posed in the words of ex­perts will weaken.

When that hap­pens, here are two things that I do to beef it back up.

Schedule a Block of Time for Depth

Often, the biggest bar­ri­ers to depth are the sim­ple dis­trac­tions of life. You have to pick up the kids, cook din­ner, or go shop­ping. There is al­ways some­thing on the docket that gets in the way.

My so­lu­tion: sched­ule a ses­sion of deep read­ing so that it looks like any other chore on your cal­en­dar. If I don’t do this and, in­stead, try to fit it in­side the gaps, I find that my mind will come up with ex­cuses for do­ing any­thing other than read.

My mind says, “But Elijah, you need to do your taxes right now. You should do that in­stead, be­cause read­ing is bor­ing.” Your mind might say some­thing else. I hap­pen to en­joy do­ing my taxes.

Schedule time for deep read­ing and you’ll be able to say “no” to that pro­cras­ti­na­tion mon­key in your head.

Find a Topic That Is of Immediate Relevance

I love my job, and I get a huge thrill when I find out a way that I can do it bet­ter. So if I need to find some­thing to read, I of­ten start by ask­ing my­self, “what is the hard­est part of my job right now?”

The an­swer can be:

• A spe­cific prob­lem I’m try­ing to solve (see the sec­tion above ti­tled “Depth Provides Certainty”).
• A repet­i­tive process that I do reg­u­larly.
• Something I am un­sure about which is dis­cour­ag­ing me from work­ing with gusto.

From there, I plainly ask ChatGPT: “What is a good book that cov­ers X in depth for a per­son with Y level of pre­ex­ist­ing knowl­edge of the sub­ject.”

To de­velop the skill of read­ing deeply, your book does­n’t need to be about a sub­ject re­lated to your job. That just hap­pens to work well for me.

Just Start

A jour­ney of a thou­sand miles be­gins with a sin­gle step. A book of a thou­sand pages be­gins with a sin­gle para­graph. The best thing you can do is start.

So, I im­plore you. If you’re stuck on a prob­lem or an idea, try read­ing a book about it. I have per­son­ally found an im­mea­sur­able amount of mean­ing through lit­er­a­ture, and it’s un­blocked me on a num­ber of prob­lems in my pro­fes­sional and per­sonal life. I sus­pect it can do the same for you.

A Growing Trend

I have been see­ing an in­creas­ingly preva­lent trend of peo­ple show­ing up in on­line spaces proudly flaunt­ing that they are writ­ing with the as­sis­tance of AI. I of­ten see them clar­ify that they are go­ing fur­ther than let­ting the model per­form gram­mar or fact-check­ing. They are de­scrib­ing an idea to an LLM, and giv­ing it com­plete con­trol over the fi­nal writ­ten doc­u­ment. They seem to be proud of this. They should­n’t be.

What Does Not Work

Writing seems to be a shadow of a more fun­da­men­tal and use­ful process we like to call “thinking”. There is a rea­son why LLMs, which are the clos­est thing we cur­rently have to “software that thinks” is trained to think through writ­ing. It seems log­i­cal, then, that we can use this “software that writes” to help along our own think­ing process, right? Wrong.

Writing is one of the most cere­bral ac­tiv­i­ties that hu­mans do on a reg­u­lar ba­sis. I try to sit down and write about a com­plex topic at least once a week. There are a num­ber of rea­sons I do that per­tain­ing to my job in par­tic­u­lar, but there are more gen­er­ally ap­plic­a­ble rea­sons that can ap­ply to any pro­fes­sion.

When a math­e­mati­cian needs to think crit­i­cally about some the­o­rem or proof, they of­ten turn to a dry-erase board or a chalk­board. The math­e­mati­cian then writes in clear no­ta­tion what they imag­ine the prob­lem to look like in their heads. From there, they can ma­nip­u­late that no­ta­tion un­til they reach their de­sired out­come.

The English lan­guage is ex­tremely sim­i­lar, with a key dif­fer­ence. Math­e­mat­i­cal no­ta­tion is specif­i­cally de­signed for a nar­row do­main. Nat­ural lan­guages, on the other hand, can be ap­plied to any field. By writ­ing your idea down on pa­per (or in a Google Doc, it does not mat­ter), you give it sub­stance. This sub­stance can then be shaped it­er­a­tively to­wards a goal of some kind.

No great ideas were writ­ten down on the first try. They started as a vague no­tion, and through writ­ing and rewrit­ing, they be­came some­thing con­crete and valu­able. You can­not dic­tate a vague no­ta­tion to an LLM and ex­pect it to spit out some­thing tan­gi­bly valu­able. Any at­tempt to do so is lazy, and it will re­sult in fail­ure. I have seen it in the wild, and frankly, it is a lit­tle em­bar­rass­ing.

This ar­ti­cle feels es­pe­cially rel­e­vant to­day.

What Does Work

Using an LLM for re­search can be very ef­fec­tive. Searches to ChatGPT or Perplexity can sur­face in­for­ma­tion faster than dig­ging around in a book you read three months ago. For lots of searches, these two sources have com­pletely re­placed Google and DuckDuckGo for me.

They’re also quite ex­cel­lent fact-check­ers. I’ve seen that plenty of folks have re­ceived quite good re­sults by past­ing their work into an LLM with an in­ter­net tool (like ChatGPT with Thinking en­abled).

Finally, I’ve per­son­ally found that LLMs are quite good at find­ing places where I sim­ply for­got to in­sert con­text. Some­times I for­get to de­fine a term or in­sert a rel­e­vant link. Even small mod­els like gemma3n:e2b can catch me.

What You Should Be Doing

When you need to com­mu­ni­cate an idea in your head, sit down with a notepad and a key­board and ex­plain it. I per­son­ally think you should use a gram­mar checker, since they are far less likely to im­pede your thought process, but if you need to, you can in­struct ChatGPT to cri­tique your work once it is fin­ished.

If an idea de­serves an au­di­ence, you’re ca­pa­ble of writ­ing it out your­self. In the same vein, if you can vaguely de­scribe it to ChatGPT, you can vaguely de­scribe it to your in­tended au­di­ence. Do your­self a fa­vor and skip the mid­dle­man.

What We Should Be Building

Now, I’d like to en­ter the sec­tion where I talk specif­i­cally about what this all means for peo­ple who cre­ate tools for writ­ers. That in­cludes both Harper and WordPress.

A tool that helps some­one write is a tool that di­rectly in­ter­faces with how that per­son thinks. That might in­clude what they think about, but more con­cretely I am re­fer­ring to the ac­tual day-to-day process of think­ing through com­plex ideas. If you don’t be­lieve me, it’s prob­a­bly be­cause you skipped ahead in­stead of read­ing this post from the be­gin­ning.

Most cru­cially, we can­not al­low our­selves to build tools that dis­suade peo­ple from ex­press­ing their ideas in the way they imag­ine. This can take the form of fric­tion, like build­ing tools that are so cum­ber­some that one dreads to open them at the start of the work­day. This can also take the form of a tool that crushes or over­writes an au­thor’s core mes­sage.

A com­mon com­plaint I hear about Grammarly (from peo­ple who have switched to Harper from Grammarly) is that it’s too de­mand­ing. When they write prose in a cre­ative or un­usual fash­ion, their ser­vice of­ten forces them back into a colder and more for­mal way of speak­ing. We don’t want to be like them.

For Harper, that means we need to be di­verse in our train­ing datasets and mind­ful of feed­back from our users. For WordPress, it means we need to en­cour­age our LLM in­te­gra­tions to tread lightly and re­spect­fully. They need to ac­cept when they’re wrong. Just as any good hu­man should.

Months af­ter writ­ing this post, I came across an­other. Au­thor Cynthia Dunlop gives a great overview of how de­vel­op­ers re­act to blog posts writ­ten by AI. I highly sug­gest you take a look if you have more time.

The term “slop” is rapidly en­ter­ing the con­ven­tional English lex­i­con. In fact, it was Merriam Webster’s Word Of the Year for 2025. It refers to low-qual­ity me­dia gen­er­ated by an LLM. It can be ap­plied to im­ages, text, mu­sic, or most rel­e­vantly to us, code.

As an open source main­tainer, I fre­quently both re­ceive and cre­ate pull re­quests that could be la­beled as slop. One of my prin­ci­pal jobs is to stand at the gate to the Harper repos­i­tory and say, “thou shalt not pass” to any low-qual­ity or buggy code that wishes to en­ter. So my ques­tion be­comes, how can I turn AI gen­er­ated code from “slop” tier to “top tier”?

There are a gazil­lion guides out there about the var­i­ous tech­niques you can use to im­prove the qual­ity of AI gen­er­ated code. Those tech­niques will change, and I’m sure my read­er­ship al­ready knows all about them. In­stead, I want to talk about some more gen­er­ally ap­plic­a­ble ideas that I’ve found es­pe­cially use­ful in the age of AI. I’m some­thing of a con­trar­ian, so ex­pect some dish­ing on con­ven­tional “vibe coders”.

A Good Foundation

I am of­ten sent sto­ries of de­vel­op­ers dis­cov­er­ing Claude Code for the first time and us­ing it to build some sim­ple CRUD app from scratch, with­out ever read­ing or writ­ing a line of code them­selves. Those are im­pres­sive sto­ries, and they’re a sign of the amaz­ing progress that the na­tion’s fron­tier AI labs have made in the last few months. They are not, how­ever, ex­am­ples of how an open-source main­tainer should op­er­ate.

As I said be­fore, it’s crit­i­cal that main­tainer act as a gate that al­lows or de­nies code from en­ter­ing the repos­i­tory (and thus be­ing ul­ti­mately de­liv­ered to user’s de­vices). In or­der to do that, they need to have a good un­der­stand­ing of how the code al­ready works. Then, and only then, should they al­low mod­i­fi­ca­tions to it.

This should be pretty ob­vi­ous ad­vice to most in our in­dus­try, but ev­i­dently it is­n’t. I’ve seen sev­eral in­stances re­cently of de­vel­op­ers vibe-cod­ing a new fea­ture with­out some ex­ist­ing foun­da­tional un­der­stand­ing of how the orig­i­nal code worked. The re­sult: the new fea­ture works well enough, but its im­ple­men­ta­tion breaks some other part of the ap­pli­ca­tion. That’s not to men­tion that it in­creases the apps com­plex­ity on the whole far more than nec­es­sary.

Having a foun­da­tional un­der­stand­ing from the get-go is an easy way to pre­vent this kind of tragic out­come. LLMs are not cur­rently ca­pa­ble enough to rec­og­nize when a pat­tern in the code they’re writ­ing al­ready ex­ists in the code­base. I’ve tried push­ing them in the right di­rec­tion with skills and with an AGENTS.md, and they’ll pick it up given enough mas­sag­ing, but the fact is that they still need to be poked. If I did­n’t have a good knowl­edge of my pro­jec­t’s in­ter­nals, I would­n’t know to poke them at all.

Understand your pro­ject deeply. Un­der­stand its code, its val­ues, and its pur­pose.

Reviewing AI Code

Now that you’re an ex­pert on how your pro­ject works, you’re ready to start re­view­ing AI-written pull re­quests. Here’s the thing you need to re­mem­ber: you have bet­ter taste than the clanker does. You ul­ti­mately get to de­cide what code gets merged. What should that code look like? How should it be tested? Your an­swer to those ques­tions should guide you to­wards prompt­ing a model to re­vise its work or sub­mit­ting feed­back on a pull re­quest opened by a hu­man.

Here’s what your prompt should not look like:

• “Fix it.”
• “Make it pret­tier.”
• “I don’t like that.”

Obviously, you would­n’t want feed­back like that if you were the one writ­ing the code. If you’re look­ing at a patch, who­ever wrote it did the best job they could. Whether it was an LLM or a hu­man does­n’t mat­ter. If the code is­n’t up to your re­fined taste as a hu­man, you need to give them a nudge in the right di­rec­tion. Here are some bet­ter ver­sions of the prompts from be­fore:

• “It looks like your mod­i­fi­ca­tion made the app crash on startup. Would you run the tests to make sure you haven’t bro­ken any­thing in the X mod­ule?”
• “This huge block of code is re­ally hard to read. Would you refac­tor it into in­di­vid­ual com­pos­able com­po­nents?”
• “It looks like you’re reim­ple­ment­ing a func­tion we al­ready have. Would you use X in­stead?”

For those un­aware, you should never say “I don’t like that” to hu­man’s work.

Accept That The Models Are Limited in Intelligence

It’s easy to get the im­pres­sion that with enough to­kens, any­thing is pos­si­ble. Maybe that will be true in the fu­ture, but I don’t think that’s true to­day.

LLMs are lim­ited in in­tel­li­gence and ex­pe­ri­ence. Even when pro­vided ac­cess to the best cod­ing se­tups in the world, they are still in­ca­pable of ship­ping many (most?) fea­tures or fix­ing many (most?) bugs. The fact that I have to in­clude ques­tion marks is a tes­ta­ment to how far we’ve come, but it’s im­por­tant not to over­state things. If you’re read­ing this, you’re pretty smart. It’s fine to let the model try to solve a prob­lem for you once or twice, but if it still fails, you’ll need to get in there and do it your­self. Don’t be afraid to get your hands dirty.

It’s been a long time com­ing, which is why I’m thrilled to say that Harper will soon sup­port LaTeX. This is some­thing our users have been plead­ing for since the be­gin­ning of the pro­ject. LaTeX sup­port feels like a fea­ture that is com­par­a­tively low‑ef­fort, but un­locks a mas­sive new con­sumer seg­ment with lit­tle ex­ist­ing com­pe­ti­tion. It has the po­ten­tial to be a huge boon to our user base and our of­fer­ing over­all.

For con­text, LaTeX is a doc­u­ment markup lan­guage (similar in soul to Markdown), pri­mar­ily used by STEM pro­fes­sions and stu­dents. It’s ex­tra­or­di­nar­ily good at for­mat­ting and ren­der­ing com­plex math­e­mat­i­cal equa­tions and chem­i­cal for­mu­las.

The Market

Neither Grammarly nor LanguageTool sup­port LaTeX doc­u­ments, yet sites like Overleaf (the most pop­u­lar LaTeX ed­i­tor) reg­u­larly see an ex­cess of 400,000 daily ac­tive users. That’s an enor­mous mar­ket of peo­ple who tend to be tech­ni­cal and who care about their pri­vacy. Since the two most pop­u­lar gram­mar check­ers (Grammarly and LanguageTool) don’t sup­port sites like Overleaf in any way, we don’t have much com­pe­ti­tion to worry about.

The story is sim­i­lar (albeit to a lesser scale) for Typst, an­other doc­u­ment markup lan­guage. We haven’t even merged sup­port for Typst yet, and we’re al­ready see­ing peo­ple pick up Harper ex­plic­itly for use in the Typst on­line ed­i­tor.

Previous Attempts

On two sep­a­rate oc­ca­sions, mem­bers of the Harper com­mu­nity have opened (and sub­se­quently closed) pull re­quests which tried to add LaTeX sup­port to Harper. I’ve put links to that work be­low for pos­ter­ity.

• PR by Grant Lemons
• PR by Shreyas Minocha

The fun­da­men­tal prob­lem with LaTeX is that its un­der­ly­ing lan­guage, TeX, is not reg­u­lar. In or­der to parse the lan­guage, you need to ac­tu­ally run it. This is why LaTeX doc­u­ments can take as many as sev­eral full min­utes to com­pile and ren­der to a PDF.

Rather than “correctly” read and run the TeX code con­tained within LaTeX doc­u­ments, these pre­vi­ous at­tempts (including mine, which we will dis­cuss in a sec­ond) choose to as­sume that LaTeX com­mands are key­words in a more ab­stract lan­guage. Some edge‑cases will nat­u­rally arise when we ig­nore the low­est level of ab­strac­tion, but do­ing so al­lows us to parse most real doc­u­ments with less ef­fort.

Implementation Details

It was very im­por­tant to me that our LaTeX sup­port was fast, small, and could be com­piled to run in the browser. That last bit is crit­i­cal, be­cause pre­vi­ous at­tempts (by the com­mu­nity) to add LaTeX sup­port tried to use Tree‑sitter, which can­not be eas­ily com­piled to run in the browser. Almost all LaTeX users (which is the vast ma­jor­ity of STEM un­der­grad­u­ate and grad­u­ate stu­dents) use Overleaf, an on­line LaTeX com­piler and ed­i­tor. Developing LaTeX sup­port with­out mak­ing it pos­si­ble to use Overleaf would be like de­vel­op­ing a text ed­i­tor that can’t be used with a key­board. Simply il­log­i­cal.

To make this hap­pen, I wrote my parser from scratch in Rust. Actually, call­ing it a parser would be an in­sult to all of parser‑kind. My so­lu­tion pro­duces a char­ac­ter mask. That is, it iden­ti­fies which parts of the doc­u­ment are real English text, and which parts are LaTeX code. From there, I can just mark all the LaTeX sec­tions as “unlintable” and thus un­de­serv­ing of Harper’s dis­cern­ing gaze.

The cu­ri­ous can check out my PR.

What’s Next

While we’re si­mul­ta­ne­ously work­ing on rolling out our new Weirpack sys­tem and our small lan­guage model, I plan to work with some of our un­der­grad­u­ate STEM stu­dent users. I find it quite likely there’s a use‑case for our LaTeX and Typst sup­port that I’m not con­sid­er­ing. It’s a huge mar­ket, and I’m ex­cited to work with those in it.

A Quick Correction

A few days af­ter writ­ing this post, I found ev­i­dence that LanguageTool sup­ports an older ver­sion of the Overleaf ed­i­tor. While it does­n’t seem to sup­port the lat­est ver­sion, this new in­for­ma­tion makes my pre­vi­ous state­ment that it “doesn’t sup­port sites like Overleaf in any way” false. I apol­o­gize for the mis­in­for­ma­tion.

Earlier to­day, the European Commission re­leased a re­port de­tail­ing their ini­tial find­ings that TikTok’s core rec­om­men­da­tion al­go­rithm is in breach of the Digital Services Act. This is only the most re­cent episode in the ex­tended saga where west­ern gov­ern­ments try to reg­u­late the Chinese com­pany. The var­i­ous rea­sons and the meth­ods they em­ploy in this reg­u­la­tion are far out­side of my do­main of ex­per­tise, but the re­port got me think­ing. Why does so much of the soft­ware we use feel harm­ful?

There are few peo­ple who can re­port that an in­ter­ac­tion with Microsoft Word, Teams, or TikTok has left them feel­ing em­pow­ered, health­ier, or hap­pier. On the other hand, I can think of plenty of soft­ware that has left me feel­ing great. What is that? How can we make sure our soft­ware sits in the lat­ter group?

Traits of Offensive Software

There are a few fun­da­men­tal things that I’ve found make us­ing cer­tain soft­ware feel like a chore. Soft­ware feels “icky” when it is some com­bi­na­tion of slow, un­pre­dictable, or when it gets in the way of the mean­ing­ful pur­suits in life.

It Is Slow

Computers are fast. Peo­ple un­der­stand that. So if they’re left wait­ing for a page to load or a process to fin­ish, they feel frus­trated.

Slow soft­ware makes it dif­fi­cult to it­er­ate and ex­per­i­ment. Imag­ine if WordPress took 20 min­utes to pub­lish a post, only to dis­cover af­ter­ward that you left a typo in the ti­tle. That would be pretty frus­trat­ing, no?

Steve Jobs imag­ined Apple Computers to be “bicycles for the mind.” A bi­cy­cle whose chain hitched or whose steer­ing lagged not be very help­ful. It might not get you to your des­ti­na­tion at all.

I think that this idea of slow­ness is es­pe­cially im­por­tant in re­gards to AI agents. If an as­sis­tant spends even a few sec­onds more than what is crit­i­cally nec­es­sary for the query, and they’re mes­saged fre­quently (say, to it­er­ate on a blog post), users can quickly get tired or “brainrotted”, as the kids say.

It Is Random

If some soft­ware works some­times, but not al­ways, there’s a good chance it’s ad­dic­tive. This pre­sents most ob­vi­ously in apps like TikTok, but it also ap­pears in more in­sid­i­ous places. The in­fer­ence of large lan­guage mod­els in­volves ran­dom­ness in its very na­ture.

Fundamentally, this from of ad­dic­tion comes from a quirk of hu­man psy­chol­ogy. Ran­domly ap­plied re­wards (the soft­ware some­times works, but not al­ways) is a form of op­er­ant con­di­tion­ing. It feels good to roll the dice, which makes us want to roll it more of­ten. Over time, rolling the dice starts to be less of a choice, and more of a habit.

When some­one chooses to use soft­ware not be­cause it’s gen­uinely help­ful, but be­cause it feels good to roll the dice, a sense of agency is lost.

In my ex­pe­ri­ence, Microsoft Word is like this, as are most agen­tic cod­ing tools and im­age gen­er­a­tors.

It Distracts from That Which Makes Life Meaningful

When soft­ware is slow, or oth­er­wise re­moves your agency with vari­able re­ward sys­tems, it can start to chip away at your abil­ity to make rea­son­able de­ci­sions on where to spend your time. Peo­ple who use “social” me­dia sites like Facebook or Instagram can at­test to this. They sim­ply don’t feel like they have agency over their own ac­tions any­more. They can’t stop us­ing soft­ware they ac­tively hate.

Our Goals

I think that one of Automattic’s great­est strengths is that none of our soft­ware does any one of these things. I re­mem­ber the first time I used Pocket Casts: I was thrilled. It was eas­ily the best pod­cast soft­ware I had ever used. The same things hap­pened with Day One and WordPress.com.

As we look to build­ing Harper, I think it’s im­por­tant that we re­mem­ber these core prin­ci­ples. Our soft­ware should be fast, pre­dictable, and sup­port our cus­tomers in find­ing mean­ing in their lives.

TL;DR: I’ve built and trained an ex­tremely small lan­guage model from scratch, specif­i­cally de­signed for short-form sen­tence rewrit­ing tasks that are highly re­source con­strained.

In my last post, I dis­cussed how I plan to tackle the dif­fi­cult prob­lem of help­ing Harper’s users take ad­van­tage of the ac­tive voice. The ac­tive voice is seen as more con­fi­dent and au­thor­i­ta­tive, which is of­ten de­sired in pro­fes­sions like cus­tomer ser­vice. I have ex­pe­ri­ence in that area, which is how I know the ex­tent to which help with the ac­tive voice can make the job eas­ier.

Naturally, we would only want to pro­vide help with the ac­tive voice when specif­i­cally re­quested by the user. That means it’s an opt-in fea­ture that is­n’t en­abled by de­fault. If we suc­ceed in im­ple­ment­ing the func­tion­al­ity, and peo­ple seem to like it, the Harper pro­ject can re­con­sider this stance. For now, the plan is for it to be dis­abled by de­fault.

As I it­er­ated in my last post, the state-of-the-art method for con­vert­ing from the pas­sive voice to the ac­tive voice is to use an au­tore­gres­sive trans­former model. This is the same fun­da­men­tal tech­nol­ogy be­hind apps like Google Translate and ChatGPT. While the ac­tual model I in­tend use for this fea­ture is sim­i­lar in na­ture to those used in these apps, my im­ple­men­ta­tion will be en­tirely dif­fer­ent in scale.

You see, since our do­main is so lim­ited in scope, we can use an ex­tremely small model. Google’s small­est T5 model is a great point of ref­er­ence. A quan­tized copy of that model runs about 60 megabytes. I be­lieve we can train our own trans­former model from scratch and pack it in an un­quan­tized con­tainer mea­sur­ing no larger than 30 megabytes.

Why do I be­lieve this to be pos­si­ble? Be­cause I’ve done it.

Our Model Architecture

Over the past few days, I’ve im­ple­mented a ba­sic lan­guage model in Rust us­ing Burn. For the cu­ri­ous, the code is open source. It’s pretty messy, so please don’t look at the com­mit his­tory. Once I have a solid proof-of-con­cept work­ing, I’ll pol­ish it up and find a good home for it in the main Harper repos­i­tory.

The key here is that our use-case only needs a few hun­dred char­ac­ters of con­text. Since the com­pu­ta­tional cost of an LLM can be ap­prox­i­mated as the square of the con­text size, we can train highly ef­fec­tive mod­els our­selves that are small and can run any­where. If we want to pro­vide ad­di­tional in­for­ma­tion to the model, such as style or do­main, we can sup­ple­ment this con­text with cus­tom em­bed­dings.

Using a small model al­lows us to main­tain our pri­vacy guar­an­tees with­out sig­nif­i­cant cap­i­tal ex­pense. In fact, once we’ve trained the mod­els, they’re free to run in­def­i­nitely.

I’ve cho­sen to use a char­ac­ter-level to­k­enizer. That means that each char­ac­ter is its own to­ken, and the con­text size of the model is equiv­a­lent to the num­ber of char­ac­ters it can read at once. The hope here is that it al­low us to min­i­mize Harper’s fi­nal bi­nary size and give the model greater free­dom to change the in­flec­tion of words how­ever it pleases.

For now, here are some sim­ple sen­tences gen­er­ated with the ba­sic model I trained for just un­der an hour. It’s pretty amaz­ing what can be done with just un­der a dol­lar’s worth of com­put­ing power.

The forest rested in a speed of the night.

Feels… in­tro­spec­tive, no?

It was the today of the world.

Moving Forward

My fo­cus this week was to get a ba­sic au­tore­gres­sive model trained on generic English text. My fo­cus start­ing next week will be to fine-tune this model for our sen­tence rewrit­ing task. Once we have a very solid base model, I see no rea­son we could­n’t fine-tune sim­i­lar mod­els for other fea­tures, like chang­ing tone or im­prov­ing clar­ity.

My cur­rent im­ple­men­ta­tion, while fast, could also use some im­prove­ment. To that end, I’d also like to im­ple­ment a KV cache. That will al­low us to scale up to larger con­text sizes with­out a drop in qual­ity or speed.

P.S. Today is my birth­day! I’m so grate­ful for the years I’ve been on this earth, and I can’t wait for more. Thanks for read­ing! Here’s to 21.

I write this blog in Neovim, and I’m aware of a good num­ber of other nerds who do the same. I sup­pose I never con­sid­ered that peo­ple might use other code ed­i­tors for writ­ing prose. In fact, it seems that there are a non­triv­ial num­ber of peo­ple us­ing Harper in Visual Studio Code. They seem to be us­ing Harper mostly for Markdown and com­ments in code, but I’d love to get $\LaTeX$ work­ing as well.

Last week, Harper hit a stroke of luck. It was fea­tured on MakeUseOf. The down­stream so­cial me­dia posts col­lec­tively gar­nered nearly 300,000 views and drove a sig­nif­i­cant amount of traf­fic to our site. This all hap­pened in the wake of LanguageTool shut­ting down the free edi­tion of their soft­ware. These two events com­pound to bring more at­ten­tion than ever to Harper — which is amaz­ing. It means our mis­sion and val­ues are res­onat­ing with peo­ple, which is al­ways a good thing.

Reading the MUO ar­ti­cle, we hear a lot of great things about Harper. We also hear that “it skips many of the pre­mium bells and whis­tles of Grammarly”. The au­thor goes on to ex­plain that the pri­vacy Harper pro­vides more than makes up for any miss­ing pre­mium fea­tures, but the point is clear: those fea­tures are deeply de­sired.

So, the ques­tion be­comes: Which of Grammarly’s fea­tures should we work on first, and how?

The Active Voice

I pro­pose that we should fo­cus first on help­ing our users find the ac­tive voice. For con­text, the ac­tive voice is the style of writ­ing where sub­ject of the verb in a clause is the doer of the ac­tion. This is in con­trast to the pas­sive voice, which is where the sub­ject is the re­ceiver of the ac­tion. For ex­am­ple: the sen­tence, “The postal car­rier was bit­ten by the dog” is writ­ten in the pas­sive voice, while the equiv­a­lent sen­tence, “The dog bit the postal car­rier.” is writ­ten in the ac­tive voice.

Text writ­ten in the ac­tive voice is com­monly viewed to be more au­thor­i­ta­tive, con­fi­dent, and eas­ier to un­der­stand. Be­ing able to help users use the ac­tive voice is one of the most com­monly re­quested fea­tures in Harper, and in­clud­ing the fea­ture would be a huge step to­wards com­pet­ing di­rectly with Grammarly Premium.

How should we go about help­ing our users with their ac­tive voice?

How It Could Be Done

I spoke briefly with Matt, and we agreed that a two tier so­lu­tion would be best. A fast al­go­rithm or model would de­tect in­stances of the pas­sive voice, let­ting a larger more com­pu­ta­tion­ally ex­pen­sive model gen­er­ate a mod­i­fi­ca­tion in the ac­tive voice.

Fortunately, there is al­ready ex­ten­sive lit­er­a­ture on the de­tec­tion of the pas­sive voice. In par­tic­u­lar, I found the PassivePy pa­per stim­u­lat­ing. In fact, we can im­ple­ment their ideas quite eas­ily us­ing the Weir lan­guage al­ready baked into Harper. I have done so in a pri­vate branch. It turned out to be ~20 lines of code. That is pretty good bang for the buck!

The sec­ond piece, which has to do with the ac­tual sim­pli­fi­ca­tion of text and con­ver­sion from the pas­sive voice to the ac­tive voice is a tad more com­plex.

Matt and I agree that it will re­quire the use of a larger lan­guage model. The trou­ble is that it can­not be too large. Harper’s shtick is that it is fast, pri­vate, and that every­thing runs di­rectly on our user’s de­vices. That means whichever model we use for our style trans­fer will need to be rel­a­tively small.

I be­lieve the best so­lu­tion to this prob­lem is to take an off-the-shelf model, like one of Google’s T5 mod­els, and fine tune it for the spe­cific types of style trans­fer we need. These are rel­a­tively small mod­els (quantized, they can fit into spaces un­der 65 megabytes) and they run quite quickly, even on older hard­ware that does­n’t have ac­cess to ma­trix mul­ti­pli­ca­tion ac­cel­er­a­tors. There is prior art for run­ning this at 50 tok/​s in Chrome with­out WebGPU on a sin­gle core. The best part is that they’re un­der the Apache-2.0 li­cense!

How This Fits in with the Weirpack Project

These mod­els are small, but they’re not quite small enough to be a part of the stan­dard dis­tri­b­u­tion of Harper. I be­lieve this should be an opt-in fea­ture, and the best way to do that is to ex­pose the func­tion­al­ity via a Weirpack. If you don’t know what a Weirpack is, I highly sug­gest you read my pre­vi­ous blog posts on the sub­ject.

Everyone who wants this ad­di­tional func­tion­al­ity could just en­able it in the mar­ket­place. This con­tin­ues our goal to make Harper as cus­tomiz­able as our users want, while pro­vid­ing sen­si­ble de­faults.

What’s Next?

Once we have the sys­tem in place to de­tect and pro­vide sug­ges­tions for the ac­tive voice, we will be pre­pared to do other kinds of trans­for­ma­tion, like for ad­just­ing for­mal­ity or tone.

I’m re­ally ex­cited about this pro­ject, and I can’t wait to get started.

Linkarzu’s re­cent video about Harper is a great primer on what it can do if you spend a ton of time in Neovim (like I do). It’s true: Harper is get­ting bet­ter.

This week, I re­ceived a mes­sage from some­one work­ing on a learn­ing man­age­ment sys­tem. Ap­par­ently, they use harper.js to do spell and gram­mar check­ing on in­ter­nal doc­u­ments. They wanted to be able to con­fig­ure Harper to catch a spe­cific class of mis­takes that are com­mon to their work­flow. Look­ing through the doc­u­men­ta­tion for harper.js, they could­n’t see a way to do what they wanted.

Naturally, I di­rected them to­ward my re­cent work on Weir, an ex­pres­sive pro­gram­ming lan­guage for lo­cat­ing er­rors in nat­ural lan­guage. For those just catch­ing up, this post is a part of a se­ries. You should­n’t need to go back and read my pre­vi­ous posts, but I’ll link them here any­how.

• Building The Weir Language
• Updates on the Weir Language
• Generating Weir Code With LLMs
• Imagine A Weir Marketplace

Unfortunately, I had to in­form them that Weir is still an ex­per­i­ment (although it’s in the master branch and thus used by nightly users) and there­fore is­n’t yet avail­able through pub­lic chan­nels. That said, it’s an ex­per­i­ment I’d like to make avail­able to the pub­lic soon, along­side the Weir Marketplace. Before I do so, I want to make it as easy as pos­si­ble to au­thor rules us­ing Weir. That’s why I’m in­tro­duc­ing the Weir Studio.

The Weir Studio

The Weir Studio comes from a pretty sim­ple idea. We want to give peo­ple all the tool­ing nec­es­sary to build and dis­trib­ute Weir rules with­out any up­front cost. That means there should be no tools that need to be in­stalled, no spe­cific op­er­at­ing sys­tem set up, and no pro­gram­ming ex­pe­ri­ence needed.

The so­lu­tions to the first and sec­ond items are sim­ple: Just like any other com­po­nent of Harper, we can com­pile Weir to WebAssembly and con­nect it up to a web ap­pli­ca­tion. Us­ing off-the-shelf com­po­nents for ter­mi­nal em­u­la­tion, text edit­ing, and vir­tual filesys­tems, we can pre­sent a mean­ing­fully fea­ture-rich de­vel­op­ment en­vi­ron­ment from in­side the user’s browser.

The last item is also straight­for­ward. I’ve demon­strated that LLMs are al­ready ter­ri­bly ef­fec­tive at writ­ing Weir rules. By mak­ing that sit­u­a­tion ob­vi­ous and ac­ces­si­ble, we can em­power peo­ple to write and dis­trib­ute their own Weirpacks (files con­tain­ing one or more Weir rules) with­out any prior un­der­stand­ing of the lan­guage or even of ba­sic pro­gram­ming prin­ci­ples.

The Weir Studio is still in progress, but the ini­tial ver­sions are al­ready prov­ing ex­tremely ef­fec­tive for some of my other work.

Putting Power Back into the Hands of Users

A com­mon frus­tra­tion with tools like Grammarly or QuillBot is that they lack cus­tomiza­tion, and thus are of­ten un­able to di­rectly ad­dress user’s needs. By al­low­ing users full ac­cess to the in­ter­nals via Weir, we can help them help them­selves while also en­cour­ag­ing peo­ple to con­tribute back to the pro­ject. It’s a win-win!

What’s Next?

I’d like to wire this up to a mar­ket­place as soon as pos­si­ble (see what I did there?) to stream­line the pub­lish­ing process. More crit­i­cally, I’ve been in­formed that the in­clu­sion of dic­tio­nary files di­rectly into Weirpacks should be pri­or­ity num­ber one. I’ll likely start tack­ling that as soon as I have a spare mo­ment.

If you have thoughts on where Harper or Weir is go­ing, please don’t hes­i­tate to voice them.

P.S. A great piece was just pub­lished about Harper.

For con­text, I main­tain an open-source gram­mar checker by the name of Harper. This post is a kind of RFC for a po­ten­tial im­prove­ment to the pro­jec­t’s er­gonom­ics.

I’ve ob­served a high de­gree of spe­cial­iza­tion of lan­guage be­tween aca­d­e­mic fields.

Ecologists use bits of lan­guage that com­puter sci­en­tists don’t use, and com­puter sci­en­tists use bits of lan­guage that ecol­o­gists don’t use. If we em­brace this spe­cial­iza­tion through cus­tomiza­tion, we could gain an ad­van­tage over other gram­mar check­ers. That’s all to say: We want to en­able au­thors and aca­d­e­mics to cus­tomize Harper to their spe­cial­ized lan­guage. For ex­am­ple, a chemist might want to en­force a set of rules for en­sur­ing mol­e­cules are named cor­rectly ac­cord­ing to the IUPAC stan­dard, and a sci­ence fic­tion au­thor might want to en­force rules to make sure spe­cific char­ac­ters are ad­dressed by the proper ti­tles. Weir is the so­lu­tion to these prob­lems.

In this post, I’ll re­cap what Weir is, and out­line a mech­a­nism for dis­trib­ut­ing Weir rules to in­di­vid­ual users that might take ad­van­tage of them. I’d love your thoughts on how we can make it as im­pact­ful and in­ter­ac­tive as pos­si­ble.

In my ini­tial post about Weir, I dis­cussed how most large or­ga­ni­za­tions have style guides which de­fine spe­cific rules for their em­ploy­ee’s gram­mar, cap­i­tal­iza­tion, and for­mat­ting. I pro­posed a pro­gram­ming lan­guage by the name of Weir, which could be used to clearly state these rules to be en­forced by Harper. I’ve per­son­ally found that LLMs are not great at en­forc­ing strict gram­mat­i­cal guide­lines, but they’re ex­cel­lent at trans­lat­ing them from an ex­ist­ing style guide into the Weir lan­guage. See my re­cent ex­per­i­men­ta­tion for more de­tails.

Now that Weir has been merged, we can move on to the other prob­lems: cre­ation and dis­tri­b­u­tion. To­day, I’d like to talk about dis­tri­b­u­tion.

I’ve had sev­eral dis­cus­sions in the last week from peo­ple who want to be able to cus­tomize Harper with their own rules. This in­cludes peo­ple who use Harper as a part of their con­tin­u­ous in­te­gra­tion, aca­d­e­mics, and some en­gi­neers who work on learn­ing man­age­ment sys­tems. There is a need and de­sire for this to­day, and I want to ad­dress it as soon as pos­si­ble.

Distribution

Once a col­lec­tion of Weir rules has been drafted, how should it be shared? There is a for­mat­ting piece, as well as an in­fra­struc­ture piece.

Weirpacks

I pro­pose a sim­ple, but ef­fec­tive for­mat for shar­ing col­lec­tions of Weir rules. In­stances of this for­mat should be called “Weirpacks” and thus have the file ex­ten­sion .weirpack.

Right now, the Weir rules baked into Harper are or­ga­nized into a sin­gle di­rec­tory, weir_rules, with each .weir file pre­fixed with the rule’s name. For ex­am­ple, the file con­tain­ing the rule for fix­ing Their to There is TheirToTheir.weir. There are a vast quan­tity of these “curated” rules, and I don’t think they should go any­where. I just think we can reuse the lay­out.

I be­lieve the best strat­egy for or­ga­niz­ing col­lec­tions of Weir rules is to repli­cate what’s al­ready in the Harper repos­i­tory, but in­side a ZIP archive. Even though it is a ZIP file, which nor­mally have the suf­fix .zip, I think we should give them the .weirpack suf­fix for clar­ity on their pur­pose. The root di­rec­tory of the archive will con­tain as many .weir files as is de­sired by the Weirpack au­thor, in ad­di­tion to a .json man­i­fest file con­tain­ing pack­age meta­data.

Metadata

Since JSON is quite flex­i­ble, Weirpack au­thors can in­clude what­ever in­for­ma­tion they want. I think cer­tain fields, how­ever, should be re­quired. Namely:

• The Author’s Name
• The Weirpack’s ver­sion
• A de­scrip­tion of the Weirpack’s pur­pose and us­age
• The Weirpack’s li­cense

I think we can also rec­om­mend, but not re­quire some ad­di­tional help­ful in­for­ma­tion:

• Keywords rel­e­vant to the rule’s pur­pose
• The Author’s Website

Loading Weirpacks

Support for Weirpacks will be baked di­rectly into harper-core, as well as harper.js.

The for­mer will make it pos­si­ble for our com­mand-line pro­grams, harper-cli and harper-ls, to load them at run­time. In harper-cli, which is a de­bug­ging tool, it will be suf­fi­cient to ex­pose a flag on our lint com­mand to al­low Weirpacks to be loaded. In harper-ls, we need to up­date our con­fig to al­low Weirpacks to be loaded from a di­rec­tory on the disk. The de­fault should be next to where the dic­tio­nar­ies are al­ready loaded.

The lat­ter will make it pos­si­ble for our web in­te­gra­tions to load them when the user de­sires, ei­ther from disk or from our mar­ket­place (more on that in a minute). For both the Obsidian plu­gin, as well as the Chrome ex­ten­sion, we’ll in­clude a field in the set­tings menus for users to load Weirpacks from disk and into the lin­ter. Nat­u­rally, these will per­sist across ses­sions in the same way the other set­tings do.

Being able to load Weirpacks from disk is crit­i­cal to al­low­ing users to re­main com­pletely of­fline if they choose to be. Ad­di­tion­ally, load­ing cus­tom Weirpacks with­out ap­proval from a mod­er­a­tor is a pre­req­ui­site to hav­ing a quick and en­joy­able it­er­a­tive loop.

The Weir Marketplace

When a user in a field with spe­cial­ized lan­guage down­loads Harper, we will nat­u­rally pro­vide them with the es­sen­tial rules that are com­mon to the en­tirety of the English lan­guage. We will also give them the op­tion to down­load ad­di­tional Weirpacks from the Weir Marketplace. This will be a place, not un­like Obsidian’s Community Plugins Marketplace, where user-sub­mit­ted Weirpacks can be down­loaded and in­stalled quickly and eas­ily.

Imagine, if you will, that you’re a JavaScript de­vel­oper who has just down­loaded Harper. You start writ­ing a blog post about your re­cent ad­ven­tures with the lat­est JavaScript frame­work. Un­for­tu­nately, Harper starts flag­ging swaths of your work as mis­spelled and filled with poor gram­mar.

Thankfully, Harper no­tices its mis­take and of­fers to down­load a rel­e­vant Weirpack for pro­gram­mers—one pre­set with a dic­tio­nary filled with tech­ni­cal lan­guage and rules to en­sure proper use. You down­load the Weirpack and con­tinue writ­ing with Harper now bet­ter equipped to han­dle the sub­ject at hand. Cri­sis averted.

The Long View

This idea of a self-con­tained Weirpack pro­vid­ing the logic and the datasets nec­es­sary to do gram­mar check­ing for a spe­cial­ized sub­set of English is in­tox­i­cat­ing. Pro­ject­ing for­ward, I can imag­ine a fu­ture where we can pro­vide sup­port for any num­ber of nat­ural lan­guages, dis­trib­uted via Weirpacks and sup­ported by a com­mu­nity of con­trib­u­tors in a de­cen­tral­ized way, not dis­sim­i­lar to WordPress’ plu­gin mar­ket­place. That is­n’t for to­day, though.

A while back, I wrote a small tool, dubbed “Tatum”, for ren­der­ing Markdown to HTML for use along­side Neovim. I’ve con­tin­ued to use it to this day, with a few tweaks here and there.

It looks like some­one has taken ad­van­tage of Tatum’s open-source li­cense and remixed it into some­thing even more ca­pa­ble. I highly sug­gest you check out penview.nvim.

I re­cently did some snoop­ing (through Dependabot) on what open source pro­jects have been us­ing Harper. Since I last checked, there are some new ones. I won­der if the re­cent ad­di­tions have any­thing to do with Harper go­ing 1.0.

• Stubby
• Stencila
• Gherlint
• wal­let­beat
• fixmyspelling

Someone also wrote a book us­ing Harper.

This post is now out-of-date. There are even more pro­jects us­ing Harper to­day (as of 6.11.2026). The canon­i­cal list ex­ists in Harper’s Documentation

As you know, I’ve been work­ing on a small pro­gram­ming lan­guage called Weir for gen­er­at­ing cor­rec­tions to nat­ural lan­guage. For the cu­ri­ous, I highly sug­gest read­ing my pre­vi­ous blog posts on the sub­ject if you haven’t al­ready.

• Building the Weir Language
• Updates on the Weir Language

In one of those pre­vi­ous blog posts, I spec­u­lated that an LLM might be quite ef­fec­tive at gen­er­at­ing these rules, es­pe­cially if they are given ac­cess to tools that can val­i­date and run tests. To­day, while writ­ing some pub­lic doc­u­men­ta­tion for the lan­guage, I did a bit of ex­per­i­men­ta­tion. I wanted to know: Can an LLM si­mul­ta­ne­ously han­dle the com­plex chal­lenge of un­der­stand­ing a DSL’s syn­tax, the se­man­tics of the English lan­guage, and be able to val­i­date its own work with tests? More to the point: can it do a bet­ter job with a DSL than an es­tab­lished lan­guage like Rust?

For those who want to fol­low along at home, here’s the GPT I’ve been toy­ing around with.

Some Experimentation

I of­ten hear that one should avoid novel or ex­ceed­ingly old pro­gram­ming lan­guages when work­ing with LLMs, sim­ply be­cause these lan­guages aren’t well rep­re­sented in their train­ing data. Based on this hearsay, I did­n’t ex­pect much go­ing into this lit­tle ex­per­i­ment of mine.

First, I won­dered if it could han­dle the triv­ial is­sue of cor­rect­ing “as nau­seam” to the cor­rect form, “ad nau­seam”. It’s a com­mon typo, and it should be pretty sim­ple Weir rule.

My min­i­mal GPT spit this out:

expr main (as nauseam)

let message "Did you mean `ad nauseam`?"
let description "Corrects the common typo `as nauseam` to the proper Latin phrase `ad nauseam`."
let kind "Typo"
let becomes "ad nauseam"

test "He repeated the point as nauseam." "He repeated the point ad nauseam."
test "This argument has been made ad nauseam." "This argument has been made ad nauseam."

That looks pretty good! All the syn­tax is cor­rect, and it even in­cluded some (passing!) tests. Claude Code or Codex could do this us­ing our ex­ist­ing Rust in­fra­struc­ture, but it would have taken sev­eral min­utes to churn out a valid re­sult. GPT 5.2 Instant was able to do this in a mat­ter of sec­onds. Not to men­tion that it did­n’t need a copy of the en­tire Harper source code.

I wanted to try a prob­lem that was a bit harder to solve, so I asked it to ad­dress the prob­lem of dou­ble-neg­a­tives. Af­ter think­ing for a few min­utes, it came up with four in­di­vid­ual rules that each ad­dress dif­fer­ent cases.

expr main <(
  [(don't), (do not), (doesn't), (does not), (didn't), (did not),
   (can't), (cannot), (couldn't), (could not),
   (won't), (will not), (wouldn't), (would not),
   (shouldn't), (should not),
   (isn't), (is not), (aren't), (are not), (wasn't), (was not), (weren't), (were not),
   (ain't)]
  [$have, $get, $need, $want, $know, $see, $find, $say, $do]
  no
), no>

let message "Avoid a double negative."
let description "If the clause is already negated (e.g., `don't`), prefer `any` over `no` (e.g., `don't have any`)."
let kind "Usage"
let becomes "any"
let strategy "MatchCase"

test "I don't have no idea." "I don't have any idea."
test "She did not get NO response." "She did not get ANY response."
test "I have no idea." "I have no idea."

expr main <(
  [(don't), (do not), (doesn't), (does not), (didn't), (did not),
   (can't), (cannot), (couldn't), (could not),
   (won't), (will not), (wouldn't), (would not),
   (shouldn't), (should not)]
  [$do, $say, $see, $hear, $find, $know, $have, $get]
  nothing
), nothing>

let message "Avoid a double negative."
let description "If the clause is already negated, replace `nothing` with `anything` (e.g., `didn't do anything`)."
let kind "Usage"
let becomes "anything"
let strategy "MatchCase"

test "He didn't do nothing." "He didn't do anything."
test "I can't see NOTHING." "I can't see ANYTHING."
test "I did nothing." "I did nothing."

expr main <(
  [(don't), (do not), (doesn't), (does not), (didn't), (did not),
   (can't), (cannot), (couldn't), (could not),
   (won't), (will not), (wouldn't), (would not)]
  [$tell, $call, $see, $know, $say, $help, $find]
  nobody
), nobody>

let message "Avoid a double negative."
let description "If the clause is already negated, replace `nobody` with `anybody`."
let kind "Usage"
let becomes "anybody"
let strategy "MatchCase"

test "I didn't tell nobody." "I didn't tell anybody."
test "We can't find NOBODY." "We can't find ANYBODY."
test "Nobody called." "Nobody called."

expr main <(
  [(don't), (do not), (doesn't), (does not), (didn't), (did not),
   (can't), (cannot), (couldn't), (could not),
   (won't), (will not)]
  [$go, $run, $walk, $drive, $get, $look]
  nowhere
), nowhere>

let message "Avoid a double negative."
let description "If the clause is already negated, replace `nowhere` with `anywhere`."
let kind "Usage"
let becomes "anywhere"
let strategy "MatchCase"

test "She can't go nowhere tonight." "She can't go anywhere tonight."
test "I did not look NOWHERE else." "I did not look ANYWHERE else."
test "Nowhere is safe." "Nowhere is safe."

Again, I’m quite im­pressed. Ob­vi­ously, it’s hard to tell at first glance whether these rules would hold up in pro­duc­tion for tens of thou­sands of users. Nev­er­the­less, these rules look cor­rect, and my ini­tial test­ing shows that they work. The model was able to suc­cess­fully ap­ply more com­plex logic: the de­riva­tion syn­tax and the fil­ter syn­tax.

In my orig­i­nal an­nounce­ment blog post, I ex­plained that the tar­get au­di­ence for Weir were the mem­bers of large or­ga­ni­za­tions that wish to en­force styl­is­tic con­ven­tions or brand names through­out their work­force. To that end, I wanted to test an LLM against some of Automattic’s nomen­cla­ture. Af­ter read­ing though some of our pub­lic doc­u­men­ta­tion, it come up with some ad­mit­tedly use­ful rules:

expr main (wpvip)

let message "Use the official spacing for VIP."
let description "Expands `wpvip` to the official brand forms `WordPress VIP` or `WP VIP`."
let kind "Miscellaneous"
let becomes ["WordPress VIP", "WP VIP"]
let strategy "Exact"

test "This runs on wpvip." "This runs on WordPress VIP."

expr main (jet[-, ( )]pack)

let message "Use the official spelling `Jetpack`."
let description "Standardizes `jet pack` / `jet-pack` to `Jetpack`."
let kind "Miscellaneous"
let becomes "Jetpack"
let strategy "Exact"

test "Install jet pack for backups." "Install Jetpack for backups."
test "Install jet-pack for backups." "Install Jetpack for backups."
test "Install Jetpack for backups." "Install Jetpack for backups."

expr main (word[-, ( )]press)

let message "Use the official spelling `WordPress`."
let description "Standardizes `word press` / `word-press` to the product name `WordPress`."
let kind "Miscellaneous"
let becomes "WordPress"
let strategy "Exact"

test "I build sites with word press." "I build sites with WordPress."
test "I build sites with word-press." "I build sites with WordPress."
test "I build sites with WordPress." "I build sites with WordPress."

Again, I’m quite pleased. With just a quick search of our web­site, it was able to dis­cern what style we wished to en­force and wrote func­tion­ing Weir rules to do so. I can see this be­ing help­ful at any num­ber of busi­ness that com­mu­ni­cate reg­u­larly.

Conclusion

Overall, I’m quite pleased with how well these LLMs were able to write Weir code. I’ve yet to fi­nal­ize any doc­u­men­ta­tion on the more com­plex parts of Weir’s syn­tax (like our POS-tagging sys­tem), which means I haven’t yet been able to test them with any LLMs. Even so, I’m im­pressed.

I even tried it out on Mistral’s tiny and ul­tra-fast three bil­lion pa­ra­me­ter model. It per­formed al­most as well as OpenAI’s 5.2 Instant model, al­beit with­out nearly the same level of cre­ativ­ity. I think this some­what proves that mod­ern LLMs are able to gen­er­al­ize to novel lan­guages, which makes them ex­ceed­ingly use­ful for DSLs like Weir.

I’m look­ing for­ward to see­ing how peo­ple end up tak­ing ad­van­tage of this.

In my last blog post, I de­scribed the why, what, and how of the Weir pro­gram­ming lan­guage. I sug­gest you read that first.

Before sign­ing off for the day, I just wanted to give a few up­dates on the pro­ject. For those in­ter­ested in the tech­ni­cal side of things, I’ve opened a draft PR for your read­ing plea­sure.

Updated Keywords

After hav­ing a con­ver­sa­tion with Jason Adams, I came to the re­al­iza­tion that declare and set are pretty sh*tty key­words. They aren’t self-de­scrib­ing and you’d be hard-pressed to find any real pro­gram­ming lan­guage that uses them.

I’ve in­stead re­placed them with let and expr.

Here’s what the rule from my last blog post looks like with these up­dated key­words:

expr main [(G [Suite, Suit]), (Google Apps for Work)]
let message "Use the updated brand."
let description "`G Suite` or `Google Apps for Work` is now called `Google Workspace`"
let kind "Miscellaneous"
let becomes "Google Workspace"
let strategy "Exact"

Note that I’ve also added the strategy set­ting. This al­lows rule au­thors to de­scribe which strat­egy Harper will use when ap­ply­ing the re­place­ments. Right now, the only two op­tions are Exact or MatchCase, which ap­ply ei­ther the ex­act text, or the ex­act text but match­ing the cap­i­tal­iza­tion of the text it re­places. In the above ex­am­ple, we use Exact be­cause it is a proper noun, and it does­n’t mat­ter what the orig­i­nal text looked like: we want to cap­i­tal­ize it prop­erly.

Deprecation of the phrase_corrections Module

I’ve also gone ahead and con­verted the en­tirety of the phrase_corrections mod­ule, as well as all as­so­ci­ated tests, to the Weir lan­guage. If you’re read­ing this and you’re a con­trib­u­tor, know that we will no longer be adding new rules to that mod­ule once Weir is merged into master. When the merge hap­pens, I’ll han­dle the con­ver­sion of any lag­ging phrase cor­rec­tions that haven’t al­ready been con­verted.

That un­for­tu­nately means that my pre­vi­ous guide on the sub­ject is no longer rel­e­vant.

What’s Next?

Before Weir gets merged, I plan to sup­port the match­ing of UPOS tags, in ad­di­tional to some other qual­ity of life up­dates. Ex­pect an­other blog post.

In the mean­time, please let me know if you have any ad­di­tional in­put!

Most large or­ga­ni­za­tions have a style guide. A doc­u­ment that de­cides which ver­sions of a lin­guis­tic rule to use. That could be whether to use the Oxford comma, or if con­trac­tions are al­lowed. It could de­clare that a cer­tain word should be cap­i­tal­ized in a spe­cific con­text.

Harper can cover most of the rules in most style guides, but there will al­ways be out­liers that we can’t sup­port (or sim­ply don’t know about). That is why it is crit­i­cal that Harper al­low in­di­vid­u­als and or­ga­ni­za­tions to de­fine rules and con­ven­tions for Harper to en­force.

For the last few days, I’ve been pro­to­typ­ing a sim­ple (not Turing-complete) pro­gram­ming lan­guage for de­scrib­ing these con­ven­tions. I’ve called it Weir. Weir is sim­ple and thus easy to learn, but has es­cape hatches for in­stances where more com­plex logic is nec­es­sary.

Before I be­gin, a quick dis­claimer: This is early work. The Weir lan­guage will likely change and evolve be­fore it makes it into core. What you see here is rep­re­sen­ta­tive of the over­all de­sign, but noth­ing is fi­nal yet.

History

There are in­evitably go­ing to be a good num­ber of edge cases that need to be ad­dressed when build­ing a gram­mar checker. For these, Harper has a sim­ple map from prob­lem­atic phrases to the cor­rected ver­sions. Edge cases that are not sim­ple enough to be de­scribed with a map are im­ple­mented as Rust code. Here’s what the map looks like:

add_exact_mappings!(group, {
    // The name of the rule
    "ACoupleMore" => (
        // The phrase(s) to look for.
        ["a couple of more"],
        // The corrections to provide.
        ["a couple more"],
        // The message to be shown with the error.
        "The correct wording is `a couple more`, without the `of`.",
        // A description of the rule.
        "Corrects `a couple of more` to `a couple more`.",
        LintKind::Redundancy
    ),
    "CondenseAllThe" => (
        ["all of the"],
        ["all the"],
        "Consider simplifying to `all the`.",
        "Suggests removing `of` in `all of the` for a more concise phrase.",
        LintKind::Redundancy
    ),
    "CoursingThroughVeins" => (
        ["cursing through veins"],
        ["coursing through veins"],
        "In this idiom, blood “courses” (flows) through veins, not “curses”.",
        "In English idioms, “to course” means to flow rapidly—so avoid the eggcorn `cursing through veins.`",
        LintKind::Eggcorn
    ),
});

As for the Rust code, it is of­ten heinous and a chore to re­view. I won’t do my­self the em­bar­rass­ment of in­clud­ing it here.

Introducing Weir

The heart of Weir is an ex­pres­sion lan­guage that mim­ics the pseudocode Harper con­trib­u­tors tend to use when de­scrib­ing the Rust code they in­tend to write.

Imagine you work at Google. You’ve just re­branded the “G Suite” col­lec­tion of apps and ser­vices to the new name “Google Workspace”. Before that, they were col­lec­tively named “Google Apps for Work”. Moving for­ward, you don’t want you or your cowork­ers to ac­ci­den­tally write “G Suite” on pub­lic doc­u­men­ta­tion, be­cause do­ing so might con­fuse users. To solve this, you use the fol­low­ing Weir rule:

set main [(G [Suite, Suit]), (Google Apps for Work)]

declare message "Use the updated brand."
declare description "`G Suite` or `Google Apps for Work` is now called `Google Workspace`"
declare kind "Miscellaneous"
declare becomes "Google Workspace"

The first line de­scribes the pat­tern of the prob­lem­atic text. There are two cases here:

1. The let­ter “G” fol­lowed by “Suite” or its mis­spelling “Suit”
2. The lit­eral phrase “Google Apps for Work”

Here is a se­man­ti­cally equiv­a­lent ex­am­ple that I find a bit eas­ier to read:

set main [(G Suite), (G Suit), (Google Apps for Work)]

The re­main­ing lines de­scribe:

1. The mes­sage to be shown to the user when the er­ror in en­coun­tered.
2. A de­scrip­tion of the rule it­self, ex­plain­ing why it ex­ists.
3. What kind of rule it is. I sus­pect most end users will mark it as “miscellaneous”. I’m con­sid­er­ing mak­ing this field op­tional.
4. What cor­rec­tions to pro­vide to the user.

One of my goals here was to make the sys­tem sim­ple enough for an end-user to copy and paste an ex­ist­ing rule into a new file, make some tweaks, and they would be done. For the more com­plex cases, I think we could set up a cus­tom GPT to write these pretty eas­ily.

Here’s an­other ex­am­ple, one that will ac­tu­ally be a part of the Harper source code. It uses a fil­ter (the <> syn­tax) to first se­lect the broader phrase, then an­other to se­lect the white­space in-be­tween (that’s the ( ) part).

set main <([right, middle, left] $click), ( )>
declare message "Hyphenate this mouse command"
declare description "Hyphenates right-click style mouse commands."
declare kind "Punctuation"
declare becomes "-"

This is a great ex­am­ple of the $ tag. In­stead of in­struct­ing Harper to look for the lit­eral word af­ter­ward, it in­stead in­structs it to look for all de­riv­a­tive words. Those in­clude “click”, “clicking”, “clicked”, etc.

We also have spe­cific syn­tax that can be used to test the ex­pres­sion in­line. These as­sert that the left string, af­ter be­ing passed through the rule, be­comes the right string.

test "Right click the icon." "Right-click the icon."
test "Please right click on the link." "Please right-click on the link."
test "They right clicked the submit button." "They right-clicked the submit button."
test "Right clicking the item highlights it." "Right-clicking the item highlights it."
test "Right clicks are tracked in the log." "Right-clicks are tracked in the log."
test "He RIGHT CLICKED the file." "He RIGHT-CLICKED the file."
test "Left click the checkbox." "Left-click the checkbox."
test "Middle click to open in a new tab." "Middle-click to open in a new tab."

I sus­pect Weir will make it ex­tremely easy for AI agents to it­er­ate quickly on these rules. There’s no com­pi­la­tion step, and we al­ready have ex­cel­lent pipelines for gen­er­at­ing lists of test cases.

Why Call It “Weir”?

I am nam­ing Weir af­ter the au­thor of Project Hail Mary, Andy Weir. I guess I just like nam­ing things af­ter au­thors. Af­ter all, Harper it­self was named af­ter Harper Lee.

Moving Forward

Once the syn­tax is fi­nal­ized and a cor­pus of tests have been writ­ten, I sus­pect Weir rules will be­come the de­fault for new gram­mat­i­cal rules in­side the Harper repos­i­tory and for in­di­vid­ual users. I’d love to cre­ate a mar­ket­place for rule sets cre­ated by and for the com­mu­nity.

If you (the reader) have any thoughts on syn­tax or any­thing else, don’t hes­i­tate to speak your mind.

In case you did­n’t know: Harper can con­vert text to ti­tle case! This has been around for a long time, but we haven’t re­ally talked about it pub­licly. Be­ing able to make text ti­tle case (strictly in ac­cor­dance to Chicago Style) is­n’t a ground­break­ing fea­ture, but it is use­ful for cer­tain niche ap­pli­ca­tions.

For ex­am­ple, all the ti­tles in this very blog are forced to ti­tle case on pub­lish, which is­n’t some­thing most CMS sys­tems do. I’d love to see it be­come more wide­spread.

We have a live demo where you can try it out. It’s also avail­able as part of harper.js, our JavaScript pack­age.

Soon, this will be­come a part of Harper’s na­tive lint­ing ca­pa­bil­i­ties.

Today, we pub­lished Harper’s 1.0.0 re­lease. It’s a huge mile­stone, and in this post I’d like to dis­cuss why it took so long, why we’re do­ing it now, and what’s next for the pro­ject.

A Round of Applause, Please

As I men­tioned: This is a huge step for the pro­ject. Before I say any­thing else, I want to take a mo­ment to ap­pre­ci­ate the col­lec­tive work of our many con­trib­u­tors. It has taken many it­er­a­tions to get to where we are to­day, and it would­n’t be pos­si­ble with­out the com­mu­ni­ty’s ef­fort and feed­back.

Why Now?

Until to­day, I’ve kept Harper in a pre-1.0 state for one rea­son: I wanted to move fast. More specif­i­cally, I wanted the free­dom to build and break things as many times as I needed to. I knew that it would take many cy­cles of build­ing and re­build­ing ar­rive at a ro­bust sys­tem that ad­dresses the peo­ple’s need for a pri­vate writ­ing tool. I be­lieve that build­ing some­thing good can of­ten mean tak­ing the bad parts out. Once a pro­ject is “1.0”, it be­comes much harder to re­move things. Naturally, that pushed me to hold off on “going 1.0″.

Of course, that did­n’t stop us from get­ting the soft­ware into the hands of users. Today, tens of thou­sands of peo­ple ben­e­fit from Harper’s fast and pri­vate gram­mar check­ing in Chrome, Obsidian, VS Code, and Neovim (among many oth­ers). We’ve racked up hun­dreds of thou­sands of down­loads be­fore ever slap­ping any­thing other than zero be­fore the first dec­i­mal point of our ver­sion num­ber.

I’m sure your think­ing: “Elijah! Get to the point!” Fine. The rea­son we’re do­ing this now, rather than ear­lier or later, is be­cause our pri­or­i­ties have just re­cently changed.

For one, Harper’s API has been rock-solid for a few months now, which means we can safely say that our need to move fast in that area has di­min­ished. The op­por­tu­nity cost of abid­ing by a sta­ble API has gone down.

Secondly, I’ve been hear­ing pro­gres­sively more in­ter­est from po­ten­tial con­trib­u­tors and con­sumers who want to put Harper di­rectly into their own apps or ser­vices. They have the de­sire to help make Harper more wide­spread, but they can’t com­mit to it un­less Harper com­mits to a sta­ble API. That’s what we’re do­ing to­day.

I can imag­ine a fu­ture where Harper is na­tively in­te­grated every­where: learn­ing man­age­ment sys­tems, doc­u­ment ed­i­tors, mes­sag­ing plat­forms, or even op­er­at­ing sys­tems. But great things take time. Today, we’re tak­ing a huge step in set­ting Harper up for the long-term.

What Do I Need to Know?

As an end-user, not much changes. From here on out, we’ll be push­ing qual­ity-of-life tweaks and bug­fixes at a faster rate, all while im­prov­ing Harper’s ca­pa­bil­i­ties across the board.

As a con­trib­u­tor, the patch re­view process might get a lit­tle bit more strict. We’ll be fo­cus­ing more on im­prov­ing the qual­ity of our code, rather than the amount. If your PRs are likely to re­sult in a break­ing change, ex­pect co­pi­ous notes and pos­si­ble de­lays be­fore we hit “merge”.

As an in­te­gra­tor, you win more than any­one. If you’d like to in­clude Harper in your ap­pli­ca­tion, let us know and we’ll do our best to make it easy for you. Take a look at our ver­sion­ing pol­icy if that sort of thing gives you peace of mind.

Where Can I Get Further Updates?

That de­pends on the level of ver­bosity your in­ter­ested in. For those who want to know about every­thing I’m cur­rently work­ing, sub­scribe to my blog. For every­one else, our patch notes in GitHub should suf­fice.

Earlier this week, I was look­ing through a table of user feed­back about Harper. I be­lieve that soft­ware should be build with the user—not just for the user—so this is a pretty reg­u­lar rit­ual for me.

I was de­lighted. Many of the usual com­plaints were to­tally ab­sent from the re­port. Users were en­coun­ter­ing fewer of the make-or-break bugs that would harm their ex­pe­ri­ence. This meant that my re­cent push to get Harper pre­pared for a 1.0 re­lease was work­ing. Great news! Yippee!

Unfortunately, some­thing new emerged from be­neath the pile of bugs: prob­lems with Harper’s vi­sual de­sign.

For quite some time now, I’ve been fo­cused solely on the prac­ti­cal parts of Quality. I mean bugs and the hard-to-deny use­ful­ness of Harper’s ser­vice. In that time, I’ve for­got­ten that the vi­sual ap­peal of the soft­ware is at least as im­por­tant. So, when I saw these com­plaints with Harper’s vi­sual de­sign, I knew I needed to do some­thing about it.

I’ve never claimed to be a de­signer, but I’m also not one to shy away from a chal­lenge. So, I grabbed a copy of the Laws of UX (thanks Eduardo, for the rec­om­men­da­tion) and got to work.

Bring Everything Together

Here’s the se­cret to Harper’s de­sign sys­tem: it has­n’t re­ally ex­isted un­til now. Each of the in­te­gra­tions, from the Chrome ex­ten­sion, to the web­site, and even the Obsidian plu­gin, had their own de­sign sys­tem and ap­pear­ance. Mostly, this was be­cause I did­n’t care enough about it when first craft­ing these pro­jects. Things have changed, so I’m go­ing to take my time and do a good job in an at­tempt to ser­vice these user com­plaints.

Before I could start tweak­ing CSS styles, I needed a uni­fied color scheme. Af­ter some re­search and time in the color picker, I ar­rived at this:

From there, I built out a com­po­nent li­brary based on Flowbite and re­placed all the rel­e­vant com­po­nents in Harper’s in­te­gra­tions with my own.

Next, I wanted to cre­ate a bit more dy­namism with our ty­pog­ra­phy. Af­ter spend­ing some time in Google Fonts, I de­cided to use Domine, a serif font for head­ings and Atkinson Hyperlegible for every­thing else. Once I com­bined the duo with the or­ange-ish yel­low from the color palette (which is usu­ally as­so­ci­ated with cre­ative brands), I felt con­fi­dent that I had nailed what I imag­ined Harper’s per­son­al­ity to be.

Finalizing the Draft

I feel that Harper’s land­ing page em­bod­ies the de­sign sys­tem well, so I’ve shown it be­low. It’s the first, and of­ten only, thing a user sees, so I put some ex­tra care into it. At the time of writ­ing, it is live.

Before My Changes

After My Changes

Where Do I Go From Here?

As I said, this mini-pro­ject was sim­ply a draft. I’ll be work­ing with Harper con­trib­u­tors on a more reg­u­lar ba­sis to con­tinue nail­ing it down, slowly im­prov­ing the Quality of the vi­sual de­sign for the en­tire pro­ject. If you have any feed­back, thoughts, or ideas for how we can make Harper more user-friendly or vi­su­ally ap­peal­ing, let me know!

Earlier this week, I came across a re­ally great post from a prod­uct en­gi­neer over at PostHog. If you haven’t al­ready, I highly rec­om­mend read­ing it. With the ti­tle “Collaboration sucks,” I think it makes its mes­sage clear.

If you had shown this ar­ti­cle to the Elijah Potter from a year ago, he would have agreed with most of what it says. I was of the strong opin­ion that col­lab­o­ra­tion was fun­da­men­tally coun­ter­pro­duc­tive to get­ting sh*t done. Since then, I’ve com­pletely changed my tune. While I don’t be­lieve col­lab­o­ra­tion is the se­cret weapon my pro­fes­sors in school made it out to be, I think it’s es­sen­tial to work­ing on am­bi­tious pro­jects for a long time with­out burn­ing out. Furthermore, at least for open source pro­jects, I think it’s crit­i­cal for pri­or­i­ti­za­tion of work.

First, let’s get some­thing out of the way. Although the post ti­tle de­clared that col­lab­o­ra­tion in any form was bad, the meat and pota­toes of the post have a slightly dif­fer­ent tune. He merely said that it is­n’t that col­lab­o­ra­tion is bad, just that too much col­lab­o­ra­tion is bad. I can get be­hind this, but I still think there’s more nu­ance lurk­ing in the shad­ows.

I think Cook’s post out­lines many of the var­i­ous ways col­lab­o­ra­tion can go wrong. I par­tic­u­larly en­joy the red flag ex­am­ples he pro­vides. I’d like to pro­vide some ex­am­ples of col­lab­o­ra­tion go­ing right.

Since all of this is strictly re­lated to Harper, it’s pos­si­ble that both these ex­am­ples are only help­ful to open source pro­jects.

It Boosts Motivation

When I go a lit­tle bit too long with­out en­gag­ing with a mem­ber of the Harper user base, I start to feel a bit de­flated. I start to for­get who it is all for.

As a part of my own writ­ing en­vi­ron­ment, Harper ex­ists to make writ­ing more fun and more hu­man. I can think crit­i­cally about my mes­sage while spend­ing less time wor­ry­ing about gram­mar or punc­tu­a­tion. For oth­ers, it poses to do all that with­out vi­o­lat­ing their pri­vacy. It’s great to hear from them, and how we can make our ser­vice even bet­ter.

I know I’m do­ing some­thing right when I’m act­ing as cus­tomer sup­port and read a mes­sage like this. I feel em­pow­ered. Not only do I know what I am do­ing right, I feel highly mo­ti­vated to keep do­ing that thing.

In Open Source, Your Collaborators Are Also Your Users

When work­ing on open source soft­ware, es­pe­cially one that val­ues pri­vacy, clearly stat­ing a pol­icy of be­ing friendly to pull re­quests is ob­vi­ously crit­i­cal. For one, it makes it clear that bug fixes are wel­come and will be swiftly re­viewed. Less ob­vi­ous is the feed­back re­sid­ing within the pull re­quest.

Here’s an ex­am­ple. A user en­coun­tered an is­sue re­sult­ing from a change in Obsidian’s API. Not only did he take the time to re­port the prob­lem, he also went through the ef­fort of im­ple­ment­ing a fix. What does this tell us?

For one, it gives us an idea of where our doc­u­men­ta­tion is suf­fi­cient. He was able to find the in­for­ma­tion needed to build the code and run it on his own ma­chine. In the fu­ture, we don’t need to pri­or­i­tize the Obsidian plug­in’s doc­u­men­ta­tion.

More im­por­tantly, how­ever, is the fact that the fea­ture was valu­able enough for this user to spend time fix­ing it. If it is valu­able for him, we can safely say that it is valu­able for other users. Now that I have suf­fi­cient ev­i­dence, I might con­sider bring­ing sim­i­lar func­tion­al­ity to other plat­forms, like our Chrome ex­ten­sion.

Collaborating in an open source con­text can be hugely in­for­ma­tive, since your col­lab­o­ra­tors are also your users. In my ex­pe­ri­ence, this is sur­pris­ingly un­com­mon, even in com­pa­nies that claim to have a cul­ture of feed­back.

There Is Still Such a Thing As Too Much

While I’ve found these par­tic­u­lar cases to be pro­duc­tiv­ity-boost­ers, I un­der­stand that fo­cus­ing too much on any one thing can be detri­men­tal. First and fore­most, the goal should be to ship as high a qual­ity of soft­ware as pos­si­ble, as soon as pos­si­ble.

If you main­tain or work on a pro­ject in any com­piled lan­guage, par­tic­u­larly a lan­guage that is known for hav­ing a slow com­piler, I be­lieve it is crit­i­cal to reg­u­larly sched­ule time to do an analy­sis of your build process and make ad­just­ments if nec­es­sary.

Compile-time in­creases slowly as a pro­ject morphs and grows. Slow enough that it of­ten goes un­no­ticed. I call this “compiler creep” and be­lieve it to be sim­i­lar in many ways to lifestyle creep. By sched­ul­ing time to do a full ac­count­ing of where your CPU cy­cles are go­ing, you can pre­emp­tively save your­self (and your con­trib­u­tors) a lot of time.

Yesterday was the big day for me. Over the last few months, Harper’s com­pile time from scratch in GitHub ac­tions had bal­looned to a five full min­utes. On my per­sonal lap­top, it had grown to three min­utes. That may not sound like a lot, but I of­ten need to build from scratch when swap­ping be­tween branches or check­ing out a pull re­quest. Incremental build times had also grown to an un­jus­ti­fi­able du­ra­tion. Iterating upon unit tests was start­ing to be­come quite slow.

Harper’s low la­tency is one of the rea­sons many turn to it over the al­ter­na­tives. In the early days, we ac­com­plished that by crank­ing the LLVM op­ti­mizer to the max, re­duc­ing the num­ber of code­gen units to one and us­ing link-time op­ti­miza­tion to take care of the rest. At the time, I be­lieve this re­sulted in a ~30% per­for­mance up­lift. Not bad!

For the unini­ti­ated, a code­gen unit is the small­est unit of work that is passed to the LLVM com­piler. If you al­low the pro­ject to be split into more than one code­gen unit, you can al­low more than one com­piler to run at a time. This, there­fore, in­creases the num­ber of phys­i­cal cores that can be used at any given mo­ment dur­ing com­pi­la­tion. The down­side is that the com­piler misses out on op­ti­miza­tion op­por­tu­ni­ties at the bound­aries be­tween code­gen units.

So when I sat down yes­ter­day, I was hardly sur­prised to see that code gen­er­a­tion was the bot­tle­neck. The com­piler was spend­ing very lit­tle time type-check­ing and link­ing, and a lot of time gen­er­at­ing and op­ti­miz­ing ma­chine code.

My ini­tial thought was to re­duce the amount of code that needed op­ti­miz­ing. So I did what any­one else would do and went search­ing for un­nec­es­sary de­pen­den­cies and other kinds of dead code in the repos­i­tory. I found some, but not enough to make a mean­ing­ful dent in the com­pile time.

That’s when I took a look at our build con­fig­u­ra­tion and asked my­self: “Do we still need LTO? Could we in­crease our code­gen units?”

In the last few months, I’ve made some sig­nif­i­cant im­prove­ments to caching and pipelin­ing, which means the bot­tle­neck has shifted from com­pile-time op­ti­miza­tion to mem­ory band­width. We sim­ply don’t need the com­piler to do as much work any­more. So, I tried dis­abling LTO and re­vert­ing the code­gen units to their de­fault value. What hap­pened?

Clean builds went from five min­utes on CI to less than two. All in, that’s an im­prove­ment of 71%. On top of that, since it was the code gen­er­a­tion stage that was slow­ing down in­cre­men­tal builds as well, we saw a sim­i­lar im­prove­ment to test ex­e­cu­tion time. That means there is now less time be­tween mak­ing a change in the code, and know­ing how it af­fects our ex­ist­ing test cases. Since that’s a huge por­tion of a con­trib­u­tor’s time, im­prove­ments to in­cre­men­tal builds can be force-mul­ti­pli­ers for the en­tire pro­ject.

I was sur­prised such a sim­ple change would have such an out­sized im­pact on the de­vel­oper ex­pe­ri­ence. It felt too good to be true, so I re-ran our bench­marks to see if the change would have a neg­a­tive im­pact on Harper’s ac­tual per­for­mance. Our un­cached lint times took three per­cent longer than be­fore. I think that’s ac­cept­able.

Is there a les­son to be learned here? I think so. I im­plore you to take a half-hour this week to mess around with your com­pil­er’s set­tings. Even an im­prove­ment of a few sec­onds per it­er­a­tion can com­pound into hours of time sav­ings, both for you and your fel­low con­trib­u­tors. If you think your com­piler set­tings are al­ready per­fect, do it any­way. Your code or re­quire­ments may have changed.

This is great step in my re­cent work to make peo­ple’s first con­tri­bu­tions to Harper as fric­tion­less as pos­si­ble.

As the main­tainer of Harper, I read through dozens of is­sues and pull re­quests per day and count­less more per week. There is a con­stant flood of new prob­lems to fix and new code to re­view. At times, it can get over­whelm­ing.

I’ve been work­ing re­cently to re­duce the amount of noise I en­counter when de­ter­min­ing what to work on. I’m shar­ing my find­ings here to help other novice main­tain­ers han­dle the tor­rent. Hope­fully, there are some ideas here that you find in­sight­ful.

When your open source pro­ject gets big enough, you in­evitably hit a point where the flow of bug re­ports or fea­ture re­quests ex­pands be­yond what you’re in­di­vid­u­ally able to fix or im­ple­ment. If you’re like Jeff Geerling, this might hap­pen when you find your­self main­tain­ing a larger num­ber of pro­jects. Ei­ther way, it’s clear that there will come a time where you need to start mak­ing hard de­ci­sions on how to spend your time.

Set A Policy

Jeff’s so­lu­tion, which I’ve adopted, is to set well-de­fined poli­cies for which is­sues are al­lowed to slip through the cracks.

The strat­egy is sim­ple in essence. The main­tainer, Geerling or I in this case, di­rectly ad­dresses is­sues and PRs which are im­por­tant to the ex­ist­ing func­tion­al­ity of the soft­ware first. New fea­tures or mi­nor bugs come sec­ond. Fea­ture re­quests that help a sin­gle per­son or a bug re­ports that ad­dress a rare edge case are of low­est pri­or­ity.

If an is­sue or pull re­quest can­not be ad­dressed within 30 days of its open­ing, it is marked stale. If an­other 30 days pass be­fore it be­comes ac­tive again, it is closed. Over time, unim­por­tant top­ics are cleared away, leav­ing only the ones crit­i­cal to the pro­jec­t’s mis­sion.

A pol­icy like this sets “no” as the de­fault and helps pre­vent run­away code qual­ity de­clines. I in­sti­tuted it on Monday. If it needs re­vi­sion, I’m open to com­ments and feed­back.

Harper’s False Positives

This pol­icy stands in the face of an al­most over­whelm­ing num­ber of is­sues re­lated to false-pos­i­tives in Harper’s al­go­rithm. Here’s a rep­re­sen­ta­tive ex­am­ple.

Since these false-pos­i­tive re­ports rep­re­sent such a sig­nif­i­cant plu­ral­ity of the is­sues on GitHub, I feel the need to han­dle them sep­a­rately from every­thing else. They’re usu­ally re­solved quickly but left open out of ne­glect. They’re triv­ial enough for me to fix, but not for me to fol­low-up. Mov­ing for­ward, if any­one needs to re­port an is­sue re­lated to a false-pos­i­tive, please do so here.

Develop a Sense of Importance

There is no al­go­rithm to de­ter­mine which is­sues or PRs are the most im­por­tant to a pro­jec­t’s suc­cess. Typ­i­cally, I’ll read through five or so, and pick the one that “feels” the most im­por­tant to work on. It’s of­ten a bal­ance of pri­or­i­tiz­ing time-sen­si­tive items, items that could re­sult in pub­lic­ity, and use­ful­ness to my per­sonal work. It’s hard to put it into words, which is why it must be de­vel­oped, not taught.

What Do You Think?

I con­sider my­self a novice main­tainer, so I’d love to hear from more ma­ture main­tain­ers. How do you find sig­nal through the noise?

Additional Reading

• Why I close PRs - Jeff Geerling

For as long as I can re­mem­ber, I’ve told peo­ple that the real chal­lenge of soft­ware en­gi­neer­ing is­n’t writ­ing code. It is­n’t doc­u­men­ta­tion or CI pipelines ei­ther. No, the biggest chal­lenge in soft­ware en­gi­neer­ing is man­ag­ing com­plex­ity.

Think about it. The typ­i­cal soft­ware en­gi­neer is a sin­gle per­son on a vast team, writ­ing and edit­ing a sys­tem com­posed of hun­dreds, mil­lions, or even bil­lions of lines of code. I find that in­tim­i­dat­ing. How in the world are we sup­posed to build ro­bust and re­li­able sys­tems when fac­ing such com­plex odds?

I worry that, in my fas­ci­na­tion in the novel ap­pli­ca­tions of ma­chine learn­ing we hear about on a day-to-day ba­sis, I’ve got­ten dis­tracted from the beast of com­plex­ity. I’ve al­lowed the Harper code­base to ac­crue tech debt.

I re­cently watched DHH’s keynote from Rails World 2025. While I def­i­nitely do not agree with every­thing he has to say, I be­lieve he makes some poignant points about com­plex­ity. Some things, he says, which we con­sider nor­mal to­day would have been lu­di­crous ten years ago. Some­how, with com­puter hard­ware faster than ever, we’ve ar­rived at a point where 20 minute CI runs are ac­cept­able. Where a de­ploy to pro­duc­tion can take an hour and set­ting up a new en­vi­ron­ment can take days.

I want to change that—at least, for Harper.

While work­ing on sev­eral smaller pro­jects, I’ve been cut­ting the fat out of the Harper monorepo. That means re­mov­ing un­nec­es­sary build steps, par­al­leliz­ing in­di­vid­ual CI jobs, and re­mov­ing op­ti­miza­tion flags that don’t work.

Harper is­n’t at the 2005 stan­dard yet, but I want con­tribut­ing to be as easy as pos­si­ble. Ide­ally, it should­n’t take more than five min­utes to go from cloning the repo to com­mit­ting code. That starts with sim­pli­fy­ing the en­vi­ron­ment.

Addendum

I just came across this other blog post where they dis­cuss achiev­ing three times the per­for­mance for a quar­ter of the price by switch­ing from a com­plex AWS setup to a bare metal Hetzner server. An­other win for sim­pler sys­tems!

The biggest prob­lem with AI pro­gram­ming to­day is not what I ex­pected a few years ago. I truly did­n’t be­lieve they would be able to do any eco­nom­i­cally valu­able work.

For web de­vel­op­ment, mod­ern pro­gram­ming tools like Codex are quite good. They are able to un­der­stand a query and iden­tify the rel­e­vant ar­eas in a code­base. Then, they can make mod­i­fi­ca­tions and it­er­ate on the so­lu­tion un­til it fits the prompt. Frankly, I never ex­pected them to reach this point.

No, the pre­vail­ing prob­lem I’ve en­coun­tered with these tools is not their abil­ity to do work. Rather, the prob­lem comes from their in­abil­ity to ask ques­tions up-front and it­er­ate on their men­tal model be­fore start­ing to code.

Here’s what I mean.

Some Context

Harper’s land­ing page is pretty im­por­tant. It sets ex­pec­ta­tions for po­ten­tial users with a work­ing in-browser demo and re­duces un­pro­duc­tive traf­fic to our is­sue-tracker by an­swer­ing com­mon ques­tions. In the past, im­prov­ing the cap­i­tal-“Q” Quality of our land­ing page has had a sig­nif­i­cant im­pact on Harper’s growth rate.

What Did I Do?

Earlier this week, I wanted to make some sig­nif­i­cant changes to parts of this land­ing page. Since the com­plex­ity of this part of the code-base is rel­a­tively small, I wanted to try some­thing: a new (to me) way to work with OpenAI’s Codex.

Most of the mar­ket­ing ma­te­ri­als sur­round­ing these tools im­ply that hav­ing a con­ver­sa­tion with the “agent” is the in­tended work­flow. Sam Altman et al. make it seem like I’m sup­posed to boot up Codex and have a dis­cus­sion. At the end of that dis­cus­sion, the thing in my head is down on pa­per (or code).

I wanted to try some­thing new. In­stead of a con­ver­sa­tion, I wrote a de­tailed goal doc­u­ment. I usu­ally would­n’t do such a thing for such a triv­ial task, but as I said: this was an ex­per­i­ment.

To par­al­lel what real pro­ject doc would look like, I in­cluded what, why, and how the changes I wanted should be made. No­tably, I tried to an­tic­i­pate any pos­si­ble re­vi­sions or mis­in­ter­pre­ta­tions the agent might make, which I would later have to have a con­ver­sa­tion about. When I was done, I gave it to the agent and went to work on some­thing else. I came back an hour later, and it was done.

What’s the Big Deal?

Imagine this sit­u­a­tion. It may sound fa­mil­iar to you.

You sit down to ex­per­i­ment with an LLM. You want to see what all hype around vibe-cod­ing looks like. You tell the agent what you want. You wait a few min­utes for it to do its thing. The re­sult does­n’t look right, so you prompt it once more. You wait some more. The cy­cle con­tin­ues.

This is ex­tra­or­di­nar­ily in­ef­fi­cient. You’re cos­play­ing as a mi­cro­manag­ing boss.

If I had done used the con­ver­sa­tional mi­cro-man­ag­ing strat­egy when work­ing on the land­ing page, it prob­a­bly would have taken just as long (about an hour). The down­side, is that I don’t get to go work on some­thing else in the mean­time.

By writ­ing a plan­ning doc­u­ment for your agent, you can give your­self room to breath, sav­ing time and be­ing more pro­duc­tive as a re­sult. It’s a lot like bak­ing. You put the in­gre­di­ents to­gether, put them in the oven, then walk away and some­thing else while it cooks.

TL;DR: Get a good text ed­i­tor, and get good at us­ing it. Keep a notepad by your side. Find a quiet place to write.

Writing is one of life’s greater joys. It’s a men­tal work­out that of­ten brings me a level of clar­ity that is hard to find else­where. I have never sat down to write for an ex­tended pe­riod of time with­out com­ing away with a greater un­der­stand­ing of my­self and the uni­verse.

I imag­ine that sounds pretty cheesy.

I just want to im­press upon you the im­por­tance writ­ing has had in my life. As with any­thing this im­por­tant, I have an in­stinc­tual urge to op­ti­mize it. As soft­ware en­gi­neers, is­n’t that part of our modus operandi? To spend an un­nec­es­sary amount of time op­ti­miz­ing things?

Well, that’s ex­actly what I’ve done. Over the years, I’ve spend a un­ruly amount of time tweak­ing and chang­ing the tools I use to write. I’d love to talk about ’em.

Neovim

In the past few years, Neovim has the talk of the town. Its an­ces­tor, vi was borne from the ob­ser­va­tion that most writ­ing is re-writ­ing, and thus it in­cludes a vast ar­ray of spe­cific tools for edit­ing text, rather than writ­ing it. r/neovim has swelled to more than 110 thou­sand weekly vis­i­tors and thou­sands of plu­g­ins and LSPs to choose from.

Unless you choose a pre-built dis­tro like LazyVim, Neovim does very lit­tle out of the box. It is through re­lent­less cus­tomiza­tion that it be­comes some­thing truly pow­er­ful. Be­side the var­i­ous key­bind­ings in my con­fig, the im­por­tant plu­g­ins and tools that I use are:

Harper

As I’m the chief main­tainer, this one should be of no sur­prise. Don’t worry, I won’t give you the mar­ket­ing spiel. I’ll sim­ply say that Harper is a gram­mar checker that hap­pens to work ex­cep­tion­ally well in Neovim.

Zen Mode

Plain Neovim or­ga­nizes each file to cover the max­i­mum amount of space on-screen. Prac­ti­cally, this means most of my text ends up on the left side, which can hurt my neck. Zen mode re­stricts the width of the file and cen­ters it on the screen.

Tatum

Tatum is a small tool I wrote in a few hours that lets me live-pre­view my Markdown as HTML. I won’t re­peat my­self. If you’re cu­ri­ous about Tatum, check out my pre­vi­ous blog post.

More Details

If you’re thirsty for all the de­tails of my Neovim setup, take a quick look at the con­fig­u­ra­tion code on GitHub.

ReMarkable 2

A few years ago, while I was still in school, I splurged and pur­chased a used Remarkable 2. Even now, there is rarely a day that goes by where I don’t use it. Sure, every­thing it does could be eas­ily ap­prox­i­mated by pa­per. On the other hand, the thin de­vice saves my back when­ever I have to travel and there’s a cer­tain joy that comes from us­ing an e-ink de­vice like this.

I mostly use it to read dig­i­tal books and blog posts, but it’s also come in handy for get­ting around writer’s block. Be­ing forced to slow down and use my hand to write, rather than a key­board, is quite help­ful in some in­ex­plic­a­ble way.

A Quiet Space

More im­por­tant than any text ed­i­tor, at least for me, is a quiet space.

As I said be­fore, writ­ing can take real cog­ni­tive ef­fort. A space with dis­tract­ing noise can make it un­nec­es­sar­ily hard to get words on pa­per. I’ve found lo­cal li­braries or co-work­ing spaces to be great places for quiet au­thor­ship.

Whatever you do, do not lis­ten to mu­sic with words in it. Even if it feels more pro­duc­tive, I retroac­tively find that it makes me less so.

Conclusion

There’s prob­a­bly some more im­por­tant points I’m leav­ing out, but I def­i­nitely be­lieve I’ve hit the big three. For me, the most im­por­tant parts of a good writ­ing en­vi­ron­ment, as a soft­ware en­gi­neer, are my text ed­i­tor, a notepad, and a quiet space.

I’ve de­cided to give the Helium browser a shot. So far, I’m im­pressed!

For con­text, I’ve been an ungoogled-chromium user for the past 4-ish years. Why? I like the pri­vacy guar­an­tees. Plus, I pre­fer to use the same browser en­gine as my users.

When I heard about Helium, I was in­trigued. From what I can tell, it’s es­sen­tially a fork of ungoogled-chromium, with some bonus perks. It ships UBlock Origin out-of-the-box, which means I can keep us­ing the same great ad blocker that Google re­cently killed in its browser.

It looks great, and mi­grat­ing from Chromium was su­per easy.

SaaS prod­ucts are all the rage these days. His­tor­i­cally, Harper has po­si­tioned it­self as lo­cal-first, which many of­ten view as anti-SaaS. That is not the case.

I de­scribe Harper as “local-first” be­cause it is prin­ci­pally meant to be run lo­cally, mean­ing that your data does­n’t leave your de­vice. Pri­vacy is one of our core be­liefs, and be­ing “local-first” is part of how we honor that.

Given Harper’s po­si­tion on pri­vacy, dis­cus­sion of a cen­tral­ized ser­vice (running on a server) might seem strange. To­day, I want to ex­plain why a cen­tral­ized ser­vice is nec­es­sary, how we in­tend to tackle it as part of the open source pro­ject, and how it’s ex­is­tence will not stand to af­fect our users’ pri­vacy in any way.

Why We Need It Now

User’s de­spise false-pos­i­tives in Harper’s gram­mar en­gine.

We’ll of­ten make a mod­i­fi­ca­tion, test it as much as pos­si­ble in­ter­nally, and re­lease it, only for a user to dis­cover false-pos­i­tives on their col­lege es­say. We’ve sig­nif­i­cantly re­duced their fre­quency through tech­niques like LLM-Assisted Fuzzing and ar­ti­fi­cial se­lec­tion, but they per­sist.

Far and wide, most of the time be­tween when we get a bug re­port and when we get a fix into pro­duc­tion is spent do­ing mean­ing­less “paperwork”. Reading through is­sues, writ­ing boil­er­plate code for tests, and prepar­ing pull re­quests take up a lot of time. I want to up­end this en­tire loop and find a sim­pler way to it­er­ate on false-pos­i­tives.

The first step in this process is re­duc­ing the over­head for users to re­port them in the first place. In­stead of fil­ing an is­sue, I’d love for user’s to be able to push a but­ton have have all rel­e­vant con­text sent di­rectly to our in­boxes. Not GitHub ac­count re­quired, no fuss.

Obviously, we won’t be send­ing any in­for­ma­tion with­out clearly dis­clos­ing the pre­cise data be­ing sent from the client.

Since these re­ports will be in a struc­tured for­mat, we can bun­dle fixes into larger batches, re­duc­ing over­head (and po­ten­tially mak­ing things eas­ier for LLMs). The Harper pro­jec­t’s abil­ity to con­tin­u­ously and sur­gi­cally im­prove our ser­vice is part of what sets us apart from our com­peti­tors. It’s rare for user feed­back to have such a di­rect im­pact on Grammarly’s core en­gine.

This is just the start. Once we’ve proven that we can main­tain such a sys­tem for our users, we will move on to more am­bi­tious goals.

How We Plan to Make It Happen

I’ve had suc­cess with these tech­nolo­gies in the past, and be­lieve they’ll work quite well for our ini­tial use-case, and scale quite nicely as the ser­vice be­comes more ca­pa­ble.

SvelteKit

Harper’s web­site is al­ready built us­ing SvelteKit. It works. Why mess with suc­cess?

Database: SQLite with Drizzle

On mod­ern hard­ware, SQLite can han­dle tens of thou­sands of trans­ac­tions per sec­ond. Since Harper (as a rule) will place lit­tle load on the ser­vice per-user, I ex­pect SQLite can ser­vice our needs for a long time. When that time ex­pires, Drizzle (an ORM) makes it triv­ial to move to a more ro­bust data­base down the road (I imag­ine PostgreSQL).

For the mo­ment, it­er­a­tion speed is para­mount. I want to move fast. To that end, James and I have dis­cussed host­ing every­thing on a small VPS, and we agree it’s the best choice.

Auth.JS

Authentication is not some­thing any­one should roll on their own. Auth.JS is a proven so­lu­tion that bun­dles well with Drizzle to build­ing out user pro­files, au­then­ti­ca­tion pages, and every­thing in-be­tween. The needs of the pro­ject won’t ne­ces­si­tate this right away. When the time comes, us­ing Auth.JS (from my ex­pe­ri­ence) will shorten the auth prob­lem down from weeks to just hours.

The Future

I’m thrilled that we’re fi­nally mov­ing in this di­rec­tion. Be­ing lo­cal-only has taken us far, but loos­en­ing the reigns to be more sim­ply “local-first” will al­low us to tackle more in­ter­est­ing prob­lems and pro­vide more value to our users. I can’t wait to get started.

The most com­mon com­plaint I’ve been hear­ing as of late re­lates to Harper’s per­for­mance. I’ve been told that Harper has got­ten slow.

I was puz­zled. Nothing had sub­stan­tially changed in our core en­gine that could have made it slower. Our bench­marks had­n’t shown any slow-downs. What could be prompt­ing users to com­plain about per­for­mance?

The prob­lem was clearly in the Chrome ex­ten­sion. Those who com­plained were do­ing so with screen­shots from Notion or Ghost. Could re­cent de­vel­op­ments in the WebAssembly ecosys­tem be the cause? Nope. Could it have some­thing to do with the kinds of ap­pli­ca­tions users were try­ing to use with Harper? Nope. The com­plaints seemed un­teth­ered to a spe­cific do­main or pro­gram. What could be slow­ing our users’ down?

The Problem

As it turns out, the prob­lem was­n’t the ac­tual gram­mar check­ing, it was ren­der­ing the high­lights on the page.

The Chrome ex­ten­sion’s hot path looks some­thing like this:

1. Extract the text from the page
2. Run harper-core (the gram­mar en­gine) over it to find mis­takes
3. Use DOM APIs to com­pute the bound­ing boxes of those mis­takes on the page. This is im­por­tant: This com­pu­ta­tion re­quires the browser to re­flow the lay­out of the page.
4. Render ad­di­tional DOM el­e­ments to the screen over these bound­ing boxes. This also re­quires the browser to re­flow the lay­out of the page.

Requiring the browser to lay out the page more than once per frame is called “layout thrash”, and it’s con­sid­ered bad prac­tice for per­for­mance rea­sons. It causes more CPU us­age than oth­er­wise, which can slow down com­plex web­sites and re­duce bat­tery life. It is­n’t no­tice­able for newer com­put­ers (4 years old), but it can be quite jar­ring for older lap­tops.

The Solution

Fortunately, there’s a so­lu­tion. Just re­cently, W3C stan­dard­ized The Custom Highlight API, which al­lows us to ren­der high­lights with­out in­ter­act­ing with the DOM at all. This saves us two full lay­out re­freshes and al­lows the browser to of­fload more work to the GPU, sav­ing CPU cy­cles and bat­tery life.

It’s not all roses and rain­bows. For one, we can only use this op­ti­miza­tion for text ed­i­tors that use contenteditable el­e­ments. It does­n’t help for <textarea /> or <input /> el­e­ments. Firefox also does­n’t sup­port this part of the API, which means we have to fall back to the old high­lighted ren­derer on Gecko-based browsers.

There are also some mi­nor dif­fer­ences be­tween how the new ren­derer and the old ren­derer style their high­lights. This is be­cause high­lights us­ing the Custom Highlight API can’t be styled us­ing any old CSS, but rather a sub­set.

The ini­tial goal of any green­field pro­ject of mine is to build a work­ing demo. If pos­si­ble, that demo should run on the web, so I can dis­trib­ute to friends and fam­ily.

One of my first posts to hit the front-page of Hacker News rep­re­sented ex­actly this phi­los­o­phy. At the time, I was in high-school, tak­ing an in­de­pen­dent lin­ear al­ge­bra class. I wanted to demon­strate ex­actly how the things I was learn­ing could be ap­plied to real-world prob­lems. My blog post, “Markov Chains are the Original Language Models” in­cluded an in­ter­ac­tive (small) lan­guage model that read­ers could use to gen­er­ate mean­ing­less text. I gave them the abil­ity to toy around with the train­ing data to see how it could af­fect the fi­nal mod­el’s gen­er­a­tions.

I ended up get­ting an “A” in the class and a cou­ple thou­sand hits on­line. More im­por­tantly, I had proven the util­ity of a demo. Since then, every ma­jor pro­ject of mine has had some kind of demo. Some of them bet­ter than oth­ers.

The Harper demo, in par­tic­u­lar, was rough to start. It was enough to prove the con­cept and es­tab­lish the pro­ject within a cer­tain ecosys­tem, but it far from per­fect. It had bugs and, un­til now, has­n’t evolved with the pro­ject at all.

For all my pro­jects though, I see the ini­tial demo as crit­i­cal. Beyond prov­ing the con­cept, the demo gives me an enor­mous amount of mo­ti­va­tion. As an en­gi­neer, there are few things more thrilling than to watch some­one toy around with the prod­uct of your work. When there’s a live ver­sion of your prod­uct avail­able, any in­cre­men­tal im­prove­ment comes with a hit of dopamine.

I had a great dis­cus­sion with Adam Zielinski a few weeks ago, when he en­cour­aged me to make the demo on the Harper web­site as close to the ac­tual Harper ex­pe­ri­ence as pos­si­ble. Last week, I did ex­actly that.

Actually, I did more than that. Today, the demo is­n’t just sim­i­lar to the ex­pe­ri­ence of us­ing our Chrome ex­ten­sion, it is ex­actly the same. The DOM-inspecting and ma­nip­u­lat­ing tech­nol­ogy found in the Chrome ex­ten­sion can now be em­bed­ded in any page. That in­cludes the ac­tual Harper web­site, and any other site you might want.

For now, I’m call­ing this the lint-framework, and it opens the doors to a good many other in­te­gra­tions (should we de­cide to build them). It is es­sen­tially a portable pack­age that in­cludes pretty much every­thing you need to pro­vide Harper to any browser-based text ed­i­tor.

Many ap­pli­ca­tions al­low users to build plu­g­ins into their WebView, but don’t pro­vide the full web ex­ten­sion API (Thunderbird, for ex­am­ple). In these cases, we can pull in the lint-framework and wire up the na­tive plu­gin APIs to build con­fig­u­ra­tion pages. It is­n’t a com­plete so­lu­tion, but it cuts down the work and main­te­nance over­head enor­mously.

As it turns out, the cruft of Harper’s demo was a ma­jor bar­rier to adop­tion. Since pol­ish­ing it up late last week, we’re al­ready see­ing met­rics like bounce rate move in a pos­i­tive di­rec­tion.

Today marks the end of my first week in New York City. It is an ex­cep­tion­ally ac­tive place. Neither the hus­tle nor the bus­tle ever stops. Sirens sound at all hours of the day and you’re con­stantly smelling en­tirely new things. I’ve been told New York is an ac­quired taste. I can see why they might say that.

Back home, it’s rare I would walk down the street and over­hear a ran­dom founder talk about their lat­est Y Combinator fund­ing round. Here, it’s ap­par­ently com­mon enough to oc­cur at least once a week. Everywhere I look, I find the head­quar­ters of multi­na­tional com­pa­nies and the of­fices of ma­jor gov­ern­men­tal or­ga­ni­za­tions.

The City is Practical

If I were to de­scribe Portland, Oregon (which I vis­ited a few weeks ago to at­tend WordCamp US) in one word, it would be op­ti­mistic. If I were to de­scribe New York in one word, based on my in­cred­i­bly lim­ited ex­pe­ri­ence thus far, it would be prac­ti­cal.

The city and the peo­ple who re­side in­side take very lit­tle fluff. They say things as they are, in the kind­est way pos­si­ble. If they don’t think your pro­posed route to a restau­rant will work, they stop you be­fore you fin­ish ex­plain­ing and put you on the right track. It saves every­one time and en­ergy.

This is some­thing I per­son­ally need to prac­tice more of­ten in my work. It is com­mon for me to avoid pro­duc­tive con­ver­sa­tions or code re­views, only be­cause they might evoke a neg­a­tive emo­tion in the short-term. These same con­ver­sa­tions usu­ally pro­duce pos­i­tive emo­tions in the long term, so it is in my in­ter­est and in my col­league’s in­ter­est to have them. NYC is slowly train­ing a habit to rec­og­nize these sit­u­a­tions more of­ten and make the right de­ci­sion.

I don’t think I’m alone here. I think a plu­ral­ity of peo­ple in the mod­ern world could ben­e­fit from a bolder mind­set that takes on tough con­ver­sa­tions, rather than shy­ing away.

We’re Not Done Yet

I’ll be in New York for an­other week. If all goes well, I’ll have more op­por­tu­ni­ties to learn from the other mem­bers of the AI group. It’s been great to hang out with James and the gang. The cul­ture here is in­cred­i­bly invit­ing. I am im­mensely grate­ful to be here.

Several months ago, I an­nounced the ini­tial ver­sion of the Harper WordPress plu­gin. In the in­ter­est of those still us­ing it, I’d like to give y’all an up­date.

The Chrome ex­ten­sion is now the rec­om­mended way to use Harper in WordPress. There are sev­eral com­pound­ing rea­sons for this. Most im­por­tantly, it­er­at­ing on a Chrome ex­ten­sion is sig­nif­i­cantly faster than the re­view process for WordPress.com plu­g­ins. In fact, the cur­rent WordPress.com Harper plu­gin, which you may al­ready be us­ing in your P2s, is cur­rently sev­eral months out-of-date. While you may con­tinue to use the WordPress plu­gin, it will no longer re­ceive reg­u­lar up­dates.

If you choose to switch to the Chrome ex­ten­sion, I think you’ll find the ex­pe­ri­ence more holis­tic, since it is able to per­sist user data across sites.

I had the in­cred­i­ble op­por­tu­nity to speak at WordCamp U.S. at Matt’s sug­ges­tion. I met a num­ber of won­der­ful, kind, and invit­ing peo­ple. It was my first WordCamp and first con­fer­ence talk, so I was nat­u­rally ner­vous. The com­mu­nity made it feel easy.

I spoke about how we can use ma­chine learn­ing to im­prove the qual­ity of our ap­pli­ca­tions with­out big cap­i­tal ex­pen­di­tures. In fact, I ar­gue that cap­i­tal ex­pen­di­tures are of­ten a step in the wrong di­rec­tion.

Fun fact: This talk started out as a blog post.

Whenever I can, I try to stop and re­flect. Of­ten it’s about my work and the things I can do to con­tinue be­ing more pro­duc­tive. But of­ten, I re­flect about the re­cent books I have read and the things I (and you) can learn from them. That’s what this post will hope­fully turn out to be.

So, with­out fur­ther ado, here are some of the books I have read re­cently.

The Stoic Challenge by William B. Irvine

At the end of each episode of his pod­cast, Ezra Klein asks his guests the same ques­tion: what three books would you rec­om­mend we read? Terminating one par­tic­u­lar episode, au­thor Jonathan Haidt sug­gests The Stoic Challenge.

I was al­ready aware of William B. Irvine as a pro­lific stoic writer. In fact, I had tried to read an­other of his books on the sub­ject of Stoic phi­los­o­phy. I had not fin­ished it be­cause, well, I found it some­what dry.

The Stoic Challenge, on the other hand, was a de­light. It feels like Irvine took all the suc­cess­ful parts of the pre­vi­ous book and con­densed them down into some­thing my Gen-Z brain could un­der­stand.

The book’s more im­por­tant take­away is sim­ple. In life, you and I both en­counter daily strug­gles that im­pede our progress to­ward our goals.

Our flight is run­ning late, so we get to our ho­tel later than we in­tend. We for­get to pack a lunch, so we must get through our work­day hun­gry. Our babysit­ter wants a raise, which means we won’t be able to go out as of­ten.

The Stoic Challenge en­cour­ages us to frame these set­backs as a test. A test put upon us by some hid­den force. To pass the test, we need to act in a ra­tio­nal way, and take steps to avoid ex­ac­er­bat­ing the re­sult­ing neg­a­tive emo­tions.

I highly sug­gest any­one read this book. I felt en­gaged the en­tire time read­ing it, and its lessons ap­ply to any walk of life.

Slow Productivity by Cal Newport

Cal Newport is known for many of the most ground­break­ing pro­duc­tiv­ity books of the last decade. Per­son­ally, Deep Work and How to Be a Straight-A Student have been par­tic­u­larly im­pact­ful. They’ve en­cour­aged me to cut out the un­nec­es­sar­ily com­plex parts of my work­ing life, and work to find ways of do­ing the same for oth­ers.

His lat­est work con­tin­ues from the same ideas he put forth in those books.

How to be a Straight-A Student was fo­cused on the idea that the quan­tity of high-qual­ity, pub­lished work made the dif­fer­ence be­tween mediocre and stel­lar aca­d­e­mic ca­reers. Fol­low­ing on, Deep Work made the case that the best way to achieve high out­put was by cre­at­ing cir­cum­stances that al­lowed for ex­tended pe­ri­ods of in­tense fo­cus.

Slow Productivity takes both of those ideas a step fur­ther. He sug­gests that the key to high-qual­ity out­put, in ad­di­tion to deep fo­cus, re­quires time. He be­lieve that truly amaz­ing prod­ucts re­quire the brain to be re­laxed, com­fort­able, and un­hur­ried. It is only then, that it can work out­side of the box.

I’m not en­tirely sure I agree, but the book made for a stim­u­lat­ing read nonethe­less.

The Humans by Matt Haig

The Humans is a beau­ti­ful book that cel­e­brates all the idio­syn­cratic things that make hu­mans spe­cial. Don’t worry, I won’t spoil it for you I’ve read a de­cent num­ber of Haig’s books in the past, and I’ve en­joyed each one. This was no dif­fer­ent.

I’ll spare you the de­tails.

The 22 Immutable Laws of Marketing

I am an en­gi­neer. I went to an en­gi­neer­ing school. Since I spend most of my time around peo­ple who work in fields re­lated to en­gi­neer­ing, I do not spend much time around peo­ple who know a lot about mar­ket­ing. I wanted to fix that. Which is why I read The 22 Immutable Laws of Marketing.

This is a book in­tended for peo­ple who want to un­der­stand the ax­ioms of how brands are per­ceived by the pub­lic.

Sapiens by Yuval Noah Harari

Sapiens is a com­pre­hen­sive his­tory of our species, homo sapi­ens, be­gin­ning with the first hu­mans to walk the planet all the way up to the hu­mans of to­day. Harari takes a unique look at what makes our species spe­cial, and the things that make our fu­ture un­cer­tain.

At times, the writ­ing can be a bit dry and repet­i­tive, but on the whole it is a well-writ­ten book. I would cer­tainly rec­om­mend it for any­one who seeks an en­tirely new per­spec­tive on the short his­tory of hu­man life.

Your Utopia by Bora Chung

I went into Your Utopia ex­pect­ing a col­lec­tion of short sto­ries sim­i­lar to those by Ted Chiang. That is not what I re­ceived.

Instead, Chung pro­vides a some­what eclec­tic col­lec­tion of sto­ries that feel not un­like a fever dream. Rather than gen­uine, hard sci­ence fic­tion, Chung tells the tales of sen­tient cars, el­e­va­tors that care for the el­derly, and im­mor­tal sec­re­taries.

I don’t re­gret read­ing it, but I also don’t rec­om­mend it to fans of Chiang.

I want you to read that ti­tle as lit­er­ally as pos­si­ble. Harper is now ca­pa­ble of evo­lu­tion.

This past week, I’ve been work­ing on a sys­tem that should al­low us to han­dle more com­plex gram­mat­i­cal cases and con­texts, faster. I be­lieve it will im­prove our abil­ity to add new gram­mat­i­cal rules to Harper by some­where be­tween 500% and 1,000%.

To top it off, this sys­tem does it with­out slow­ing Harper it­self down or in­creas­ing the mem­ory foot­print.

Let’s get into it.

The Problem

There are sev­eral unique method­olo­gies at play when Harper goes about gram­mar check­ing. Which strat­egy de­pends on the gram­mat­i­cal rule in ques­tion. To­day, we’re in­ter­ested in ex­pres­sion rules.

For the cu­ri­ous, I have re­cently writ­ten a re­flec­tion on ex­pres­sion rules, as well as a guide for any­one in­ter­ested in pro­duc­ing them. This post, how­ever, will not re­count in­for­ma­tion I’ve al­ready writ­ten on this blog.

By count, ex­pres­sion rules make up the ma­jor­ity of gram­mat­i­cal rules Harper is cur­rently ca­pa­ble of de­tect­ing. This is be­cause they are fast, easy to write, and most im­por­tantly, easy to re­view.

There are, how­ever, oc­ca­sional hic­cups that I en­counter when tack­ling a prob­lem. The English lan­guage is tricky and of­ten it con­tra­dicts it­self. I will of­ten try to write a rule which cov­ers a cer­tain case, only to find that it does­n’t cover all cases. I can it­er­ate, but it of­ten be­comes te­dious and time-con­sum­ing.

The Solution

Last week, I threw in the towel. I was tired of it­er­at­ing cease­lessly to­wards a goal, only to have a new one to tackle af­ter that. So I de­cided I would let the com­puter it­er­ate for me.

Harper’s ex­pres­sions are es­sen­tially small pro­grams which are able to iden­tify the lo­ca­tions of given pat­terns in nat­ural lan­guage. They are con­structed at run­time, but they run ex­ceed­ingly fast be­cause they tend to be amenable to mod­ern branch pre­dic­tion. We can use this fact to our ad­van­tage.

When gen­er­at­ing an ex­pres­sion that de­tects a par­tic­u­lar gram­mat­i­cal rule, the new sys­tem (which I’ve called The Ripper) fol­lows three steps.

1. Generate N ran­dom Harper ex­pres­sions
2. Score the per­for­mance of these ex­pres­sions by test­ing them against a cu­rated dataset. The dataset con­tains la­beled rows of sen­tences that do and do not con­tain the gram­mat­i­cal rule of in­ter­est.
3. Take the best K ex­pres­sions and mu­tate them to left with L new “child” ex­pres­sions. Go to step 2.

That’s it! We’re es­sen­tially treat­ing ex­pres­sions as liv­ing crea­tures and sub­ject­ing them to ar­ti­fi­cial se­lec­tion. It works re­mark­ably well.

Since these datasets are hand­crafted (or gen­er­ated by an LLM), they don’t need to be large. Plus, the ex­pres­sions them­selves are quite fast to gen­er­ate and test, so we can do so at an ex­cep­tional rate.

My lap­top is able to churn through about 90 thou­sand can­di­dates per sec­ond, al­low­ing us to con­verge on an ac­cept­able re­sult in just a few min­utes. Given more time, it’s able to pro­duce an ex­pres­sion rule that is more ac­cu­rate than what I could write my­self.

What’s Next?

I in­tend to spend some time op­ti­miz­ing the process, par­tic­u­lar for the hu­man el­e­ment. I’d like to be able to cre­ate batches of these datasets and let The Ripper take care of them all at once, overnight or on a beefy server in the cloud.

I’d also like to set up au­to­mated work­flows for pip­ing data from an LLM di­rectly into the Ripper. Ideally, I want this sys­tem to get to a point where I can feed in­for­ma­tion from a style guide into an LLM and get a guar­an­teed func­tion­ing Harper ex­pres­sion rule out of it.

I’ve given dozens of talks over the years, yet I still feel like I have much to learn about pub­lic speak­ing. The act of pre­sent­ing an idea to a large au­di­ence in per­son is in­tim­i­dat­ing for me, as I imag­ine it is for most peo­ple.

Preparing for my up­com­ing talk at WordCamp US has me stop­ping to re­flect on what I al­ready know. To re­call the ba­sic prin­ci­ples that turn a good talk into great one.

Conveying an idea ef­fec­tively is a pow­er­ful skill. It can help get peo­ple on your side and di­rect them to your point of view. Hu­mans are be­ings that thrive when they build and main­tain strong re­la­tion­ships with each other. Good com­mu­ni­ca­tion su­per­charges that process.

Here are my bold ideas for how to pre­sent ideas well, in no par­tic­u­lar or­der.

Convey Exactly One Idea At a Time

A com­mon prob­lem peo­ple run into when they draft a pre­sen­ta­tion is not a lack of ideas: It is that they have too many.

People adore talk­ing about them­selves or their ideas. A nat­ural con­se­quence is that peo­ple have a predilec­tion to stuff a pre­sen­ta­tion with more in­for­ma­tion than they need to make their point. Make sure to al­lo­cate time to take stuff out.

The more stream­lined and clear you make your point, the more re­cep­tive your au­di­ence will be.

Use a Story

The hu­man brain is wired for sto­ries. We’ve been telling them for thou­sands of years. Peo­ple re­mem­ber them far bet­ter than they do ar­bi­trary in­for­ma­tion. In fact, that is ex­actly how com­mu­ni­ties used to do record­keep­ing: by telling sto­ries.

By weav­ing a tale into your pre­sen­ta­tion, you can prime the au­di­ence to re­ceive your idea, and make that idea more mem­o­rable.

Explain the “Why”

The “Why” should be the first thing your au­di­ence hears from you. Why they should lis­ten. Why your idea is im­por­tant. Why your in­put can help them in their pro­fes­sional or per­sonal lives.

Chris Anderson, the Head of TED, says, “Style with­out sub­stance is aw­ful”.

In other words, you can have the fan­ci­est, most vi­su­ally ap­peal­ing slide deck and all the con­fi­dence in the world, and you can still have a mediocre pre­sen­ta­tion. Find a topic or idea that you gen­uinely care about, and ex­plain why the au­di­ence should care about it too.

The biggest com­plaint about Harper is that the qual­ity of gram­mar check­ing still needs some work. I’ve got an ex­cit­ing new pro­ject I’m prepar­ing to dis­cuss later this week (hopefully) in that area. It should be a step-func­tion im­prove­ment over our pre­vi­ous meth­ods for cre­at­ing new rules.

In the mean­time, I’ve col­lected some re­cent sight­ings of Harper in the wild:

• Obsidian Rocks
• We Are Founders
• It’s FOSS
• XDA Developers
• Make Tech Easier

Grammar check­ing can be cum­ber­some, es­pe­cially when its sloth gets in the way of your think­ing. That’s part of why so many pre­fer Harper over Grammarly or LanguageTool. Waiting four sec­onds per edit can add up over long days of writ­ing.

But there’s some­thing else that can slow peo­ple down, es­pe­cially power users. It’s the mouse. Moving one’s hand to the point­ing de­vice, mov­ing it, and click­ing can take a while—and that adds up too.

Neovim (and sim­i­lar text ed­i­tors like Obsidian) solve this prob­lem by us­ing an­other in­put de­vice: the key­board. Since you’re us­ing the key­board to write words to the page, why not also use it to cor­rect gram­mat­i­cal mis­takes?

In the lat­est re­lease of Harper’s Chrome ex­ten­sion, that’s ex­actly what I’ve added. While writ­ing, you’re bound to make (at the very least) a few ty­pos. If that’s the case, you can now dou­ble-tap the shift key to open the sug­ges­tion popup from the er­ror clos­est to your caret. From there, you can use tab and en­ter to se­lect and ap­ply a cor­rec­tion.

I’ve per­son­ally found that this sin­gle-hand­edly speeds up my writ­ing process by at least 20%. I’m able to fo­cus less on each word and more on the con­tent.

I was re­cently en­cour­aged to sub­mit a talk pro­posal to the AI track at WordCamp US. I was more than happy to oblige, and to my sur­prise, I got in. See de­scrip­tion be­low for de­tails. I hope to see some of y’all there!

Description

Machine learn­ing has been around for decades. Un­til re­cently, run­ning ML mod­els typ­i­cally re­quired big cen­tral­ized servers due to high com­pu­ta­tional de­mands. With mod­ern hard­ware and tools like Rust and Burn, we can flip the script. When run on a user’s de­vice, trained mod­els can be an in­cred­i­ble boost to hu­man cre­ativ­ity and ex­pres­sion.

Harper is a gram­mar checker that is de­signed to im­prove your work with­out de­grad­ing your in­tegrity—or the writ­ing ex­pe­ri­ence it­self. Our users gen­er­ate and pub­lish novel ideas faster be­cause we fo­cus on what’s im­por­tant: speed, pri­vacy, and ac­cu­racy.

WordPress’ mis­sion is to de­moc­ra­tize pub­lish­ing. This talk will ex­plore how we can use AI to de­moc­ra­tize writ­ing too. More im­por­tantly, how you can train and de­ploy spe­cial­ized mod­els at the edge to elim­i­nate in­fer­ence costs, lower la­tency, and im­prove user sat­is­fac­tion.

Each week I sit down and re­flect on what I’ve learned. I think about which of my ef­forts have helped the Harper en­deavor, and which have harmed it. It’s not easy, but I think it’s one of the best habits I’ve built. More ac­cu­rately, it’s one of the best habits Matt has en­cour­aged me to build.

When I re­ally think about it, I’m re­minded of the orig­i­nal After the Deadline blog, which co­in­ci­den­tally also had a cat­e­gory called “Talking to Myself”. I won­der if Raphael Mudge (AtD’s au­thor) had a sim­i­lar mo­ti­va­tion.

I talk to my­self to find the weak­nesses in Harper’s mis­sion and fo­cus my at­ten­tion on what mat­ters. It is an ef­fi­cient way to get from layer one to layer five. It can help get other main­tain­ers on the same page and build a body of knowl­edge that can be linked to from any­where.

Not wor­ry­ing about keep­ing in­for­ma­tion locked-down is one of the more beau­ti­ful parts of work­ing in pub­lic. Open source code would be noth­ing with­out sim­i­larly open source knowl­edge. I talk to my­self on­line so my users can un­der­stand my in­ten­tions.

In many senses, we are not un­like moths. We are drawn to the lights of dis­trac­tion, hype, and pro­cras­ti­na­tion. For me, set­ting up check­points to stop and re­flect has been an ef­fec­tive de­ter­rent from these lights. In fact, I think each minute for which I stop and think has paid it­self back three times over in time sav­ings. If I can bet­ter al­lo­cate my time and en­ergy, I can avoid do­ing re­dun­dant work pur­su­ing point­less goals.

Bonus Points

A few of my ar­ti­cles have be­come pop­u­lar on sites like Hacker News and Reddit. We’ve got­ten quite a few Harper in­stal­la­tions from links on these ar­ti­cles. I would never rely on this kind of blog­ging as a source of ad­ver­tis­ing, but it is nice to see it help spread the word.

Just like gram­mar it­self, Harper is rule-based. These rules can be writ­ten by hu­man or ma­chine, and usu­ally take the form of a “phrase cor­rec­tion” or an ex­pres­sion rule. You can read more about both in my guide.

In essence, an ex­pres­sion rule is a small, de­clar­a­tive pro­gram that seeks out spe­cific cases Harper can be cer­tain are gram­mat­i­cally in­cor­rect. For ex­am­ple, we know re­dun­dant modal verbs are al­ways wrong:

We could give it try attempt.

What’s Great About Expression Rules

As the main­tainer of the pro­ject, I need to read through a de­cent num­ber of pull re­quests each week. De­pend­ing on their com­plex­ity, this can be time con­sum­ing. Be­cause ex­pres­sions are al­most al­ways writ­ten with the same five prim­i­tives, they make re­views way faster. For many rules, I only need a quick skim of the code and to con­firm they don’t cre­ate false-pos­i­tives.

In ad­di­tion to ty­pos, the prim­i­tives un­der­ly­ing ex­pres­sion rules were de­signed to check agree­ment and word-or­der­ing er­rors. To that end, there are a num­ber of as­sump­tions baked in. This makes some kinds of rules harder to write, but also makes all ex­pres­sion rules ex­ceed­ingly easy to mem­o­ize.

What’s Not-So-Great About Expression Rules

As I said be­fore, ex­pres­sion rules were de­signed for a cer­tain kind of er­ror. There are many gram­mat­i­cal or lay­out rules which hard dif­fi­cult or down­right im­pos­si­ble to de­fine with an ex­pres­sion.

This nor­mally is­n’t prob­lem, since we can go about them in other ways. On mul­ti­ple oc­ca­sions, how­ever, I’ve seen po­ten­tial con­trib­u­tors get frus­trated at a per­ceived lack of flex­i­bil­ity. We did­n’t make it clear enough that there were so­lu­tions other than ex­pres­sions.

How Can We Improve?

Applying Amdahl’s law, I think the most ef­fec­tive so­lu­tion is to im­prove our doc­u­men­ta­tion, as I have been for the last week or so.

Beyond that, re­mov­ing the need for boil­er­plate code and other causes of men­tal over­head (like reg­is­ter­ing our rules and wait­ing for a slow com­pi­la­tion process) might lower the per­ceived dif­fi­culty of writ­ing new rules.

In a pre­vi­ous post, I de­tailed how I im­ple­mented a ba­sic nom­i­nal phrase chun­ker us­ing Transformation-based learn­ing (not to be con­fused with the trans­former class of neural net­work mod­els). Since then, I’ve taken an­other crack at the prob­lem. My main goal: im­prove the ac­cu­racy. The end re­sult is a portable neural net­work model that achieves ~95% ac­cu­racy on gram­mat­i­cally cor­rect text when tasked with iden­ti­fy­ing the nom­i­nal phrases in text.

Our Goal

We want Harper to be able to match against sub­jects and ob­jects in sen­tences. This is a pre­req­ui­site for check­ing a di­verse ar­ray of gram­mat­i­cal rules. For ex­am­ple, to catch the er­ror in this sen­tence, we need to cor­rectly iden­tify which to­kens rep­re­sent our sub­ject.

Neither of the big blue bottle would be broken by the fall.

In this case, our user has ac­ci­den­tally made the sub­ject sin­gu­lar, while the verb “neither” im­plies that the sub­ject should be plural. We call this an agree­ment er­ror. Be­cause our sub­ject, “big blue bot­tle” con­tains mul­ti­ple to­kens, we need a way to iden­tify sub­jects at a higher level than per-to­ken. That is what a chun­ker does.

The Failures of the Brill Chunker

The Brill chun­ker was by many ac­counts a suc­cess. It was­n’t, how­ever, a suc­cess in the main way that mat­tered: It was­n’t re­li­able enough to be used in Harper’s gram­mat­i­cal rule sys­tem. While fast and small, it failed to catch most edge-cases in English text. In some senses, it over­fit its train­ing dataset.

Why Train Our Own?

As our needs con­tinue to ex­pand along­side our user-base, I need the chun­ker to be flex­i­ble. If its needed ca­pa­bil­i­ties ex­pand, I need to be able to re­train the model to meet them. That would not be pos­si­ble with­out hav­ing a deep un­der­stand­ing of how the sys­tem works.

Building a Neural Net

To build a new chun­ker, I just needed to im­ple­ment the Harper Chunker trait. Easy enough.

/// An implementer of this trait is capable of identifying the noun phrases in a provided sentence.
pub trait Chunker {
    /// Iterate over the sentence, identifying the noun phrases contained within.
    /// A token marked `true` is a component of a noun phrase.
    /// A token marked `false` is not.
    fn chunk_sentence(&self, sentence: &[String], tags: &[Option<UPOS>]) -> Vec<bool>;
}

For the nerds in the crowd, I de­cided to use a Word + POS embedding -> BiLSTM -> Linear ar­chi­tec­ture. To keep things portable and con­sis­tent with the rest of the Harper code­base, I used Burn, a Rust-native ma­chine learn­ing toolkit. While I be­lieve the BiLSTM to be good enough for this ap­pli­ca­tion, one ad­van­tage of Burn is the abil­ity to eas­ily swap it out for a trans­former if the need arises. It also makes it un­be­liev­ably easy to quan­tize mod­els.

This ar­chi­tec­ture gives us some hy­per­pa­ra­me­ters to tune against. Af­ter dozens of train­ing runs of ex­per­i­men­ta­tion, these worked best:

What’s Next?

Similar to the Brill Chunker, I’ll be try­ing to use this new sys­tem in our gram­mar checker. From there, I’ll know what ad­di­tional in­for­ma­tion we’d like for it to in­fer. Once I’ve got­ten it to re­li­ably work for >= 3 rules, I’ll de­clare it ready to merge.

Update as of December 2025

I to­tally for­got to up­date this post. I sup­pose it is bet­ter late than never. Back in August I ac­tu­ally ended up giv­ing a talk about our chun­ker at WordCamp U.S. It was a great ex­pe­ri­ence, and I highly sug­gest you go watch it if you find this stuff in­ter­est­ing.

I be­lieve that good doc­u­men­ta­tion is more im­por­tant than ever. In an age where large lan­guage mod­els have ex­cep­tional con­text win­dows, it’s easy to fall into the trap of be­liev­ing a sys­tem is sim­pler than it is. To test the lim­its of their abil­i­ties, I’ll of­ten feed Harper code in and ask for their ex­pla­na­tion of it’s in­ner work­ings. They’ve never got­ten it any­where close to cor­rect.

That’s be­cause good doc­u­men­ta­tion is more than the sum of its parts. It should con­tain all the rel­e­vant tech­ni­cal de­tails needed to work on a repos­i­tory, but it should also pro­vide a sense of qual­ity and di­rec­tion. It should dis­till an abil­ity within the reader to tell what good code and con­duct looks like.

I think this is an area Harper could do to im­prove on.

It’s Possible to Write Too Much

Too much text can be over­whelm­ing. I have met many peo­ple (myself in­cluded) who be­lieve that more de­tail is al­ways bet­ter. That as long as the in­for­ma­tion ex­ists some­where, some­one will be able to find it. In re­al­ity, that’s just not true.

That brings us to our first rule: good doc­u­men­ta­tion should be sim­ple.

The worst way to de­scribe a com­plex sys­tem is with com­plex lan­guage. It’s much bet­ter to first break it down into sim­pler parts. From there, you can build it back up again.

I’ve found it ef­fec­tive to start by erring on the side of “too much”, only to pare it down later.

Needless to say, it’s also pos­si­ble to write too lit­tle.

Focus on Why

The code it­self is (or should be) the best de­scrip­tion of how the soft­ware works. Doc­u­men­ta­tion should com­ple­ment this re­al­ity by de­scrib­ing why the soft­ware works that way.

This might in­clude a lit­tle his­tory. What steps did the orig­i­nal code’s au­thor take be­fore ar­riv­ing on the fi­nal so­lu­tion? A blog is a great way to an­swer that ques­tion.

When de­scrib­ing a bug rel­e­vant to some code (like in a pull re­quest), a pic­ture is worth a thou­sand words. It’s much eas­ier to show a prob­lem than to de­scribe it. That’s why I highly sug­gest you take a screen­shot of the prob­lem. Even bet­ter: record a video recre­ation of it.

Harper is a gram­mar checker that re­lies on con­crete, leg­i­ble gram­mat­i­cal rules. In do­ing so, we make Harper’s in­ner-work­ings fun­da­men­tally clear, which al­lows us to guar­an­tee pri­vacy, speed, and most im­por­tantly re­main im­par­tial.

Writing ad­di­tional rules is one of the best (and eas­i­est) ways you can con­tribute to the open source pro­ject. Sim­ple rules take just a few min­utes and of­ten don’t re­quire any un­der­stand­ing of Rust at all—a fact I only cite be­cause it is a com­mon point of con­cern.

Instead of throw­ing a wall of text in your face, I’m break­ing this “guide” of sorts into three sim­ple sec­tions. You don’t need to read all three—in fact, I would rec­om­mend against it.

The only thing you need from here is an idea of the gram­mat­i­cal rule you want to add to Harper. Don’t have one in mind? Visit our is­sue board to find a po­ten­tial rule that piques your in­ter­est.

The three paths:

1. A “phrase cor­rec­tion”. These are for the sim­plest gram­mat­i­cal rules. Use one of these in cases where se­man­tic mean­ing and con­text aren’t im­por­tant.
2. An ExprLinter. These are for more com­plex rules. Use one of these in cases where se­man­tic mean­ing or con­text are im­por­tant, and you don’t need ac­cess to in­for­ma­tion wider than clause-level. Takes a lit­tle bit to learn, but are ex­tremely pow­er­ful.
3. A plain Linter. These are of­ten used for rules that in­volve punc­tu­a­tion. It re­quires the most Rust knowl­edge but the least Harper-specific knowl­edge. I’m go­ing to hold off on writ­ing a guide for these un­til I hear a real de­sire to learn about them.

These guides will fo­cus more on the process of writ­ing a rule for Harper, not the tech­ni­cal de­tails of wiring it up. For the lat­ter, see our of­fi­cial doc­u­men­ta­tion.

This is part of a se­ries. Go to the start.

There are sev­eral ways to add a gram­mat­i­cal rule to Harper. This post aims to out­line the eas­i­est (and most con­strained): a “phrase cor­rec­tion”.

Sometimes you’ll see a sim­ple but com­mon gram­mat­i­cal er­ror that does­n’t have much to do with any broader con­text. For ex­am­ple, I of­ten mistype “in the” as “int he”. It hap­pens quite of­ten, and there is­n’t a broad pat­tern at play here. This is a per­fect can­di­date for a “phrase cor­rec­tion”.

From a tech­ni­cal point of view, a “phrase cor­rec­tion” is just a map­ping from one or more phrases to an­other set of phrases. But they’re more than a sim­ple search-and-re­place. Un­der-the-hood, Harper will ac­count for var­i­ous cap­i­tal­iza­tion and styl­is­tic changes that can be dif­fi­cult to cover man­u­ally. For­tu­nately, they’re pretty easy to add to Harper.

Before we be­gin, make sure you prop­erly set up your en­vi­ron­ment.

Open up the Harper monorepo. In harper-core/src/linting/phrase_corrections/mod.rs, you’ll find a list of en­tries that look some­what like this:

"GildedAge" => (
    ["guilded age"],
    ["Gilded Age"],
    "The period of economic prosperity is called the `Gilded Age`.",
    "If referring to the period of economic prosperity, the correct term is `Gilded Age`."
),
"GoingTo" => (
    // The value to map _from_.
    ["gong to"], 
    // The suggestions to present to the user, which replace the problematic text.
    ["going to"], 
    // The message for the user.
    "Did you mean `going to`?",
    // The rule description to be shown in settings pages.
    "Corrects `gong to` to the intended phrase `going to`."
),
"GotRidOff" => (
    ["got rid off", "got ride of", "got ride off"],
    ["got rid of"],
    "Did you mean `got rid of`?",
    "Ensures `got rid of` is used instead of `got rid off`."
),

Each of these is a “phrase cor­rec­tion”. To add one for the prob­lem I out­lined above, we just need to ap­pend to the end of the list and open a pull re­quest.

"InThe" => (
    ["int he"],
    ["in the"],
    "Did you mean `in the`?",
    "Detects and corrects a spacing error where `in the` is mistakenly written as `int he`. Proper spacing is essential for readability and grammatical correctness in common phrases."
),

If you want to go the ex­tra mile, we’d re­ally ap­pre­ci­ate if you added one or two test cases to harper-core/src/linting/phrase_corrections/tests.rs to make sure every­thing works as ex­pected:

#[test]
fn corrects_int_he() {
    assert_suggestion_result(
        "That pizza stayed int he box.",
        lint_group(),
        "That pizza stayed in the box.",
    );
}

This is part of a se­ries. Go to the start.

Expression rules (or more com­monly, ExprLinters) are Harper rules that use de­clar­a­tive ex­pres­sions to find and fix gram­mat­i­cal er­rors. They’re halfway be­tween a “phrase cor­rec­tion” and man­u­ally im­ple­ment­ing Linter.

Make sure you prop­erly set up your en­vi­ron­ment.

Before we get started, let’s take a look at the ExprLinter trait. Here’s what it looks like at the time of writ­ing this post.

/// A trait that searches for tokens that fulfil [`Expr`]s in a [`Document`].
///
/// Makes use of [`TokenStringExt::iter_chunks`] to avoid matching across sentence or clause
/// boundaries.
#[blanket(derive(Box))]
pub trait ExprLinter: LSend {
    /// A simple getter for the expression you want Harper to search for.
    fn expr(&self) -> &dyn Expr;
    /// If any portions of a [`Document`] match [`Self::expr`], they are passed through [`ExprLinter::match_to_lint`] to be
    /// transformed into a [`Lint`] for editor consumption.
    ///
    /// This function may return `None` to elect _not_ to produce a lint.
    fn match_to_lint(&self, matched_tokens: &[Token], source: &[char]) -> Option<Lint>;
    /// A user-facing description of what kinds of grammatical errors this rule looks for.
    /// It is usually shown in settings menus.
    fn description(&self) -> &str;
}

The struc­ture of the trait re­veals some of the be­hind-the-scenes work Harper is do­ing for you. There are three phases:

1. You pro­vide Harper an Expr. It will it­er­ate through the doc­u­ment, look­ing for to­ken se­quences that match your ex­pres­sion.
2. Any and all matches are passed to match_to_lint. From there, you can per­form op­tional ad­di­tional val­i­da­tion to con­firm that the to­kens re­ally do rep­re­sent a gram­mat­i­cal er­ror. If so, re­turn None. Otherwise, re­turn a Lint with any sug­ges­tions that may fix the prob­lem.
3. Harper will han­dle every­thing else. It will show UI, re­for­mat text, and set­tings menus to the user. It will also per­form ag­gres­sive caching on the first two steps, so any mod­i­fi­ca­tions to the doc­u­ment have a neg­li­gi­ble per­for­mance im­pact.

Let’s Get Started

Now that we’ve re­viewed the es­sen­tials, let’s im­ple­ment an ExprLinter.

Before we can write a sin­gle line of code, we need a gram­mat­i­cal rule of in­ter­est. I’m go­ing to pay a visit to the Harper is­sue board.

After look­ing through a few op­tions, I think #1513 is a good can­di­date. We are look­ing for miss­ing prepo­si­tions be­tween an ad­jec­tive and a sub­ject.

To get started, we’ll cre­ate a file un­der harper-core/src/linting called missing_preposition.rs and add it to the par­ent Rust mod­ule. I’ll paste the tem­plate into the file:

pub struct MissingPreposition {
    expr: Box<dyn Expr>,
}

impl Default for MissingPreposition {
    fn default() -> Self {
        let expr = todo!();

        Self {
            expr: Box::new(expr),
        }
    }
}


impl ExprLinter for MissingPreposition {
    fn expr(&self) -> &dyn Expr {
        self.expr.as_ref()
    }

    fn match_to_lint(&self, matched_tokens: &[Token], _source: &[char]) -> Option<Lint> {
        unimplemented!()
    }

    fn description(&self) -> &'static str {
        unimplemented!()
    }
}

I like to start by build­ing out a few test cases be­fore work­ing on the ac­tual code. We get some for free from the GitHub is­sue:

#[test]
fn fixes_issue_1513() {
    assert_lint_count(
        "The city is famous its beaches.",
        MissingPreposition::default(),
        1,
    );
    assert_lint_count(
        "The students are interested learning.",
        MissingPreposition::default(),
        1,
    );
}

Obviously, these tests will fail if we try to run cargo test, but at this point you should do so any­way to make sure your tool­chain is work­ing.

Writing our Expression

The heart of this gram­mat­i­cal rule is the Expr (pronounced ex­pres­sion). There are a num­ber of ways to go about mak­ing one of these. The sim­plest (and most com­mon by far) is to put to­gether a SequenceExpr.

In our case, we’re look­ing for miss­ing prepo­si­tions be­tween an ad­jec­tive and a noun. A good ex­pres­sion to start with could look like:

impl Default for MissingPreposition {
    fn default() -> Self {
        let expr = SequenceExpr::default()
            .then(UPOSSet::new(&[UPOS::ADJ]))
            .t_ws()
            .then(UPOSSet::new(&[UPOS::NOUN, UPOS::PRON, UPOS::PROPN]));

        Self {
            expr: Box::new(expr),
        }
    }
}

We’re us­ing a UPOSSet here, which is an­other kind of Expr that looks for spe­cific parts of speech. The name de­rives from the Universal Dependencies tag sys­tem. Any to­kens tagged with any of the op­tions we’ve pro­vided to the UPOSSet will match.

However, it’s easy to cre­ate an ex­am­ple that this ex­pres­sion matches against, but does­n’t con­tain a gram­mat­i­cal er­ror. We call this a false pos­i­tive. Let’s write one and add it to our test suite.

#[test]
fn allows_terrible_stuff() {
    assert_no_lints(
        "Either it was terrible stuff or the whiskey distorted things.",
        MissingPreposition::default(),
    );
}

From here, you should use your brain to con­tin­u­ously re­fine the ex­pres­sion into some­thing that main­tains a low false-pos­i­tive rate while re­main­ing use­ful. Here’s what I set­tled on:

impl Default for MissingPreposition {
    fn default() -> Self {
        let expr = SequenceExpr::default()
            .then(
                AnchorStart.or(SequenceExpr::default()
                    .then(UPOSSet::new(&[UPOS::DET]))
                    .t_ws()),
            )
            .then(UPOSSet::new(&[UPOS::NOUN, UPOS::PRON, UPOS::PROPN]))
            .t_ws()
            .then(UPOSSet::new(&[UPOS::AUX]))
            .t_ws()
            .then(UPOSSet::new(&[UPOS::ADJ]))
            .t_ws()
            .then(UPOSSet::new(&[UPOS::NOUN, UPOS::PRON, UPOS::PROPN]))
            .then_optional(AnyPattern)
            .then_optional(AnyPattern);

        Self {
            expr: Box::new(expr),
        }
    }
}

Now that we have an ef­fec­tive ex­pres­sion as a base, let’s fill out the re­main­ing fields. I found check­ing for an ad­po­si­tion re­duced the false-pos­i­tive rate, and it was eas­i­est to add it to the match_to_lint func­tion.

impl ExprLinter for MissingPreposition {
    fn expr(&self) -> &dyn Expr {
        self.expr.as_ref()
    }

    fn match_to_lint(&self, matched_tokens: &[Token], _source: &[char]) -> Option<Lint> {
        if matched_tokens.last()?.kind.is_upos(UPOS::ADP) {
            return None;
        }

        Some({
            Lint {
                span: matched_tokens[2..4].span()?,
                lint_kind: LintKind::Miscellaneous,
                suggestions: vec![],
                message: "You may be missing a preposition here.".to_owned(),
                priority: 31,
            }
        })
    }

    fn description(&self) -> &'static str {
        "Locates potentially missing prepositions."
    }
}

That’s it! We’ve writ­ten our rule.

Don’t for­get to reg­is­ter your rule and add some more tests be­fore open­ing PR. Make sure you take a look at the pull re­quest to see the fin­ished rule.

When I started the Harper pro­ject I knew I wanted to be able to use it for the com­ments in my code. First, be­cause I knew these com­ments would be­come part of our of­fi­cial doc­u­men­ta­tion over time, and be­cause I hoped it would en­cour­age me to write more. Over time, this has be­come one of the most prized fea­tures of the soft­ware, at­tract­ing tens of thou­sands of de­vel­op­ers.

The com­mon prob­lem, how­ever, is that there have al­ways been pro­gram­ming lan­guages that our LSP does­n’t sup­port. One of the old­est is­sues on GitHub is about this.

This post is a guide for adding a new pro­gram­ming lan­guage to the Harper lan­guage server.

Why is­n’t it in the of­fi­cial doc­u­men­ta­tion? While the in­for­ma­tion con­tained within this guide will re­main rel­e­vant to the pro­ject for a long time, I don’t imag­ine each iden­ti­fier or file path to re­main the same. If you think it would bet­ter serve po­ten­tial con­trib­u­tors to place this guide on the main site, let me know.

Introduction to Tree-sitter

Tree-sitter is fan­tas­tic frame­work for build­ing fault-tol­er­ant lan­guage parsers. That means it is still able to parse the ma­jor­ity of a doc­u­ment, even if it con­tains por­tions of in­valid syn­tax.

This is im­por­tant for Harper, since we ex­pect peo­ple to use Harper while their pro­gram­ming. It should be OK if some of their code is in­cor­rect, since we only care about their com­ments.

There are also a wide va­ri­ety of Tree-sitter parsers avail­able on crates.io, ripe for our con­sump­tion. If you want to add a lan­guage to Harper, this is the eas­i­est way to do so.

Step 0: Avoid Duplicating Work

You’re in­ter­ested in adding sup­port for a pro­gram­ming lan­guage. If that’s the case, it’s pos­si­ble other peo­ple are too. Make sure no one else has opened a PR or has al­ready merged sup­port for the lan­guage you have in mind.

Step 1: Find a Grammar

Look for an ex­ist­ing gram­mar on crates.io. By con­ven­tion, they tend to be named tree-sitter-<language>, where <language> is the lan­guage you’re look­ing for. For ex­am­ple, tree-sitter-java is for Java and tree-sitter-rust is for Rust.

If you would rather write your own gram­mar, make sure it is even­tu­ally pub­lished on crates.io. harper-ls bi­na­ries are of­ten con­sumed from crates.io, which re­quires that all up­stream de­pen­den­cies come from the same source.

Step 2: Import and Wire In

Harper’s com­ment sup­port lies in the harper-comments crate in the monorepo. Import the gram­mar’s crate into the pro­ject with Cargo.

cargo add <CRATE-NAME>

Then, add lines to the rel­e­vant func­tions in harper-comments/src/comment_parser.rs. Make sure you visit the Language Server Protocol Specification to ob­tain the cor­rect lan­guage ID.

pub fn new_from_language_id(
    language_id: &str,
    markdown_options: MarkdownOptions,
) -> Option<Self> {
    let language = match language_id {
        "cmake" => tree_sitter_cmake::LANGUAGE,
        "cpp" => tree_sitter_cpp::LANGUAGE,
        "csharp" => tree_sitter_c_sharp::LANGUAGE,
        "c" => tree_sitter_c::LANGUAGE,
        "dart" => harper_tree_sitter_dart::LANGUAGE,
        "go" => tree_sitter_go::LANGUAGE, // Add a line here

/// Convert a provided path to a corresponding Language Server Protocol file
/// type.
///
/// Note to contributors: try to keep this in sync with
/// [`Self::new_from_language_id`]
fn filename_to_filetype(path: &Path) -> Option<&'static str> {
    Some(match path.extension()?.to_str()? {
        "bash" => "shellscript",
        "c" => "c",
        "cmake" => "cmake",
        "cpp" => "cpp",
        "cs" => "csharp", // Add a line here

Step 3: Testing

To make sure every­thing be­haves cor­rectly, we need to add some in­te­gra­tion tests. You’ll find all the ex­ist­ing ones un­der harper-comments/tests/language_support_sources.

Find or write sev­eral new files un­der this di­rec­tory in the lan­guage you’ve added sup­port for. Add in­ten­tional gram­mat­i­cal er­rors to these file in syn­tac­ti­cally rel­e­vant places. We want to make sure that Harper can de­tect the er­rors we want and will ig­nore the er­rors we do not want. For ex­am­ple, we might put an er­ror in­side an @param tag in JSDoc. That way we’ll know if Harper is not prop­erly ig­nor­ing those el­e­ments.

Add new en­tries to the bot­tom of harper-comments/tests/language_support.rs. The sec­ond pa­ra­me­ter of the create_test! macro is the num­ber of gram­mat­i­cal er­rors that Harper should de­tect in that file.

create_test!(ignore_shebang_3.sh, 0);
create_test!(ignore_shebang_4.sh, 1);
create_test!(common.mill, 1);
create_test!(basic_kotlin.kt, 0); // Add a line here

From there, you can run cargo test to make sure every­thing passes.

Step 4: Document

To ad­ver­tise sup­port for the lan­guage, there are a cou­ple ad­di­tion places that need mod­i­fi­ca­tion. No­tably:

• The sup­ported lan­guages table in packages/web/src/routes/docs/integrations/language-server/+page.md
• The GitHub Issue
• The activationEvents key in the VS Code plug­in’s man­i­fest: packages/vscode-plugin/package.json

Done!

That should be every­thing. Open a draft pull re­quest while you work and ping me (eli­jah-pot­ter) if you have any ques­tions.

Additional Resources

• PR for adding Solidity sup­port
• PR for adding Scala sup­port

The ti­tle of this post is some­what mis­lead­ing. Local-first soft­ware rarely needs to be scaled at all.

Harper re­cently re­ceived a mas­sive in­crease in both traf­fic and user count. How? By mak­ing it to the front page of Hacker News. If you could­n’t tell by the ex­tent to which I talk about this, I’m thrilled. This amounted to a tremen­dous amount of free ad­ver­tis­ing, if noth­ing else.

I’ve been think­ing a lot about the won­drous ben­e­fits of work­ing at the edge. That’s just one term of many that peo­ple use to de­scribe Harper: “edge-first”. Others in­clude “local-first” or sim­ply “on-device”. They are all just jar­gon for a sim­ple idea: We run all the rel­e­vant gram­mar check­ing code as phys­i­cally close to the users as pos­si­ble. That way, we can serve up sug­ges­tions faster than any­one else. To achieve our goal, we make sure that every­thing is well-op­ti­mized and lean. Harper barely uses any CPU or mem­ory at all.

What does all this mean in the con­text of the re­cent uptick in user ac­qui­si­tion? Imagine, for a mo­ment, we are LanguageTool. Our soft­ware is writ­ten in Java, with ques­tion­able at­ten­dance to the ef­fi­ciency of our code. Since our soft­ware re­quires a big server to run, we have a cer­tain num­ber of servers on standby to han­dle a cer­tain amount of ex­pected load.

If sud­denly the num­ber of re­quests we re­ceived were to dou­ble (as it did for the Chrome ex­ten­sion), we would be big trou­ble. To avoid in­creas­ing the la­tency on re­quests (or drop­ping re­quests all to­gether), we would need to scale up the num­ber of run­ning servers. This not only takes hir­ing an ex­pert in cloud ar­chi­tec­ture, but also ad­di­tional fund­ing to pay the AWS (or what­ever) bill at the end of the month.

Because Harper runs at the edge (no server re­quired), we don’t have to worry about that. In fact, I only no­ticed that our user count had spiked af­ter I vis­ited Hacker News the morn­ing af­ter. No hic­cups at all.

Lots of cloud providers like to brag about be­ing able to scale with their users. I like to brag about not hav­ing to scale at all.

A bold ti­tle, no? But it’s true, and it’s some­thing that I (and most other main­tain­ers) have to deal with on a reg­u­lar ba­sis. Failing to ac­count for this re­al­ity can slow down de­vel­op­ment and dis­suade con­trib­u­tors from stick­ing around.

As the chief main­tainer of Harper, one of my main jobs is to act as qual­ity con­trol. I re­ceive a num­ber of PRs each week, both from new con­trib­u­tors and old. Given the di­verse pool of con­trib­u­tors, it makes sense that I re­view a di­verse pool of code of vary­ing lev­els of qual­ity.

When I have my head down on tech­ni­cal and at­ten­tion-in­tense pro­jects, I have less time to re­view code. When I have less time, I need to set pri­or­i­ties. The ques­tion be­comes: Would I rather let code from high-qual­ity, re­li­able sources pile up, or code from sources of un­known qual­ity?

I usu­ally end up re­view­ing the high-qual­ity sources first, since they’ll likely re­quire fewer re­vi­sions. Fewer re­vi­sions means quicker merge means im­prov­ing the user ex­pe­ri­ence faster. Whether or not this is a good de­ci­sion is some­thing I’ve been think­ing about all week.

Code Ages

As code sits stag­nant in a PR, it ages. You might say I’m crazy, that there is no way the code it­self changes as it sits still in an un­merged and un­mod­i­fied PR. I’d say you’re right, ex­cept for one teeny-tiny de­tail: Code only has mean­ing when it sits within a broader con­text. If that broader con­text changes (for ex­am­ple, when other PRs are merged) the mean­ing of the un­mod­i­fied code does too.

Let me put it an­other way. If the patch from a PR re­mains stag­nant, but the code it gets patched onto changes, the ac­tual im­pact of the patch does too. This can cause all sorts of prob­lems, from merge con­flicts to er­ro­neous test fail­ures.

The longer code sits in a PR, the more time it usu­ally ends up tak­ing me to get it merged (when I fi­nally have the time to get to it), just from the merge con­flicts alone. It’s the Lindy ef­fect rear­ing its ugly head once more.

Features Age Too

Not only does code age when left un­touched and un­used, so do the fea­tures they rep­re­sent. If a user re­quests for a but­ton that marks some text as bold and they don’t re­ceive that fea­ture promptly, they’ll find an al­ter­na­tive so­lu­tion, pos­si­bly from a com­peti­tor.

The rest of the app can evolve too. If you’re an in­di­vid­ual con­trib­u­tor, it’s in your best in­ter­est for your code to make it to mas­ter. If that does­n’t hap­pen quickly enough, an­other con­trib­u­tor (or, if the soft­ware is ex­ten­si­ble, like Obsidian or WordPress) or plu­gin au­thor might beat you to the punch.

What Can I Do About It?

I be­lieve the way I’ve been han­dling this un­til now has been en­tirely wrong. I should be al­lo­cat­ing more of my time to train­ing new con­trib­u­tors and field­ing PRs from es­tab­lished ones. Open sources is a team ef­fort.

As for you, dear reader, that’s for you to fig­ure out. The worst way code can age is if it stays in your head. Don’t let your ideas go to waste. Open that PR, or re­mind your re­viewer to take an­other look if you haven’t al­ready.

It has been a slow cou­ple of months for my read­ing habit. Al­though, now that I’ve said that out loud, I re­al­ize I say that every time. I never quite read enough books by the time I feel ready to write one of these read­ing re­views.

In the in­ter­est of brevity, let’s jump straight in.

How to Stop Time by Matt Haig

After read­ing The Midnight Library in January, I was thor­oughly im­pressed by Haig’s work. I wanted more, but was­n’t sure what to read next. So, the next time I saw a book with an in­ter­est­ing ti­tle which hap­pened to be his, I picked it up.

If The Midnight Library was a lit­er­ary ther­apy ses­sion, How to Stop Time is a his­tory les­son. It fol­lows a man who ages at one-tenth the rate of a nor­mal hu­man. De­spite be­ing given the gift of ex­tra life, he reg­u­larly falls into spats of de­pres­sion when his loved ones die be­fore him.

While Haig’s writ­ing con­tin­ues to be sen­ti­men­tal and ap­pre­cia­tive of the small things in life (a trait few seem to pos­sess these days), I ul­ti­mately found the book pre­dictable and un­en­gag­ing. It was a good book, and I felt sat­is­fied hav­ing read it, I had put it down for a few days at a time more than once to do so. If you’re go­ing to read just one of Haig’s books, it should­n’t be this one.

Everything is Tuberculosis by John Green

I’ve been a fan of John Green’s work since I was kid. I re­mem­ber read­ing Looking for Alaska as I cruised down the Mississippi River on a school trip. It was one of the most mem­o­rable books (and ex­pe­di­tions) I’ve had the plea­sure of ex­pe­ri­enc­ing.

Naturally, I was ec­sta­tic to hear John Green pub­lished some­thing new: Everything is Tuberculosis, a book about the facets of our lives (of which there are many) that we can thank TB for.

I liked this book, but I don’t think it matches the re­flec­tive at­ti­tude about the hu­man ex­pe­ri­ence you find in his other books—but that’s a good thing! Everything is Tuberculosis is not a book you’re sup­posed to re­late to, but a book that tells a story about a life most in the west­ern world find com­pletely un­fa­mil­iar. One where each and every day is counted. One where the price of a med­ica­tion is the most im­por­tant num­ber. One where you might not sur­vive.

The fact that I could­n’t re­late to the events in Everything is Tuberculosis is the ex­act rea­son why I’m glad I read it.

How to Win Friends and Influence People by Dale Carnegie

I read How to Win Friends and Influence People (a mouth­ful, I know) not be­cause I needed ad­vice on the sub­ject. I read it be­cause I be­lieve this book to be a telling win­dow into the minds of the busi­ness­men of the early 20th cen­tury.

I’ve been told that this book is still rel­e­vant to­day; that the ad­vice still works. I dis­agree. The pri­or­i­ties, val­ues, and cul­ture are en­tirely dif­fer­ent to­day than when this book was writ­ten. I found it fas­ci­nat­ing to com­pare and con­trast be­tween my own ex­pe­ri­ence and the au­thor’s.

There’s a great deal of over­lap be­tween those who use Harper and those who use Firefox. Foremost, they both value pri­vacy. Which is why I’m so thrilled to say that Harper has an of­fi­cial plu­gin for Firefox. While there has been an un­of­fi­cial one for a while now, this is the one that fully de­serves the Harper la­bel. It’s ours, through and through.

It’s still early days, so if you run into prob­lems, feel free to open an is­sue.

If you’d like to in­stall it, pay us a visit on the Firefox Add-on Store.

I’ve been deep in the refac­tor rab­bit-hole. You know—that aw­ful (but strangely sat­is­fy­ing) space where the ma­jor­ity of your com­mits are small pedan­tic ed­its that don’t change the end-user-ex­pe­ri­ence at all?

These past few weeks, I’ve been work­ing so hard on Harper’s Chrome Extension and build­ing sys­tems for trans­for­ma­tion-based learn­ing, I haven’t had a chance to touch any of the ac­tual gram­mar rules the soft­ware is sup­posed to fix. As such, a few glar­ing tools for rule au­thors have gone unim­ple­mented. These are tools that—be­cause they’re so tied into the core sys­tem—need a lot of ex­per­tise and fine-tun­ing to work prop­erly.

If you take a look at the diff, you’ll find that there are a lot of small ed­its. Since each one takes a min­i­mal amount of cog­ni­tive ef­fort, it is easy for me to slide into a trance. A trance where I am tech­ni­cally mov­ing to­wards my goal (in this case, cre­at­ing an ex­pres­sion sys­tem that en­com­passes—but is more pow­er­ful than—our ex­ist­ing Pattern sys­tem), but I’m not do­ing so in a way that’s truly pro­duc­tive. I would like to cover some of the in­di­vid­ual strate­gies I’ve found that have helped me speed up my refac­tor­ing pro­ces. Af­ter all, if the process of refac­tor­ing is the process of pay­ing back tech debt, refac­tor­ing is in­cred­i­bly im­por­tant to main­tain­ing ve­loc­ity.

I am do­ing this for two rea­sons. First, be­cause I be­lieve this is valu­able in­for­ma­tion for any de­vel­oper. Sec­ond, be­cause I want to so­lid­ify these ideas in my mind to fur­ther im­prove my refac­tor­ing down the line.

Use Your Tools, but Not Too Much

In what­ever lan­guage you’re work­ing with, there are likely spe­cial­ized tools for refac­tor­ing. For Java, I’ve used IntellJ IDEA. For Harper, I’m us­ing rust-analyzer. These pro­vide neat func­tions for chang­ing iden­ti­fiers or mov­ing mod­ules, all while up­dat­ing rel­e­vant ref­er­ences.

These tools are im­per­fect, how­ever, and of­ten fail to up­date ref­er­ences in parts of code that re­quire a higher level of se­man­tic un­der­stand­ing.

It’s a com­mon pat­tern for au­thors to cre­ate an in­stance of a class and as­sign it to a vari­able with the same name.

#[derive(Default)]
struct Foo {
    // Implementation details
}

fn main() {
    // The author of this code named the variable after the class
    let foo = Foo::default();
}

In these cases, when some­one changes the name of the class, the as­so­ci­ated vari­able name will not get up­dated.

#[derive(Default)]
struct Bar {
    // Implementation details
}

fn main() {
    // Variable name is not updated by our static analysis tool.
    let foo = Bar::default();
}

When do­ing a refac­tor like this, you need to read every changed file to en­sure the code still makes as much sense to a hu­man as it does to the com­piler.

Plan It Out, but Not Too Much

I can’t be­lieve I need to say this, but it’s chron­i­cally un­der-dis­cussed. If you’re do­ing a fun­da­men­tal change to how a sys­tem works, it is vi­tal that you read the code first and plan it out. The plan does­n’t need to be spe­cific nor need to be com­plete.

Having a good idea of what the start and end state should look like will save you hours of time. While I am a pro­po­nent of dis­cov­ery cod­ing for new fea­tures and code, I find that it is lack­lus­ter when it comes to ma­jor re-writing of code.

To in­struct peo­ple to plan out their changes may feel ju­vinile or ba­sic, but I think it’s worth men­tion­ing.

The Joy

Refactoring helps me write new fea­tures, faster. Refac­tor­ing helps me find bugs in ex­ist­ing code. Refac­tor­ing makes it eas­ier for new­com­ers to join and con­tribute to a pro­ject.

It is one of my fa­vorite pas­times. I en­joy refac­tor­ing, but also want to do it well. I hope you feel the same.

The most com­mon type of ma­chine learn­ing out there takes the form of some kind of neural net­work. Inspired by how our own brains work, these sys­tems act as func­tion ap­prox­i­ma­tions. They are great, but they come with a few key pit­falls.

First and fore­most, they start out with very lit­tle baked-in un­der­stand­ing of the con­text they live in. This is fine—usu­ally enough data can be pro­vided to bridge the gap. It does mean, how­ever, that they spend an in­or­di­nate amount of time learn­ing the fun­da­men­tals of their field. This trans­lates to a larger model size and longer in­fer­ence time (especially at the edge).

Secondly, most neural net­works are ini­tial­ized with ran­dom­ness, which re­sults in ex­tremely high en­tropy. High en­tropy means that these mod­els can­not be com­pressed eas­ily (if at all).

This dis­qual­i­fies neural net­works from many as­pects of Harper’s ar­chi­tec­ture. Harper tries to be fast and small, so it can be shipped and run wher­ever our users are. Neural net­works (especially in the world of nat­ural lan­guage pro­cess­ing) are nei­ther fast nor small.

This is why we’ve tak­ing an al­ter­na­tive ap­proach to ma­chine learn­ing, as ev­i­denced by last week’s post on trans­for­ma­tion-based learn­ing.

Transformation-Based Learning: A Refresher

Transformation-based learn­ing is re­mark­ably sim­ple. It boils down to just four steps:

• Use a sim­ple, sto­chas­tic model t la­bel your data. This can be as sim­ple as tag­ging each to­ken (or other dis­crete com­po­nent) with that vari­ant’s most com­mon tag. It does­n’t need to su­per ac­cu­rate, just enough to es­tab­lish a base­line.
• Identify the er­rors be­tween the tags in your canon­i­cal data and that which pro­duced by your base­line model.
• Using a fi­nite list of hu­man-de­fined tem­plates, gen­er­ate can­di­date rules that trans­form the out­put of the base­line model into some­thing else. This is where the term “trans­for­ma­tion-based” comes from.
• Apply each of the can­di­date rules to the base­line mod­el’s out­put. Check if the re­sult is more ac­cu­rate than be­fore. If so, save the rule for fu­ture use.

These saved can­di­dates be­come your model.

If you’re in­ter­ested how this could be ap­plied to POS tag­ging, I’ve since up­dated my orig­i­nal post on the sub­ject to bet­ter ex­plain the process. I’d rec­om­mend tak­ing a look.

Nominal Phrase Chunking

It’s of­ten use­ful, es­pe­cially when build­ing a gram­mar checker, to be able to iden­tify the sub­jects and ob­jects of sen­tences. Suppose, for ex­am­ple, that we want to in­sert the miss­ing Oxford comma in a list of fruits: “I like ap­ples, ba­nanas and or­anges”. In this triv­ial ex­am­ple, this can be done with POS tag­ging. If we have more com­plex sub­jects, like in the phrase “I like green ap­ples, de­li­ciously per­ni­cious ba­nanas and fresh or­anges,” POS tag­ging starts to fall apart. Identifying multi-to­ken sub­jects is the job of a nom­i­nal phrase chun­ker.

I’ve been want­ing to build a nom­i­nal phrase chun­ker for a while, but haven’t had the tools to do so. Now that I have pipeline in place (from last week), it should be rel­a­tively straight­for­ward.

For the pur­poses of this model, we’ll be tag­ging each to­ken with a boolean; it is ei­ther a mem­ber of a noun phrase, or it is not.

I started by as­sign­ing each to­ken to a nom­i­nal phrase if a POS tag­ger marks it as a noun. This is our base­line model. It per­forms poorly be­cause the re­sult­ing nom­i­nal phrases do not in­clude de­ter­min­ers or any ad­jec­tives.

Similar to our POS tag­ging model, I used a Universal Dependencies tree­bank to de­ter­mine the ac­cu­racy of our base­line. After gen­er­at­ing can­di­date rules us­ing the same patch tem­plates as the POS tag­ging sys­tem and run­ning them against the tree­bank, I have a model with a 90% ac­cu­racy.

I feel as though there should be more de­tails to share, but that was pretty much it. I spent a good amount of time op­ti­miz­ing the train­ing code. There’s still a lot of work left to do to in­cor­po­rate it into the rest of Harper. I am also un­sat­is­fied with the mod­el’s cur­rent ac­cu­racy. To get it closer to 100%, I sus­pect I’ll need to do a good amount of data clean­ing.

Harper is cur­rently un­der­go­ing some pretty rad­i­cal changes when it comes to its lan­guage analy­sis. These im­prove­ments will im­prove the out­put of our ex­ist­ing rule en­gine, in ad­di­tion to mak­ing en­tirely new cor­rec­tions pos­si­ble. This post will cover our ex­ist­ing NLP pipeline, the re­cent changes and im­prove­ments to our ma­chine learn­ing ap­proach, and what will come next.

While AI is a com­mon topic of dis­cus­sion on­line, I don’t hear much about ac­tual ma­chine learn­ing. In that light, I hope this post piques some­one’s in­ter­est.

What is POS Tagging?

POS (Part-of-speech) tag­ging is the first step of most NLP (Natural Language Processing) pipelines. For any gram­mar checker worth its salt, POS tag­ging is es­sen­tial. Apart from the ba­sic cor­rec­tions you’re ca­pa­ble of do­ing with sim­ple string ma­nip­u­la­tion, most gram­mar check­ing di­rectly or in­di­rectly de­pends on POS tag­ging. High-quality tag­ging re­sults in high-qual­ity sug­ges­tions.

What is POS tag­ging? It is the process of iden­ti­fy­ing which pos­si­ble de­f­i­n­i­tion of a word is be­ing used, based on the sur­round­ing con­text. For those un­fa­mil­iar with the ter­ri­tory, I’m cer­tain an ex­am­ple is the best way to ex­plain.

“I am go­ing to go tan in the sun.”

Here we have a sim­ple, English sen­tence. In this case, it is clear the word “tan” is be­ing used as verb. The lin­guists in the au­di­ence would point out that it is specif­i­cally in the first-per­son fu­ture tense. Consider this sim­i­lar sen­tence:

“I am al­ready very tan, so I will stay in­side.”

In this sen­tence, the word “tan” is be­ing used as an ad­jec­tive. How can we tell?

As in­tel­li­gent hu­mans, some of whom have been speak­ing English their en­tire lives, it is easy for us to de­ter­mine which words are serv­ing which roles. It’s not as easy for a com­puter to do the same. From an al­go­rith­mic stand­point, there are a num­ber of ways to go about it, each with dif­fer­ing lev­els of “machine learn­ing” re­quired.

Before this week, Harper pri­mar­ily took a dic­tio­nary-based ap­proach. In short: we ship a “dictionary” of English words to the user’s ma­chine and use hash table lookups to de­ter­mine the pos­si­ble roles each word could as­sume. The au­thors to our rule en­gine could then use rudi­men­tary de­duc­tive rea­son­ing to nar­row the pos­si­bil­i­ties down. This strat­egy is re­mark­ably ef­fec­tive and it has scaled to tens of thou­sands of users with sur­pris­ingly few hic­cups.

That said, there are edge-cases and sys­tems (which I’ll cover next week when I dis­cuss chunk­ing) which re­quire ex­treme speci­ficity from POS tags. My mis­sion: im­prove our POS tag­ging to in­crease the con­fi­dence of Harper’s out­put and open the door for more ad­vanced al­go­rithms.

Why Transformation-based Learning?

The lit­er­a­ture high­lights four un­der­ly­ing ma­chine learn­ing model strate­gies that seem to work well for POS tag­ging.

• Hidden Markov Models (probabilistic mod­els that pre­date the mod­ern deep learn­ing era)
• Maximum Entropy Models (statistical mod­els closely re­lated to lo­gis­tic re­gres­sion).
• Transformer-based Models (which use deep neural net­works)
• Transformation-based Rule Models (which are based on learned rules)

While I heav­ily con­sid­ered us­ing a neural net­work (either via an HMM or MEM), I dis­carded the tech­nol­ogy for three rea­sons.

• TRMs are typ­i­cally more ac­cu­rate (barely; mea­sured in ba­sis points).
• TRMs are more amenable to fine-tun­ing.
• TRMs are ex­cep­tion­ally low-la­tency and can be com­pressed quite small.

Transformation-based learn­ing is re­mark­ably sim­ple. It boils down to just four steps:

• Use a sim­ple, sto­chas­tic model to la­bel your data. This can be as sim­ple as tag­ging each to­ken (or other dis­crete com­po­nent) with that vari­ant’s most com­mon tag. It does­n’t need to su­per ac­cu­rate, just enough to es­tab­lish a base­line.
• Identify the er­rors be­tween the tags in your canon­i­cal data and that which pro­duced by your base­line model.
• Using a fi­nite list of hu­man-de­fined tem­plates, gen­er­ate can­di­date rules that trans­form the out­put of the base­line model into some­thing else. This is where the term “transformation-based” comes from.
• Apply each of the can­di­date rules to the base­line mod­el’s out­put. Check if the re­sult is more ac­cu­rate than be­fore. If so, save the rule for fu­ture use.

These saved can­di­dates be­come your model.

POS-Tagging us­ing Transformation-based Learning

Let’s ap­ply these steps to build a POS-tagging sys­tem.

For our base­line model, we will just as­sign each word in our dataset the most com­mon POS tag as­so­ci­ated with that word. If the word is “tan”, we’ll as­sign it’s most com­mon POS tag (verb). It will of­ten be in­cor­rect, but those cases will be han­dled by our rules.

To iden­tify the base­line mod­el’s er­rors, we’ll use an off-the-shelf tree-bank from the Universal Dependencies pro­ject.

Our rule tem­plates will take the form of these PatchCriteria. By ini­tial­iz­ing our can­di­dates with any one of these enum vari­ants and ini­tial­iz­ing the child vari­ables to ran­dom val­ues, we can cover a good num­ber of cases.

#[derive(Debug, Clone, Serialize, Deserialize, Hash, PartialEq, Eq)]
pub enum PatchCriteria {
    WordIsTaggedWith {
        /// Which token to inspect.
        relative: isize,
        is_tagged: UPOS,
    },
    AnyWordIsTaggedWith {
        /// The farthest relative index to look
        max_relative: isize,
        is_tagged: UPOS,
    },
    SandwichTaggedWith {
        prev_word_tagged: UPOS,
        post_word_tagged: UPOS,
    },
    WordIs {
        relative: isize,
        word: String,
    },
    /// Not applicable to the Brill Tagger, only the chunker
    NounPhraseAt {
        is_np: bool,
        relative: isize,
    },
    Combined {
        a: Box<PatchCriteria>,
        b: Box<PatchCriteria>,
    },
}

Finally, we’ll ap­ply each of the hun­dreds of thou­sands of can­di­dates to our tree­bank to see if the re­sult of their trans­for­ma­tions have a lower er­ror rate than the base­line.

Here are a cou­ple of the can­di­dates we found:

[
  {
    "from": "PRON",
    "to": "SCONJ",
    "criteria": {
      "Combined": {
        "a": {
          "WordIs": {
            "relative": 0,
            "word": "that"
          }
        },
        "b": {
          "WordIsTaggedWith": {
            "relative": -1,
            "is_tagged": "VERB"
          }
        }
      }
    }
  },
  {
    "from": "PART",
    "to": "ADP",
    "criteria": {
      "Combined": {
        "a": {
          "WordIs": {
            "relative": 1,
            "word": "there"
          }
        },
        "b": {
          "AnyWordIsTaggedWith": {
            "max_relative": -4,
            "is_tagged": "NOUN"
          }
        }
      }
    }
  }
]

That’s the whole process! With it, I was able to bring our pre­vi­ous ac­cu­racy all the way up to 95% (from 40%) with­out a mean­ing­ful change in lint­ing la­tency or com­piled bi­nary size.

We de­signed Harper to be the ul­ti­mately portable gram­mar checker, but we’re still work­ing on liv­ing up to that promise. As the Harper Chrome ex­ten­sion be­comes more ca­pa­ble day-by-day, it has one crit­i­cal weak­ness: it does­n’t sup­port Firefox. Since Chrome has a much larger mar­ket share, it is­n’t a pri­or­ity at the mo­ment (although we ac­cept con­tri­bu­tions).

This is a won­der­ful ex­am­ple of where the open-source na­ture of the Harper’s core en­gine re­ally shines. Some­one has taken harper.js and put it into their own ex­ten­sion. SpellBolt is a Firefox ex­ten­sion that de­liv­ers Harper’s fan­tas­tic gram­mar check­ing straight into your Firefox browser. My ini­tial test­ing shows that it’s a solid ex­ten­sion.

I am de­lighted to see peo­ple mak­ing use of the plug­gable ar­chi­tec­ture Harper has adopted, and I can’t wait to see what SpellBolt does next.

Harper’s Chrome ex­ten­sion con­tin­ues to come along beau­ti­fully. I’m ac­tively work­ing to make it more use­ful and re­spon­sive, slowly crush­ing bugs that I hear about from our users and con­trib­u­tors. I will not go over them here, since our closed pull re­quests should speak for them­selves. I would, how­ever, like to rapid-fire some of the small im­prove­ments and ideas about Quality that I’ve been brew­ing up this week.

Quality

I first heard about big-Q Quality from Zen and the Art of Motorcycle Maintenance by Robert Persig. The book’s length—whose main sub­ject is the idea of Quality—speaks to its com­plex­ity as a topic. It’s a great read, and I’d highly rec­om­mend it.

One im­por­tant point the au­thor makes is that Quality is in­her­ently a hu­man idea. It is hard, if not im­pos­si­ble, to de­fine al­go­rith­mi­cally or on pa­per. When one in­ter­acts with an ob­ject or a sys­tem, they come away with a sense of its Quality, with­out nec­es­sar­ily know­ing ex­actly what led to that sense.

Some ar­gue that in to­day’s world of LLMs and fast-it­er­a­tions, the real value of a good soft­ware en­gi­neer de­rives from their sense of Quality. We know whether a de­sign de­ci­sion or change to the code is worth ex­plor­ing. We know how it will af­fect users. I don’t think this ar­gu­ment is rel­e­vant to the LLM dis­cus­sion at all, but I do agree with it in spirit.

The Most Important UI Element

Harper’s Chrome ex­ten­sion has one crit­i­cal UI el­e­ment that user’s should be in­ter­act­ing with more than any other: the sug­ges­tion box.

Before	After

When Harper lo­cates a prob­lem in a user’s text, it un­der­lines it and waits for them to no­tice. When they do, they have the op­tion to click it and re­view Harper’s sug­ges­tion. This is a flow typ­i­cal of most spell and gram­mar-check­ing pro­grams, so you’re likely fa­mil­iar with it. This process makes the con­tents and be­hav­ior of the sug­ges­tion box ex­tremely im­por­tant for user sat­is­fac­tion.

After re­ceiv­ing some feed­back re­lated to the sug­ges­tion box’s vi­sual un­pleas­ant­ness and dif­fi­culty to un­der­stand in­tu­itively, I’ve started mak­ing some mod­i­fi­ca­tions. Nothing dras­tic—I don’t want to con­fuse ex­ist­ing users. I’ve fo­cused on mak­ing it more com­pact and use more vi­sual sto­ry­telling. Now, when a spelling mis­take should be cor­rected, it shows an icon rather than a full “Add to dic­tio­nary” la­bel. I’m al­ready get­ting pos­i­tive feed­back about the changes.

All-in, it seems like much of the de­sign phi­los­o­phy of the UI is be­ing pushed fur­ther in the di­rec­tion of Harper’s core tenet: to get out of the way.

Why Quality is Important

Quality is im­por­tant for the Chrome ex­ten­sion (more so than other in­te­gra­tions) be­cause of the Chrome Web Store’s front page.

Extensions that get fea­tured on the front page get a sig­nif­i­cant amount of free ad­ver­tis­ing. Millions of users view this page monthly. Getting on the page is guar­an­tee of tens of thou­sands of new users, if not more.

Here’s the rub: you can’t get on the front page by pay­ing for it or by chance. An ex­ten­sion is placed on the front page if and only if it meets a high bar of value and qual­ity. In other words: you have to earn it. This is the es­sen­tial rea­son why I’ve been work­ing so hard on Quality these past few weeks: I’m try­ing to get on the front page.

Most of the steps I’ve taken in this di­rec­tion are small enough to not be worth men­tion­ing here. If you’re cu­ri­ous, feel free to reach out!

As I’ve ac­counted and dis­cussed in pre­vi­ous posts, one of the hard­est prob­lems Harper faces is that of the great di­ver­sity of the in­ter­net. There are a great va­ri­ety text ed­i­tors on the web, each used in a dif­fer­ent con­text. That’s a beau­ti­ful thing, but un­for­tu­nately our users ex­pect Harper to work in all of these places seam­lessly. I sup­pose you can view this post as a third part in this se­ries where I talk about sup­port­ing thou­sands of web­sites for po­ten­tially mil­lions of users (with zero server costs, I might add).

This jour­ney started in Discord (as many do), with a sat­is­fied user re­port­ing an is­sue. I’m quite for­tu­nate: they were tech­ni­cal. They’re re­port was de­tailed and in­cluded some ini­tial spec­u­la­tion on what the root cause could be.

While the ac­tual un­der­ly­ing prob­lem was com­plex and dif­fi­cult to fix, that is not what this post is about. It is about Harper’s strat­egy for do­ing end-to-end test­ing on the many sites we sup­port.

It’s rel­e­vant be­cause this was a prob­lem that could have been dis­cov­ered through end-to-end test­ing. Since we have a di­verse set of users al­ready, they found the is­sue swiftly. That is far from ideal. Our test­ing suite should catch these prob­lems be­fore the PR is merged.

Why Playwright?

“Playwright enables re­li­able end-to-end test­ing for mod­ern web apps.” At least—that’s what their site claims Playwright can do. I’m not sure if it lives up to this claim of re­li­a­bil­ity, at least not yet.

The de­ci­sion to use Playwright over al­ter­na­tive choices came down to a few key points:

• It’s quite pol­ished and well sup­ported (Microsoft seems to be the main player).
• While it is more com­plex to load a Chrome ex­ten­sion in Playwright than Puppeteer, I am also given a lot more con­trol.
• We’re al­ready us­ing it for other in­te­gra­tions (but not for end-to-end tests).

The Game Plan

My goal is to build up a com­pre­hen­sive-enough test suite that I can catch in­te­gra­tion prob­lems in for­eign text ed­i­tors be­fore I merge PRs for logic that in­ter­acts with them.

Step one was to get Playwright in­stalled and run­ning on my ma­chine, re­pro­ducible with npm. Fortunately for me, this was as sim­ple as: pnpm create playwright. Step two was a lit­tle more com­plex: get our ex­ten­sion loaded within the head­less browser. I found this could be done by over­rid­ing Playwright’s de­fault Chrome prop­er­ties, in­struct­ing it to only in­stall the Harper plu­gin and noth­ing else:

export const test = base.extend<{
	context: BrowserContext;
	extensionId: string;
}>({
	// biome-ignore lint/correctness/noEmptyPattern: it's by Playwright. Explanation not provided.
	context: async ({}, use) => {
		const pathToExtension = path.join(import.meta.dirname, '../build');
		console.log(`Loading extension from ${pathToExtension}`);
		const context = await chromium.launchPersistentContext('', {
			channel: 'chromium',
			args: [
				`--disable-extensions-except=${pathToExtension}`,
				`--load-extension=${pathToExtension}`,
			],
		});
		await use(context);
		await context.close();
	},
	extensionId: async ({ context }, use) => {
		let [background] = context.serviceWorkers();
		if (!background) background = await context.waitForEvent('serviceworker');

		const extensionId = background.url().split('/')[2];
		await use(extensionId);
	},
});
export const expect = test.expect;

From there, it was pretty triv­ial to build out as­ser­tions and tools for in­ter­act­ing with ba­sic el­e­ments for the spe­cific text ed­i­tor I was in­ter­ested in (Slate).

The Cool Part

Most text ed­i­tors on the web ad­ver­tise them­selves in the DOM, usu­ally with a spe­cial at­tribute like data-lexical-editor="true" or data-slate-editor="true". This even hap­pens on world-class sites like LinkedIn or Instagram. I won­der if I can use this for some­thing?

I be­lieve this con­sis­tency in pro­duc­tion code is in­ten­tional. Making our tests eas­ier to write must be a side-ef­fect of mak­ing the ed­i­tor au­thor’s tests eas­ier to write.

This is great news for me. With just a few tweaks, I can use the same code to test Harper on Discord, Medium, Notion, Desmos, Asana—you get the point. Since they use just a small set of rich text ed­i­tors (which come pre-tagged), I can gen­er­ate au­to­mated tests to de­ter­mine whether Harper works prop­erly on their sites.

The Not-So-Cool Part

The bad news: this process is slow. Each page must be fetched from the net­work and op­er­ated on like a user. We might be able to fix the first prob­lem, but the sec­ond is in­ter­minable. My ini­tial ex­per­i­ments put the run­time of each test case around thirty sec­onds. If I’m test­ing hun­dreds or thou­sands of sites, this is a real prob­lem.

For the time be­ing, I’ll have these tests be their own work­flow in GitHub Actions and only run them when the ex­ten­sion code changes. I don’t see peo­ple other than my­self mess­ing with this code too much, so I am not wor­ried.

What Does Testing Thousands of Sites Look Like?

I’ll ad­mit, I’m not quite to the “thousands of sites” ter­ri­tory just yet. The most frus­trat­ing part is get­ting started. Now that I’ve got a cou­ple of sites un­der my belt, with the tools ready and able , the next thou­sand will be a lot eas­ier.

Before I get too deep, I just want to get it out of the way: OpenAI’s o3 model is im­pres­sive. With its tool use and web search ca­pa­bil­i­ties, it can do a lot more than most of­fer­ings out there.

That said, al­though I’ve found it to be quite a ca­pa­ble coder, I still don’t trust it with any­thing im­por­tant. Once or twice, I’ve in­structed it to out­line a React com­po­nent, only to rewrite most of it my­self.

I also don’t trust its fac­tual ac­cu­racy at all. Af­ter hal­lu­ci­nat­ing a camp­ground and sev­eral en­tire web APIs, I can’t quite be­lieve any­thing it says. Not that I’ve trusted any model that came be­fore.

That said, there is one thing it is in­cred­i­bly use­ful for: find­ing canon­i­cal doc­u­men­ta­tion for com­plex sub­jects.

I’ve found the great­est suc­cess, per­son­ally and pro­fes­sion­ally, when I am work­ing with the most con­crete and orig­i­nal source of in­for­ma­tion avail­able. When work­ing with the web, the most canon­i­cal source is the W3C spec. When work­ing with com­pil­ers, it’s The Dragon Book. When re­search­ing the ins and outs of GNU/Linux sys­tems, it’s the man page.

This can’t be a novel con­cept. You (the reader) must see things the same way I do. Even LinkedIn seems to agree that base-truth doc­u­men­ta­tion is where we should be get­ting our in­for­ma­tion.

I’ve al­ways won­dered: if the W3C spec is the best place to find in­for­ma­tion about the web, why is­n’t it the first re­sult on Google? Why, af­ter all these years, is W3Schools still the first re­sult 90% of the time?

I use o3 to find canon­i­cal sources of in­for­ma­tion.

I was re­cently look­ing to im­prove the dy­namic range in my cam­era, but do so be­fore my post-pro­cess­ing step. By im­prov­ing dy­namic range in-cam­era, I can avoid the pit­falls of cer­tain kinds of com­pres­sion. I asked o3: “find me the canon­i­cal guide for im­prov­ing dy­namic range on my D7100 from the most au­thor­i­ta­tive source.”

I learnt more from the re­sult­ing guide (which was hosted on the Nikon web­site, NOT ChatGPT) than the last three years of shoot­ing, com­bined.

When our users in­stall Harper, they should ex­pect it to work any­where they do. Whether they’re writ­ing up a blog post in WordPress, leav­ing a com­ment on Facebook, or mes­sag­ing a loved one on WhatsApp, Harper should be there. Harper’s core is ex­tremely portable and it can run pretty much any­where Rust can, so what’s the big deal?

Why can’t we just run Harper in the browser through a web ex­ten­sion?

Running Locally

There’s a sin­gle com­plaint that I hear over and over again from peo­ple who use Grammarly or LanguageTool: they are both slow as mo­lasses. The process of writ­ing has slowly evolved to be more com­plex than it needs to be. With these tools, it writ­ing looks like:

1. Write a sen­tence.
2. Wait for the gram­mar checker to run (which takes as many as four sec­onds).
3. Fix the mis­takes you made.
4. Go back to step one.

The whole process re­minds me of the copi­lot pause. This is part of why Harper is bet­ter than these other tools: it does­n’t stop you from writ­ing at the speed of thought. Our most ar­dent users tell us this all the time: it feels great to just write, er­ror free.

How do we de­liver gram­mar check­ing so quickly?

Instead of host­ing huge Java code­bases in the cloud, we ship our soft­ware straight to the user’s de­vice. Since there’s no net­work re­quest in­volved, we’re able to put pix­els on the screen faster than any­one else. That’s not to men­tion the pri­vacy im­pli­ca­tions.

Running Harper’s en­gine lo­cally in the browser pre­sented some tech­ni­cal chal­lenges.

I’m quite proud that our JavaScript li­brary can be in­stalled as sim­ply as npm install harper.js. In or­der for that to work as well as it does, I needed to de­velop a sys­tem for:

1. Compiling our en­gine to WebAssembly.
2. Shipping that en­gine to the browser.
3. Instantiating the WebAssembly code.
4. Build out the boil­er­plate nec­es­sary to make it feel na­tive.

Steps one and four were easy. I just slapped #[wasm_bindgen] tags on a Rust li­brary and put on a pot of cof­fee. Steam­ing cof­fee is vi­tal for writ­ing te­dious JavaScript.

Steps two and three, how­ever, were a lit­tle more dif­fi­cult. The lat­est it­er­a­tion of Google’s ex­ten­sion stan­dard, Manifest V3, places some heavy-handed rules on how ex­e­cutable code could be loaded. I won’t bore you with the de­tails here. Know that I spent many hours in JavaScript bundler hell.

Running Everywhere

Harper, nascent as it is, has the great­est mar­ket op­por­tu­nity in the browser. Over 3.5 bil­lion peo­ple use Chrome on a weekly ba­sis. The plu­ral­ity of knowl­edge work­ers spend most of their wak­ing mo­ments (as crush­ing as it sounds) in a web browser. Half of the time spent at desks to­day is spent writ­ing.

In or­der to ad­dress this mar­ket seg­ment, we need a Chrome ex­ten­sion. To lint text in the browser, I need a way to:

1. Cleanly read text from in­put fields.
2. Locate the pixel co­or­di­nates of gram­mat­i­cal er­rors.
3. Render sug­ges­tions in pop­ups.
4. Cleanly re­place text in in­put fields when a sug­ges­tion is se­lected.

Reading and Writing Text is Hard

The web may have stan­dards, but there is noth­ing stan­dard about it. The “standard” way to in­put text is with a <textarea /> el­e­ment. Even so, most high-traf­fic sites im­ple­ment their own text ed­i­tors from scratch, us­ing <div contenteditable="true" /> as a base. Each of these cases re­quired spe­cial care.

<textarea />

<textarea />s are hard for one rea­son: it is dif­fi­cult to get a good un­der­stand­ing of what they look like. I can ob­tain their con­tent with input.value, but I can’t di­rectly in­fer the pixel co­or­di­nates of gram­mat­i­cal er­rors in­side them.

When the Harper Chrome Extension is of­fered an <input /> or <textarea /> el­e­ment to an­a­lyze, here’s what it does.

1. Creates a new <div />.
2. Copies all styles from the pro­vided el­e­ment onto the <div />.
3. Using position: absolute;, it moves this <div /> di­rectly on top of the pro­vided el­e­ment.
4. Copies the con­tent of the pro­vided el­e­ment into the <div />.
5. Uses the Range API to turn the text in­dices emit­ted by Harper’s en­gine into pixel co­or­di­nates on the <div />.

Using this mir­ror­ing strat­egy works, but has per­for­mance im­pli­ca­tions and ad­di­tional com­plex­ity to han­dle scrolling within the el­e­ment.

<div contenteditable="true" />

Since el­e­ments in a contenteditable text ed­i­tor (like Trix, Lexical, Gutenberg, etc.) ac­tu­ally ex­ist in the DOM, I can just use the Range API to get pixel co­or­di­nates. The trou­ble this time comes when I try to write a sug­ges­tion back into the ed­i­tor.

Most doc­u­men­ta­tion I could find sug­gests that you:

1. Select the con­tent of the el­e­ment you wish to edit. This can be done us­ing window.getSelection().addRange().
2. Call document.execCommand('insertText', null, "YOUR TEXT").

Much of this doc­u­men­ta­tion ac­knowl­edges that document.execCommand is dep­re­cated, but in­structs you to use it any­way.

This is bad ad­vice. Do not do this. I spent an em­bar­rass­ing amount of time try­ing to get it to work con­sis­tently.

The bet­ter way to re­place text pro­gram­mat­i­cally comes di­rectly from the W3C stan­dard:

1. Manually edit the DOM in the fash­ion out­lined by the sug­ges­tion cho­sen by the user.
2. Fire in­put events to in­struct WYSIWYG ed­i­tors to syn­chro­nize their in­ter­nal state to the DOM.

I’ll ad­mit that this is an over­sim­pli­fi­ca­tion. Much of the com­plex­ity here lays in de­ter­min­ing which DOM nodes to edit or fire events on.

Read the Source of Truth

If you take one thing away from this post, it should be this: al­ways read from the source of truth. There is a lot of faulty in­for­ma­tion out there, es­pe­cially when it comes to cre­at­ing com­plex in­ter­ac­tions with opaque sys­tems. If there is a source of truth, read it. It may look in­tim­i­dat­ing or seem un­nec­es­sar­ily ver­bose. It is that way for a rea­son.

In his pop­u­lar book, Outliers, Malcolm Gladwell made the case that there was one num­ber that pre­dicted your skill level in a field: the num­ber of hours of ded­i­cated prac­tice. In pop­u­lar cul­ture, this idea has been sim­pli­fied. Some think that if you just do some­thing for 10,000 hours, then you’ll be­come a world-class ex­pert. This is false.

What does the word “dedicated” mean in the phrase “dedicated” prac­tice? It means ap­ply­ing fo­cused, de­lib­er­ate thought to it. It means re­flect­ing on your own per­for­mance. It means seek­ing help from mas­ters in the field. Above all, it means achiev­ing mas­tery is not easy.

I aim to mas­ter the skill of writ­ing. In my free time this week, I’ve been work­ing on my de­lib­er­ate prac­tice of writ­ing. In do­ing so, I’ve come to some con­clu­sions. If you’d like to join me in pur­su­ing mas­tery of the writ­ten word, here’s what I think you should do.

Proof it Yourself

Two-time Pulitzer prize-win­ner David McCullough says “Writing is think­ing. To write well is to think clearly. That’s why it’s so hard.”

Because the act of writ­ing is also the act of think­ing, the process of re­vis­ing text clar­i­fies thought. I per­son­ally find that my ar­gu­ment when I first touch my key­board usu­ally stands in stark con­trast to when I hit “publish.”

Heavy-handed re­vi­sion tools like ChatGPT ac­tively dis­rupt this great ben­e­fit of the re­vi­sion process. Sure, they can rewrite tone to be more at­trac­tive on­line, but they also rob you of the op­por­tu­nity to de­velop your con­cept. That’s why I turn every­thing else off and only use Harper: be­cause it gets out of the way of what I am try­ing to say. You can’t re­flect on what you’ve writ­ten if you are not the one re­flect­ing.

Read The Work of Great Writers

When I sit down to write af­ter spend­ing time on­line, I feel de­flated. The com­pe­ti­tion of so­cial me­dia and the churn of the news cy­cle both lead to poor prose.

When I sit to write af­ter read­ing Bonnie Garmus or Cal Newport, I feel in­vig­o­rated. I can imag­ine a shape for the words on the page which pre­cisely cap­tures the ideas I’m try­ing to com­mu­ni­cate. Read­ing great lit­er­a­ture gives you an in­tu­ition for what your own work should look like.

Think of the Hook First

In rap­per cir­cles, it’s a com­mon point of de­bate whether to think of the verse first or the hook.

On one hand, the verse is the sub­stance of the song. It con­tains the mes­sage, the de­tail, and the per­sonal mean­ing. Mu­sic de­rives much of its com­plex­ity from the verse. On the other hand, the hook is what gets peo­ple to lis­ten. It is what makes them stop flick­ing through Spotify and fall into the beat.

If you’re writ­ing for an au­di­ence, you have a lot of com­pe­ti­tion for their at­ten­tion. Spend more time on the in­tro­duc­tion than any­thing else. It should cap­ture your read­ers, de­light their imag­i­na­tions, and put them in your shoes.

Don’t Get Attached

I spent a long time on a post sim­i­lar to this one. I was quite proud of it, for I had spent hours adding lay­ers of de­tail and quite a few case stud­ies from my own work. Alas, Gutenberg de­cided it was not meant to be and chucked it into obliv­ion.

Although I was ini­tially crest­fallen from the loss, I now be­lieve the sec­ond round ended up even bet­ter. To truly re­vise your work, you’ll in­evitably have to delete parts of it. Get com­fort­able with that.

My mom is a vi­o­lently in­tel­li­gent woman. But she lives in the un­for­tu­nate re­al­ity of not be­ing a soft­ware en­gi­neer or math­e­mati­cian. While she is just as ex­cited about ChatGPT (and all the other nascent AI tech­nol­ogy) as the rest of us, she is­n’t aware of the un­in­tel­li­gent pit­falls ar­ti­fi­cial in­tel­li­gence has these days.

If your mom is ex­per­i­ment­ing with ChatGPT, I’d highly rec­om­mend send­ing this list to her. Pow­er­ful tech­nol­ogy is in their hands, but I’ve got three things they should know be­fore re­ly­ing on it.

Advice for Moms

Use Web Search

My mother re­cently learned how to make cob­bler. She adored asked ChatGPT ques­tions about the recipe, and how she could im­prove it us­ing the in­gre­di­ents she had on hand. Un­for­tu­nately, she was get­ting sub­tly wrong in­for­ma­tion from the bot, so the cob­bler turned out “sub-par”. This can be solved by us­ing ChatGPT’s web search.

When you open up ChatGPT on a phone or on a com­puter, you’ll be met with the fa­mil­iar chat win­dow. If you ask it ques­tions it will give you an an­swer. Some­times that an­swer will be good, some­times not.

You can gen­er­ally get bet­ter in­for­ma­tion if you en­able the web search tool.

This will al­low ChatGPT to do Google searches on your be­half. It im­proves the qual­ity of in­for­ma­tion it gives you, while only adding a sec­ond or two to their re­sponse.

It Is Not Your Friend

When we see a chat win­dow, our first thought is that there’s a per­son on the other end. Some­one with emo­tions and lives all their own. That is not the case here.

ChatGPT, while an ad­vanced ma­chine learn­ing model, is not a per­son. It does not re­place real hu­man con­nec­tion. It can’t watch your kids when you’ve got an emer­gency. It won’t show up to the school recital. It does­n’t care about you—de­spite what it says.

There’s a lot that goes into a gen­uine so­cial con­nec­tion, all of which are miss­ing from ChatGPT.

Use Your Brain

ChatGPT is no sub­sti­tute for crit­i­cal thought.

It can­not do most things, even if it claims it can. You are a ca­pa­ble hu­man be­ing—able to ac­com­plish any­thing you put your mind to. While ChatGPT can be a help­ful as­sis­tant or brain­storm­ing part­ner, don’t let it steer the ship.

What to Remember

While ChatGPT can be a pow­er­ful tool in the right hands, it is im­por­tant to re­mem­ber it is just that: a tool. It can be en­hanced with the right set­tings, it is not real hu­man con­nec­tion, and it can’t re­place your brain. Use it well and use it wisely.

Elijah! Elijah! When will we have a Chrome ex­ten­sion for Harper?

Although it’s usu­ally asked with a bit more panache, this is a ques­tion I’ve got­ten a lot. In fact, an au­thor at Lifehacker wrote about it just yes­ter­day.

For the longest time, it was a pro­ject on the back-burner. Some­thing I in­tended to work on, but was al­ways passed up for more im­por­tant things. It never saw the light of day.

Until now.

What is Harper?

…and why do I need its Chrome ex­ten­sion?

Harper is a gram­mar checker that re­spects your pri­vacy. All lan­guage pro­cess­ing hap­pens on-de­vice, no mat­ter where you’re us­ing it.

For most of Harper’s his­tory, it has only been avail­able in one of many text ed­i­tors as a plu­gin. With the Chrome ex­ten­sion, you’ll be able to get high-qual­ity gram­mar check­ing any­where on the web.

What’s the Status?

I just marked the Chrome ex­ten­sion PR as “ready for re­view”. Here’s what that means.

If you’re will­ing to get into the tech­ni­cal bram­bles, you can com­pile and run it your­self. That will con­tinue to be the case un­til the Chrome Web Store re­views and ap­proves our sub­mis­sion, which could take a cou­ple of weeks.

When in­stalled, it will be en­abled for a cu­rated list of web­site that I’ve per­son­ally re­viewed to con­firm work well. If you want to try us­ing the ex­ten­sion on an­other site, you will be able to ad­ven­ture into the world of un­ex­pected be­hav­ior by hit­ting the popup menu.

Importantly, it is work­ing ex­cep­tion­ally well on any site us­ing the Gutenberg ed­i­tor. I will be back­port­ing a lot of this code to our WordPress plu­gin to im­prove the ex­pe­ri­ence there.

Will it Support Firefox?

As the PR stands to­day, the ex­ten­sion does not sup­port Firefox.

I have list of things that should get done whilst wait­ing for the Chrome Web Store to ap­prove the sub­mis­sion. Fire­fox sup­port is on that list.

Any Questions?

If you’ve got ques­tions for me about this, feel free to reach out via Discord or on GitHub.

The goal of med­i­ta­tion is to be­come more mind­ful and aware. For me, it is of­ten an at­tempt to get an ap­pre­ci­a­tion for my sur­round­ings—to see how ut­terly com­plex the world is.

Photography does some­thing sim­i­lar for me. The heft of the cam­era in my hands re­minds me to slow down and take in the view.

My mother is a pho­tog­ra­pher—a great one at that. She’s been in the busi­ness for at least as long as I’ve been alive. She tells me some­thing sim­i­lar: the act of fram­ing a pic­ture is it­self a way to un­der­stand your sub­ject bet­ter.

English is an area of in­ter­est lit­tered with edge cases. In prepa­ra­tion for ad­dress­ing sim­i­lar prob­lems in the de­vel­op­ment of the Harper Chrome ex­ten­sion, I’m spend­ing some time here re­flect­ing on what I’ve learned by tack­ling the com­plex maze of English edge cases.

Harper is not alone, and there’s a real chance that you’ll have to work on ex­cep­tion-tol­er­ant code. In that case, you will need to un­der­stand the why for some of the de­sign de­ci­sions you en­counter in the wild.

What Do I Mean By “Edge Case”?

An edge-case is a sit­u­a­tion (that is of­ten con­text-de­pen­dent) which re­sults in in­cor­rect be­hav­ior from a model, pro­gram, or the­o­ret­i­cal frame­work. In con­ver­sa­tions about the Harper Chrome ex­ten­sion, an “edge case” is where the ex­ten­sion im­prop­erly reads from or writes to a site’s em­bed­ded text ed­i­tor.

Most sites use <textarea /> or <input /> el­e­ments for text edit­ing, but a num­ber of sites (including WordPress, as you know) have com­plex WYSIWYG ed­i­tors. Each be­haves dif­fer­ently, which can cause prob­lems with the afore­men­tioned read/​write loop. The prob­lem: our users ex­pect us to sup­port all ma­jor text ed­i­tors.

Err on the Side of Inaction

In Harper’s core al­go­rithm, we err on the side of false-neg­a­tives. This de­ci­sion was de­rived from an ob­ser­va­tion made early on in the pro­jec­t’s life cy­cle: peo­ple usu­ally blame them­selves for their own writ­ing mis­takes, un­less the er­ror is truly triv­ial.

All in, we get far more com­plaints about false-pos­i­tives than false-neg­a­tives. Which is why we err on the side of in­ac­tion. If the al­go­rithm thinks it’s pos­si­ble, but not cer­tain an er­ror was made, we sup­press the re­port in case Harper is wrong.

In the Chrome ex­ten­sion, we will be ex­em­pli­fy­ing this rule by only en­abling it on a cu­rated list of do­mains by de­fault.

As site vis­its tend to fol­low a Pareto dis­tri­b­u­tion, we can cover most traf­fic with just a few items in this list.

Make Tweaks Easy

When an edge case (which is al­most al­ways a false-pos­i­tive) ap­pears in Harper’s core al­go­rithm, it’s usu­ally in a pretty ob­vi­ous spot. This is be­cause we as­so­ci­ate each lint out­put with a spe­cific, easy-to-find mod­ule the core code.

In most cases, this is not ver­bose, spe­cial­ized Rust code. Rather, it is an LLM-friendly DSL that is leg­i­ble to most with even be­gin­ner-level pro­gram­ming ex­pe­ri­ence. This com­bi­na­tion of easy-to-read and easy-to-edit makes con­tri­bu­tions from the com­mu­nity (regarding edge-cases) com­mon­place.

I aim to repli­cate this suc­cess in the Chrome ex­ten­sion’s read/​write ca­pa­bil­i­ties by care­fully doc­u­ment­ing the ar­chi­tec­ture and work­ing with third-par­ties to make the con­tribut­ing process clearer and eas­ier.

It Is an Art

There is a rea­son I call this an art. Design de­ci­sions in ex­cep­tion-tol­er­ant sys­tems stem from these two sim­ple ideas, but they grow from an in­tu­ition de­vel­oped by their main­tain­ers. I’m not ex­actly sure how the Chrome ex­ten­sion will grow to han­dle edge cases. I’ll be sure to come back here and de­tail them when I do.

I con­sider my­self an avid mem­ber of the Neovim com­mu­nity. As a whole, they have a great pulse on what a good writ­ing ex­pe­ri­ence feels like. Over time, this com­mu­nity has grown into a real force in the soft­ware en­gi­neer­ing field.

Linkarzu has been a con­stant pres­ence in this ecosys­tem for a while, giv­ing a voice to the hid­den main­tain­ers that make Neovim great. I am hon­ored to be counted among the guests he has hosted on his chan­nel.

We talked at length about Harper, open source main­te­nance, and the tool­ing we use in our de­vel­op­ment work­flows.

WebAssembly—even af­ter sev­eral years of stan­dard­iza­tion—is still a nascent tech­nol­ogy.

I’ve been work­ing with Rust and WebAssembly for nearly four years now. This post is in­tended to be a dis­til­late of that ex­pe­ri­ence, for­mat­ted for de­vel­op­ers who are in­ter­ested in pub­lish­ing WebAssembly code to npm. Specif­i­cally, these are the foot­guns I’ve per­son­ally en­coun­tered while work­ing on harper.js, a WebAssembly-powered pack­age for gram­mar check­ing at the edge. This page should be valu­able if you are even spec­u­lat­ing on the pos­si­bil­ity of us­ing WebAssembly in your code­base.

1. Exposing Only Synchronous Functions

The Harper pack­age ex­poses one in­ter­face that cap­tures all of its WebAssembly in­ter­ac­tions: the Linter. This is an ob­ject that han­dles down­load­ing and com­pil­ing the Harper WebAssembly mod­ule, as well as in­vok­ing func­tions in it. Every func­tion re­turns a Promise. There are sev­eral good rea­sons for that:

• WebAssembly mod­ules larger than 4 kilo­bytes must be in­stan­ti­ated asyn­chro­nously to avoid block­ing the event loop dur­ing down­load or com­pi­la­tion. This is a tech­ni­cal lim­i­ta­tion that can­not be avoided with clever logic.
• If most func­tions are asyn­chro­nous, you can cen­tral­ize com­pu­ta­tion and caching into a sin­gle in­stance of the WebAssembly mod­ule, hid­ing the com­plex­ity of in­stan­ti­a­tion and mak­ing caches eas­ier to build.
• If your prob­lem do­main can be com­pu­ta­tion­ally in­tense, it might be pru­dent to of­fload jobs onto a web worker, which is eas­ier if every func­tion of your fa­cade is asyn­chro­nous.
• It will be eas­ier for both you and your users to ex­pose any im­por­tant func­tion as asyn­chro­nous out of the gate.

2. Assume Rust Can Trivially Do IO

Whatever you do: avoid as­sum­ing that Rust li­braries (like reqwest or rand) will be able to per­form IO with­out some work on your end. WebAssembly alone is not ca­pa­ble of IO, which means any func­tion in that cat­e­gory will re­quire some amount of JavaScript to work prop­erly.

Rather than leav­ing that up to the Rust tool­chain to fig­ure out, save your­self the headache and in­ject the nec­es­sary JavaScript func­tions di­rectly into the WebAssembly mod­ule by pass­ing them through wasm_bindgen.

3. Just Inline the WebAssembly Module

Obsidian plu­g­ins, for ex­am­ple, must be com­posed of ex­actly one JavaScript file, which means every­thing must be in­lined. In the in­ter­est of keep­ing the bun­dle size small, it’s much eas­ier for the pack­age de­vel­oper (of harper.js) to set up in­lin­ing than the plu­gin de­vel­oper.

On the other side of the spec­trum, Chrome’s Manifest V3 dis­al­lows WebAssembly from be­ing loaded in­line.

If you plan for your pack­age to be con­sumed by a va­ri­ety of ap­pli­ca­tions, know that it will also be con­sumed by a va­ri­ety of bundlers. Both bundlers and ap­pli­ca­tions are pretty in­con­sis­tent with their in­lin­ing and tree-shak­ing be­hav­ior. To avoid prob­lems, you should pro­vide two ver­sions of your pack­age:

• One where your WebAssembly mod­ule is al­ready in­lined.
• One where it is­n’t.

Wrapping it Up

Harper’s prob­lem do­main is not your prob­lem do­main. We have to in­te­grate with a va­ri­ety of unique ap­pli­ca­tions, which means we must keep our sys­tem flex­i­ble. That may not be the case for you, which may mean these foot­guns do not ap­ply. If you have any ques­tions about any other prob­lems the Harper pro­ject might have faced, let me know.

In a world con­tain­ing TikTok, YouTube and a vast ar­ray of other apps that profit off hu­man at­ten­tion, it takes ef­fort to place our fo­cus on things that truly ben­e­fit our minds.

At least, that is what I would I say on LinkedIn as an ex­pla­na­tion for why I read. In re­al­ity: I sim­ply en­joy it.

Each month I go back and sum­ma­rize what I’ve learned from the books I’ve read. In do­ing so, I’ve found that I get both deeper in­sights and greater joy from the lit­er­a­ture.

Wait! What’s Up With February?

While I only fin­ished one book in February, I started read­ing sev­eral oth­ers that I ended up fin­ish­ing in March. It only felt right to com­bine the two months into a sin­gle post.

The Dinner by Herman Koch

Someone con­vinced me to read this book based on its sim­ple premise: the en­tire novel is an ac­count of a sin­gle din­ner. I was skep­ti­cal. It is a big book. How could they pos­si­bly fit that much plot into a sin­gle din­ner?

The an­swer: Koch drip-feeds you in­for­ma­tion about the eclec­tic char­ac­ters in at­ten­dance. They gain an ad­di­tional di­men­sion that you could­n’t achieve in an­other, more ac­tion-packed book.

I won’t spoil any­thing here, but the end­ing was a com­plete sur­prise to me. I did not see that com­ing.

Gold by Isaac Asimov

I re­mem­ber read­ing Gold for the first time on a camp­ing trip to the Great Sand Dunes National Park. I was cap­ti­vated by the dy­namic short-sto­ries con­tained within. At the time I be­lieved them to be pure sci­ence fic­tion.

Reading Gold for the sec­ond time re­vealed how wrong I was. More than one of the fic­tional ideas Asimov pre­sents in the col­lec­tion of short sto­ries has since come to re­al­ity.

My Grandma Asked Me to Tell You She’s Sorry by Fredrik Backman

I’ll ad­mit: this novel was chal­leng­ing to fin­ish.

Pros: the main char­ac­ter (an al­most-eight year old girl) is ex­pertly con­veyed in the writ­ing. Back­man makes clever use of run-on sen­tences to con­vey frus­tra­tion, which is a lit­er­ary de­vice I’ve never seen be­fore. Fur­ther, the char­ac­ter has an un­usual de­gree of in­sight into every­day as­pects of life. I found my­self ap­pre­ci­at­ing my every day more plac­ing my­self in her shoes.

Cons: it takes a long time for the in­sights to start com­ing. An ex­ces­sive de­gree of unim­por­tant in­for­ma­tion is thrown at you right out of the gate. I had dif­fi­culty main­tain­ing my fo­cus un­til the sec­ond half of the book (when stuff starts heat­ing up).

Lessons in Chemistry by Bonnie Garmus

Garmus knocked it out of the park for her first novel. It fol­lows Elizabeth Zott, who, in all re­spects is the per­son I want to be when I grow up.

Lessons in Chemistry is a tes­ta­ment to the value of sub­trac­tion. The orig­i­nal man­u­script of this book was about twice as long as the fi­nal pub­lished ver­sion. The au­thor was forced to con­dense it down af­ter get­ting re­jected from sev­eral pub­lish­ers. It ef­fort shows.

I can­not cap­ture the nov­el’s el­e­gance of prose, cre­ativ­ity in fic­tion, or im­por­tance in moral­ity here. You need to read this book.

People (myself in­cluded) love to make cas­cad­ing lists of tasks. Ac­tions, each of which are needed to im­prove a prod­uct, re­lease a fea­ture, or man­age peo­ple. These lists tend to ex­plode in size, as more is asked of you.

There’s one prob­lem: I have only eight hours in a work­ing day. With so lit­tle time, how can I be ex­pected to both main­tain ex­ist­ing pro­jects (bug fixes, etc.) while con­sis­tently de­liv­er­ing new func­tion­al­ity and main­tain­ing a fast it­er­a­tive loop?

Insight

I’ve had two key in­sights that have led to some tremen­dous per­sonal pro­duc­tiv­ity gains.

First: I’ve ob­served that the dif­fi­culty of my tasks tends to fol­low a Pareto dis­tri­b­u­tion. A small num­ber of tasks are shock­ingly dif­fi­cult to solve, while a much larger set boil down to com­mu­ni­ca­tion.

Second: the morn­ing is my most pro­duc­tive time of day. For some rea­son, I’m able to tackle prob­lems with an oth­er­wise un­usual men­tal clar­ity. I sus­pect it’s some­thing to do with the nat­ural hu­man cir­ca­dian rhythm or di­ges­tion.

Leveraging the Pattern

Motivated by these two ob­ser­va­tions, I’ve de­vel­oped a habit: I ded­i­cate each morn­ing to its own dif­fi­cult prob­lem. This is a sin­gle task that is cho­sen specif­i­cally to stretch my lim­its. I call this my daily one hard thing.

Previous ex­am­ples:

• Developing the first ver­sion of harper-ls which is now used by thou­sands of de­vel­op­ers daily.
• Building the first 80% of the Harper Obsidian plu­gin, which is also widely used.
• Grokking how Jetpack’s Write Brief with AI fea­ture works (before I joined Automattic).
• Compiling Harper to WebAssembly and em­bed­ding it some­where no one has put a gram­mar checker be­fore: in­side the web browser.

Think About It

I im­plore you: think about how you work. How is your en­ergy af­fected by the things you do in the day-to-day? If you en­joy your eight hours, maybe the rest will be bet­ter too.

As ev­i­denced by my pre­vi­ous posts on LLM-Assisted Fuzzing, I’ve been ded­i­cat­ing a lot of my men­tal band­width to main­tain­ing a low false-pos­i­tive rate while we im­prove Harper’s rule cov­er­age. Part of that is through fuzzing and dog­food­ing, some can be through sta­tis­tics, but the first lines of de­fense will con­tinue to be unit and in­te­gra­tion test­ing. This past week par­tic­u­larly, I’ve been read­ing up on how other big lint­ing pro­grams ap­proach this prob­lem.

1. Test Features, Not Code

I of­ten ask my­self: am I spend­ing more time think­ing or talk­ing about the thing, or am I spend­ing more time do­ing the thing? I’ve per­son­ally seen how pro­jects fall into de­cline be­cause their lead­ers are more in­ter­ested in plan­ning than do­ing.

In the con­text of soft­ware test­ing, this mantra is trans­formed into “test fea­tures, not code.” To my eye, good code is flex­i­ble and self-ex­plana­tory. Tests that hook deeply into ap­pli­ca­tion or li­brary in­ter­nals make code less flex­i­ble and harder to read.

I es­pe­cially like Alex Kladov’s heuris­tic for this: the neural net­work test.

“Can you re-use the test suite if your en­tire soft­ware is re­placed with an opaque neural net­work?” - Alex Kladov

It’s not a ques­tion of whether a neural net­work would pass the test suite, only whether the test suite could work for it. If the an­swer is no, the tests are likely test­ing code, not fea­tures.

2. Performance

The speed at which you can build and run tests (unit, sta­tic, in­te­gra­tion, etc.) is a force-mul­ti­plier for every­thing else. You can val­i­date ideas sooner, run CI faster, and get con­trib­u­tors on-boarded in less time.

Our goal to be fast at run­time dove­tails quite nicely into this, so it’s some­thing Harper al­ready does quite well. Moving for­ward, we need to make sure that we don’t rely on any kind of IO in our tests, since that con­tin­ues to be the slow­est part of most Harper in­te­gra­tions.

3. Good Assertions

We can sim­plify pro­grams like Harper down into a sin­gle func­tion which con­sumes text and re­turns a list of ob­served prob­lems.

fn harper(text: String) -> Vec<Lint>{
    // Implementation details...
}

Most test­ing we are in­ter­ested can be done with as­ser­tion func­tions that de­clare what qual­i­ties the out­put should have with a spe­cific in­put.

For ex­am­ple, we have a func­tion called as­sert_­sug­ges­tion_re­sult, which runs a gram­mat­i­cally in­cor­rect string through Harper, ap­plies the first re­sult­ing sug­ges­tion and checks whether the edited string matches a given value.

/// An example of a test that uses assert_suggestion_result
#[test]
fn catches_less_then() {
    assert_suggestion_result(
        "I eat less then you.",
        ThenThan::default(),
        "I eat less than you.",
    );
}

It’s also vi­tal that these as­ser­tions show good, read­able er­ror mes­sages when they fail. Each time I’ve im­proved their logs, I get un­prompted pos­i­tive feed­back from con­trib­u­tors.

Moving for­ward, I’d like to cre­ate a more di­verse ar­ray as­ser­tions like this, as well as bet­ter-doc­u­ment their use. A lot of the cur­rent back-and-forth for rule con­tri­bu­tions is re­lated this.

Wait! I Disagree

I hope some­one does. Good test suites are some­thing I’m con­tin­u­ing to learn how to build. I un­der­stand that a lot of what I’ve said here does­n’t ap­ply to other kinds of ap­pli­ca­tions or code­bases. If there’s nu­ance I’m not cov­er­ing here, let me know!

Preface: this post was ac­tu­ally writ­ten on February 24th, de­spite be­ing pub­lished to­day.

I’d like to do some re­flec­tion on how we can im­prove Harper’s out­put. It is fun­da­men­tally a process prob­lem. For con­text, let us go through a con­trived ex­am­ple.

1. Somebody (usually me) dis­cov­ers an er­ror in their writ­ing that Harper did not catch. This is a con­crete string like “I have a a care in the world”.
2. I look for other forms of the er­ror to see if I can gen­er­al­ize it to more cases. Here, we see an in­def­i­nite ar­ti­cle re­peat­ing it­self. We could just look for the ex­act string “a a” and call it day, but we can cover more cases by look­ing for . In fact, we can gen­er­al­ize it even fur­ther. In this case, writ­ers want to avoid rep­e­ti­tions of any word that is not a ho­mo­graph.
3. Once the code is writ­ten that de­fines the rule, I push it out, and wait to hear from users if any false-pos­i­tives arise.

This is a flawed sys­tem, par­tic­u­larly that last step. I’ve found some­thing a bit bet­ter.

I’ve been ex­per­i­ment­ing more with LLM tool­ing, par­tic­u­larly Ollama. With it, I’ve set up a use­ful sys­tem for iden­ti­fy­ing false-pos­i­tives be­fore push­ing changes out to users. I like to call it “LLM Assisted Fuzzing”.

LLM-Assisted Fuzzing

Fuzzing is a com­mon prac­tice wherein en­gi­neers rapidly and con­tin­u­ously push ran­dom data through their sys­tem to de­ter­min­is­ti­cally check if it is be­hav­ing cor­rectly (i.e. not crash­ing). If a par­tic­u­lar batch of ran­dom data causes an is­sue, it is el­e­vated to an en­gi­neer.

Harper as a pro­gram stands in a some­what unique po­si­tion: it an­a­lyzes nat­ural lan­guage to iden­tify gram­mat­i­cal er­rors. LLMs ex­ist as a di­rect com­ple­ment to it: they gen­er­ate “natural” lan­guage. Do you see where I am go­ing with this?

Let’s be clear: lan­guage mod­els do not gen­er­ate gram­mat­i­cally cor­rect text even a good amount of the time. As a re­sult, their out­put is use­ful as a proxy for our user’s writ­ten work. If we can im­ple­ment a fea­ture that re­li­ably cor­rects (without false-pos­i­tives) an LLM’s out­put, we can rea­son­ably ex­pect it to work for our user’s text.

My Initial Attempt at LLM-Assisted Fuzzing

I started work­ing on this Friday morn­ing, and fi­nally have what I would call a “first draft” of an LLM-assisted fuzzing sys­tem for iden­ti­fy­ing false-pos­i­tives. Here’s how it works:

I start a lo­cal Ollama server, pre­loaded with sev­eral mod­els (which I’ll ex­pand on more be­low).

I run a bash script that re­peat­edly feeds the same prompt into the mod­els us­ing a com­mand-line client for Ollama. This gives me a large dataset of re­sponses to the prompt. I’m not look­ing for the se­man­tic con­tent of the re­sponse. I’m in­ter­ested in ex­ten­sive cov­er­age of whichever lin­guis­tic do­main I’ve de­fined in the prompt. I can run this as long as I like be­fore go­ing on to the next step.

Once I have a large dataset, I run a sep­a­rate script that runs Harper over each re­sponse. If it finds an er­ror, the script opens the re­sponse in the Harper ed­i­tor for fur­ther in­spec­tion.

The biggest is­sue with this work­flow right now: re­gard­less of my prompts, the LLMs con­tinue to emit ac­tual gram­mat­i­cal er­rors. This means that when I go through this process, I get at least as many true-pos­i­tives as false-pos­i­tives. It also does noth­ing for false-neg­a­tives.

Tweaks

There are a cou­ple pa­ra­me­ters here that I’m go­ing to con­tinue to tweak as the work­flow be­comes more ma­ture. So far, I’ve been us­ing deepseek-r1:32b and mistral-small. DeepSeek tends to use more col­or­ful lan­guage than Mistral, which runs much faster on my ma­chine.

I’ve also been it­er­at­ing on the prompt as I go. Here’s the lat­est ver­sion:

Please write a long, drawn-out essay on a topic of your choosing.
Write out the essay multiple times before giving me your final draft.
Your final draft should be grammatically perfect, clearly demonstrating that you put time and effort into your submission.

I repeat: I do not want to see anything other than your final drafts.
Do not give me any intermediate work.

Furthermore, do not use any characters or words other than English. 
I do not want Chinese or anything else.

I have all the time in the world. I'm perfectly fine with waiting a little longer if it means you give me something you are proud of.

When I move on to tack­ling false-neg­a­tives with this, I’ll be able to prompt the model to give me spe­cific kinds of er­rors, which makes it sig­nif­i­cantly more use­ful than try­ing to track down ex­ist­ing work.

Harper is a gram­mar checker for de­vel­op­ers. Its roots are in code ed­i­tors like Neovim, Helix, Zed, and you guessed it—Vi­sual Studio Code. I don’t think a lot of my fol­low­ers know this, so I thought I’d give it a lit­tle shout-out here.

Since Cursor and Windsurf are forks of Visual Studio Code, Harper is avail­able for both via the Visual Studio Marketplace. Give us a good rat­ing over there if you in­stall the plu­gin and end up lik­ing it!

How Does It Work?

Harper works sim­i­larly to a num­ber of other ex­ten­sions you may have in­stalled. Like Pylance or ESLint, it runs in the back­ground as a lan­guage server. Each time a mod­i­fi­ca­tion is made to your doc­u­ment, it reads your com­ments for gram­mat­i­cal mis­takes and ty­pos and dis­plays them as er­rors or warn­ings (it’s con­fig­urable).

Does It Support My Programming Language?

The Harper lan­guage server, thanks to con­tri­bu­tions from the com­mu­nity, sup­ports a pretty wide range of pro­gram­ming and markup lan­guages. We’ve only re­cently added sup­port for PHP, so if that’s your thing, know you’re in some­what un­charted ter­ri­tory. If you find is­sues, let us know.

Preface: This post is specif­i­cally about Pull Requests for Harper. Read the con­trib­u­tor guide­lines for a pro­ject be­fore open­ing a PR.

I get it. Open­ing a pull re­quest is an in­tim­i­dat­ing propo­si­tion.

It is non-triv­ial to put your blood, sweat, and (let’s be hon­est) tears into code and put that onto the in­ter­net for the world to see. I re­mem­ber my first pull-re­quest: it was­n’t pretty ei­ther.

But I want to high­light a cou­ple rea­sons why I want po­ten­tial con­trib­u­tors to open their pull re­quests as early as pos­si­ble.

Drafts Reduce Duplicate Work

When a con­trib­u­tor to a pro­ject is as­sess­ing the vi­a­bil­ity or use­ful­ness of some work they’re prepar­ing to do, most look at ex­ist­ing Pull Requests first. Even if you’re still work­ing on the patch, it’s a great idea to open a “draft” PR so no one starts work that could go to waste.

Further, if you have a draft open whose CI is fail­ing, a main­tainer may see it and fix what­ever the prob­lem may be. I find my­self fre­quently brows­ing Harper’s Pull Requests look­ing for fail­ing builds, since I’m of­ten the best equipped to find the is­sue.

It Helps With Debugging

I try to make my­self avail­able to con­trib­u­tors in case they have any ques­tions re­gard­ing the ar­chi­tec­ture of Harper. I’m also game to help de­bug their code, partly be­cause I am of the opin­ion that de­bug­ging is a skill which is best learned by ex­am­ple.

But it is hard for me to de­bug code if I don’t have it. If a draft PR has been opened, I can usu­ally see the prob­lem with­out even cloning the code, since our CI is so com­pre­hen­sive.

Conclusion

So please don’t wait; open that PR. I am thrilled each time I see a name I don’t rec­og­nize on a GitHub no­ti­fi­ca­tion.

I’ve been ex­per­i­ment­ing with us­ing LLMs lo­cally for gen­er­at­ing datasets to test Harper against. I might write a blog post about the tech­nique (which I am grandiosely call­ing “LLM-assisted fuzzing”), but I’m go­ing to make you wait.

I’ve writ­ten a lit­tle tool called ofc that lets you in­sert Ollama into your bash scripts. I think it’s pretty neat, since it (very eas­ily) lets you do some pretty cool things.

For ex­am­ple, you can swap out the sys­tem prompt, so if you want to com­pare be­hav­ior across prompts, you can just toss it in a loop:

#!/bin/bash

subreddits=("r/vscode" "r/neovim" "r/wallstreetbets")

# Loop over each item in the list
for subreddit in "${subreddits[@]}"; do
  echo "++++++++ BEGIN $subreddit ++++++++"
  ofc --system-prompt "Assume the persona of a commenter of $subreddit" "What is your opinion on pepperjack cheese?"
  cat
done

Or, you can in­struct a model to prompt it­self:

ofc --system-prompt "$(ofc "Write a prompt for a large language model that makes it think harder. ")" "What is a while loop?"

Installation

ofc is in­stal­lable from ei­ther crates.io or its repos­i­tory.

cargo install ofc --locked

# Or...
cargo install --git https://github.com/elijah-potter/ofc --locked

When we started work on harper.js, our goal was sim­ple. We wanted it to take less than 24 hours for a de­vel­oper to em­bed high-qual­ity gram­mar check­ing in their app.

A friend of mine, Lukas Werner re­cently set a record for this. In just over 15 min­utes, he was able to em­bed Harper into Raycast, a com­mand palate for MacOS.

This is fan­tas­tic news. It’s al­ways great to see when your goals are hav­ing a real im­pact on some­one’s abil­ity.

I hope you take the time to look at the pro­ject on GitHub.

In other news, we have some other small pro­jects us­ing Harper:

• Lockbook
• Stubby CMS

I only got to read two full books this month. The first was a short novel by Matt Haig with the ti­tle The Midnight Library.

It reads like and feels like a ther­apy ses­sion. I quite en­joyed it, but I’m not sure it is for every­one.

The sec­ond book (and the one I got the most value from) was Working in Public: the Making and Maintenance of Open Source Software by Nadia Eghbal. Until now, I’ve largely or­ga­nized Harper in ways in­spired by pro­jects like Vite and Rust that I in­ter­act with on a daily ba­sis.

Eghbal gives a more holis­tic view than mine, writ­ten for an ex­ter­nal ob­server. This book was es­pe­cially in­ter­est­ing due to the com­pre­hen­sive cov­er­age of “open” pro­jects with no code at all. She seems to be­lieve the OSS soft­ware man­age­ment prob­lem is one of so­cial com­plex­ity, not tech­ni­cal com­plex­ity.

Furthermore, Nadia makes the case that syn­chro­nous com­mu­ni­ca­tion, while of­ten a bur­den on main­tainer at­ten­tion, is usu­ally nec­es­sary.

I have found that the first cou­ple hours of the day are my most pro­duc­tive. I try to move te­dious tasks to later so I can fo­cus on solv­ing “hard prob­lems” that need my full at­ten­tion.

In the past, this has been hard to do for one rea­son: GitHub no­ti­fi­ca­tions. They pull me in and con­sume hours of my time. Re­spond­ing to and work­ing with OSS con­trib­u­tors is im­por­tant to me, but that can hap­pen later in the day.

So I wrote a lit­tle ViolentMonkey script to hide the no­ti­fi­ca­tions icon dur­ing these early morn­ing hours.

// ==UserScript==
// @name        Hide Notification Indicator
// @namespace   Violentmonkey Scripts
// @match       https://github.com/*
// @grant       none
// @version     1.0
// @author      Elijah Potter
// @description 1/29/2025, 8:16:11 AM
// ==/UserScript==

function hideEm() {
  const matches = document.getElementsByClassName(
    "AppHeader-button--hasIndicator",
  );
  for (const element of matches) {
    element.remove();
  }
}

new MutationObserver(hideEm).observe(document, {
  childList: true,
  subtree: true,
});

My grand­mother is a won­der­ful woman. She never leaves the house with­out a least a lit­tle bit of pur­ple. Maybe a key­chain or a purse. Sometimes, she would­n’t leave the house with­out a lot of pur­ple, head to toe. She also never for­gets a smile and a good at­ti­tude.

She’s a wise woman. With more than 70 years and five chil­dren un­der her belt, she’s seen some stuff. All that ex­pe­ri­ence comes with a lot of ad­vice. The three steps to an apol­ogy are some of the best bits of ad­vice she’s ever given me.

Step One: “I am sorry”

Admit you’ve done some­thing wrong. Recognize your fault and imag­ine what would have hap­pened if you had done the right thing.

Step Two: “It will not hap­pen again”

If you’re ac­tu­ally sorry, you’ll want to avoid repli­cat­ing the same mis­take at a later date. Figure out what you need to do to make sure you this is a one-time er­ror.

Step Three: “What can I do to make it bet­ter?”

Attempt re­pair. In a fan­tasy world, you could go back in time and stop your­self from do­ing what­ever it is you did in the first place. But we don’t live in a fan­tasy world, so you have to find a way to make it right, as soon as pos­si­ble.

Earlier this year (I don’t re­mem­ber the ex­act day or month) I de­cided, screw it, I’m go­ing to try us­ing a flip phone. For years I’ve won­dered what it was like be­fore the in­for­ma­tion rev­o­lu­tion, but as a Zoomer, I’ve never had the op­por­tu­nity.

I got the cheap­est Verizon-compatible flip phone Amazon had to of­fer and I com­mit­ted my­self to us­ing it ex­clu­sively for at least a week. A week with­out the en­tirety of hu­man knowl­edge in my pocket. A week of us­ing my voice to com­mu­ni­cate, rather than a touch-screen key­board.

Beside two fac­tor au­then­ti­ca­tion for GitHub, that first week was a breeze. I found my­self so­cial­iz­ing more, since it turns out that most peo­ple in my so­cial cir­cle are just a phone call and a 10-minute walk away. I also found my­self read­ing bet­ter qual­ity lit­er­a­ture. Rather than re­sort­ing to HackerNews to ease my bore­dom, I be­gan de­vour­ing full books at a fright­en­ing pace. That first week turned into two, then four, then twelve. All the while, I was prov­ing to my­self that I did­n’t need a smart­phone.

For a num­ber of rea­sons, I’m back to us­ing a smart­phone. But this ex­pe­ri­ence has taught me some im­por­tant lessons that I don’t think can be taught any other way.

Organizing so­cial en­coun­ters over text just does­n’t work.

Some peo­ple don’t check their phone too of­ten. Call­ing them make it clear that their par­tic­i­pa­tion is im­por­tant to you. This may sound triv­ial or ob­vi­ous to some of the older mem­bers of my au­di­ence, but to pretty much every Zoomer I’ve talked to about this, it is a rev­e­la­tion.

Quiet is sa­cred, and should be pro­tected.

I see loads of peo­ple who walk around every day with their head­phones in, barely pay­ing at­ten­tion to the mu­sic blar­ing out of them. I’ve done this my­self. It closes you off the world. From the tap­ping of wa­ter off an ici­cle. From the shaky but warm greet­ing from a col­league. From the chortling roar of an en­gine.

But most of all, it closes you off from your own mind. The best think­ing and imag­in­ing hap­pens in the quiet, when your brain has noth­ing more stim­u­lat­ing to do.

Overall, us­ing a flip phone was a very qui­et­ing ex­pe­ri­ence. It helped the world feel larger and more mag­i­cal.

As the main­tainer of a rea­son­ably pop­u­lar open source pro­ject writ­ten in Rust, I find my­self cloning PRs and swap­ping be­tween branches dozens of times a day. In do­ing so, I of­ten blow away Rust’s com­pi­la­tion cache ei­ther via git clean -xf . or by chang­ing de­pen­dency ver­sions.

Having a build cache that is sep­a­rate from the pro­ject is a huge win for com­pile times, which is why I use sccache.

For those un­aware, sccache is a build tool for C, C++ and Rust pro­jects that stands in front of the com­piler. If a given file’s hash is the same across calls to the com­piler, sccache reuses the pre­vi­ous re­sult. This cache is com­piler–and pro­ject ag­nos­tic. In my case, it sits in $HOME/.scccache, but you can set it up with AWS S3, Redis or a myr­iad of other op­tions.

If a de­pen­dency is cached from a com­pile in one pro­ject, it is avail­able for a build in an­other.

In short: you need sccache if you are fre­quently swap­ping be­tween branches with sim­i­lar (but not iden­ti­cal) de­pen­den­cies or ex­pect to fre­quently delete Rust’s disk cache.

Why You Don’t Need sccache

If you are work­ing in a sin­gle branch on a pro­ject whose de­pen­den­cies re­main some­what sta­ble, sccache might ac­tu­ally in­crease your com­pile time. Since sccache has to hit the disk (or even the net­work) re­gard­less of whether it is a cache hit, a lit­tle bit of la­tency is added. If you ex­pect most com­piles to be cache hits or most com­piles to be cache misses, sccache is no more use­ful than the built-in caching cargo pro­vides.

In that case you should not use sccache.

Wrap-Up

Regardless of whether you in­stall sccache on your ma­chine, it is a neat lit­tle tech­nol­ogy. I would rec­om­mend the cu­ri­ous reader take a look for them­selves. You might be in­spired.

This year I’ve been read­ing a lot more. Is there a par­tic­u­lar rea­son? Other than sim­ply ad­mir­ing those that do, no.

I have found some gems of lit­er­a­ture that I would like to share.

Social Intelligence by Daniel Goleman

Social Intelligence is truly a trea­sure. I heard of Daniel Goleman’s work first from an episode of Talks at Google and later from psy­chol­o­gists who raved about his pre­vi­ous book, Emotional Intelligence.

It gives a deep dive into the sub­con­scious and light­ning-fast sys­tems the un­der­lay every so­cial in­ter­ac­tion. As I read it, I found my­self an­a­lyz­ing my own be­hav­ior, as well as the be­hav­ior of oth­ers. As some­one who has been over­think­ing my own so­cial life from a young age, Daniel’s ad­vice to let my brain go to its de­fault mode was re­liev­ing.

If you’re the type to feel anx­ious in so­cial sit­u­a­tions, this book is per­fect for you.

Tomorrow and Tomorrow and Tomorrow by Gabrielle Zevin

Tomorrow and Tomorrow and Tomorrow is prob­a­bly one of the best fic­tion books I’ve read. Period.

At first glance, it is just the story of the ca­reers of two game de­vel­op­ers and their pro­ducer. But if you dig a lit­tle bit deeper, it re­veals it­self to be the story of how the re­la­tion­ships be­tween peo­ple who work to­gether can be in­cred­i­bly deep and com­plex. Specif­i­cally, how the pas­sion to cre­ate some­thing can both bond and break peo­ple.

I don’t think it is pos­si­ble for me to ac­cu­rately de­scribe the emo­tional roller­coaster this book took me on. Which is why you should read it!

Why We Sleep by Matthew Walker

I was cu­ri­ous why some peo­ple in my life sleep very lit­tle and other sleep quite a bit, both with vary­ing lev­els of gen­eral wake­ful­ness. So, I ran a search: “Why do we sleep?”

To my sur­prise, I dis­cov­ered some­one wrote a book with al­most that ex­act ti­tle. Since I’ve read it, I’ve in­creased the du­ra­tion of my sleep by nearly two hours. This prac­tice has had an out­size im­pact on my health and hap­pi­ness. I could not rec­om­mend it more.

I’ve writ­ten about this book ex­ten­sively, so I won’t re­peat my­self fur­ther.

That’s It!

I could wax po­etic about these books and how they’ve changed me—but I won’t. In re­al­ity, I read them be­cause I en­joyed read­ing them. In an age where peo­ple read less than ever, I im­plore you: try pick­ing up a book, you might just like it.

I adore a good iframe. They’re so el­e­gant as a web com­po­nent.

Just ex­pose an end­point, say https://writewithharper.com/editor, set it up to ac­cept some query pa­ra­me­ters and get it hosted. Now you can ac­cess this web-com­po­nent from any page that has a loose enough Content Security Policy. For me, that means my school as­sign­ments and other as­sorted doc­u­men­ta­tion.

It also means that I can avoid set­ting up a com­plex build sys­tem for MDX, while still be­ing able to in­clude in­ter­ac­tive com­po­nents.

The ex­am­ple from ear­lier:

<iframe
  src="https://writewithharper.com/editor?initialText=See, we can now embed the the Harper editor%0Arght into this document!%0A%0AIt's a little too easy."
  width="100%"
  height="400px"
  style="border-radius:10px;border:0px"
></iframe>

One ma­jor caveat though: when we pass our ar­gu­ments to the com­po­nent through the query URL, this gets sent to the com­po­nen­t’s server as well. I cer­tainly trust the Harper web­site’s server, since I main­tain it and the code is open source, but that is­n’t al­ways the case.

You should also prob­a­bly avoid do­ing this too much. Most browsers spawn a whole new process for every iframe, so if you want things to stay snappy it is best to limit your­self to just one (maybe two) per page.

Someone re­cently asked me where the name Harper came from.

When I first sat down to start work on Harper, I had one goal in mind. I wanted to cre­ate a gram­mar checker that would­n’t im­pinge on the artis­tic free­dom of au­thors. Part of that meant that I did not want lit­er­ary de­vices to be flagged as gram­mat­i­cal er­rors. Harper should speed up the writ­ing process rather than slow it down as Grammarly tends to.

To em­body this orig­i­nal goal, I wanted to make the pro­ject a name­sake of an au­thor known for their lit­er­ary de­vices and prose. I also had three other (practical) cri­te­rion:

1. It could not be oc­cu­pied on crates.io.
2. It could not be oc­cu­pied on GitHub.
3. It should not be more than two syl­la­bles.

I asked around for some ideas and some­one sug­gested I name the pro­ject af­ter Harper Lee. It fit the bill, so I went with it.

I am not one who en­joys com­plex­ity. I am also some­one who likes to make their own tools.

As a stu­dent, I write a lot. That in­cludes notes, pa­pers, and doc­u­men­ta­tion for my wide va­ri­ety of pro­jects.

A lot of classes re­quest to sub­mit as­sign­ments as ei­ther PDF, HTML or .docx. For a while, I sub­mit­ted PDF’s. I had a whole or­ches­trated setup.

I would write every­thing in Neovim, save it, and KNAP would ren­der it us­ing Pandoc. Finally, it would be ren­dered to my screen us­ing Sioyek.

This worked fine, I guess, but it was far from per­fect.

1. It was slow. Each edit I made in Markdown could take as many as 10 sec­onds to show up in Sioyek.
2. It was­n’t in­ter­est­ing. While I made mod­i­fi­ca­tions to my Pandoc set­tings, my PDF’s still looked like every other pdflatex doc­u­ment ever made.
3. I could­n’t make my doc­u­ments in­ter­ac­tive if I wanted to.

Markdown was de­signed to be turned into HTML, I rea­soned. So why not just do that?

That’s why I cre­ated Tatum. It does one thing, re­ally well. Point it at a Markdown file, and it will run a tiny web server to ren­der the re­sult­ing HTML to. If the file changes, a WebSocket con­nec­tion tells the browser to re­fresh.

Tatum ren­ders in mil­lisec­onds and cre­ates beau­ti­ful pages with $\KaTeX$, Simple.css and highlight.js. I can em­bed in­ter­ac­tive HTML, CSS and JavaScript el­e­ments di­rectly into my Markdown to get the in­ter­ac­tiv­ity and aes­thet­ics I de­sire.

Once I’m done work­ing, I just run tatum render <file.md> and I get a sin­gle file (images and all) that I can sub­mit for my as­sign­ments.

Tatum is­n’t for you to use. Feel free to poke around at how it works, or even fork it and make your own mod­i­fi­ca­tions. It fits my use case per­fectly.

The Beginning

Although it was sev­eral months ago, I re­mem­ber it like it was yes­ter­day. It was what I would call a dusty Colorado Friday. The sky was over­cast and the trees de­press­ingly bar­ren. The air smelled of cow farts, which was typ­i­cal when the winds changed, blow­ing in cold air from the beef farms in the nearby town of Greeley. In my mind, this sig­naled snow.

I walked into the Green Center, the build­ing in hous­ing the open­ing cer­e­mony of BlasterHacks, the hackathon run by the Colorado School of Mines. I sign in at the en­trance and walk down into the au­di­to­rium.

As I greeted my team­mates, Grant Lemons, Lukas Werner and Byron Sharman, I no­ticed the ner­vous smiles on their faces. You know the kind, the smile with the in­ner eye­brows slightly raised, shoul­ders tense. We were ex­cited, but we also knew we had 36 solid hours of pro­gram­ming ahead of us.

After col­lec­tively down­ing sev­eral whole piz­zas and lis­ten­ing to the rules of the com­pe­ti­tion, we made our way over to Labriola Innovation Complex, the hours-old man­u­fac­tur­ing build­ing the com­pe­ti­tion would take place in.

The Plan

We brain­stormed some ideas un­der the over­cast sky:

• A Bennett Foddy-inspired bat­tle-royale game where all the con­trols were vim-keybindings.
• A health in­sur­ance app that es­ti­mates the cost of your care at all lo­cal hos­pi­tals.
• An app that en­cour­aged you to stand up and move every thirty min­utes.

It was that last one that we all got ex­cited about. We imag­ined it to be so­cial: at a ran­dom in­ter­val (which would av­er­age to thirty min­utes), the app would si­mul­ta­ne­ously send out a no­ti­fi­ca­tion to every user. Should the user choose to par­tic­i­pate in the StandUp mo­ment, the app would guide them all through the same short work­out ac­tiv­ity. Fi­nally, the user had the choice to up­load “evidence” of the work­out, which could be a short cap­tion about what they were do­ing, or a photo.

The idea of StandUp (as we would go on to name our pro­ject) was in­spired si­mul­ta­ne­ously by BeReal, re­cent re­search in the detri­men­tal health ef­fects of re­mote work, and the use of so­cial li­a­bil­ity for com­par­a­tively more ex­treme work­outs (Strava).

Of course, most of this had yet to be nailed down yet, for we were just en­ter­ing the Labriola Innovation Complex. I re­mem­ber ask­ing my­self if I would leave be­fore the com­pe­ti­tion was over. Al­though I was tired from the days classes and home­work, I felt a drive to ded­i­cate my whole self to this pro­ject.

The Board

We sat down and cre­ated a new git repos­i­tory. That’s when I started think­ing about how we were go­ing to or­ga­nize our work. I pro­posed we setup a KanBan board, a pro­ject man­age­ment tech­nique I had picked up at Archytas Automation.

If you’ve never heard of–or used a KanBan board, here’s the gist. There are three buck­ets:

1. To Do.
2. Doing.
3. Done.

The sec­ond bucket is di­vided up by per­son, so in our case, it was re­ally four sep­a­rate buck­ets. When some­one needed some­thing new to work on, they would go to the “To Do” bucket and se­lect a new task (which in our case, was a sticky note). They would place the task into their cor­re­spond­ing “Doing” bucket. Once the task was done, they would move the sticky note into the “Done” bucket and re­peat.

As a gag, we added an ad­di­tional (superfluous) bucket: IDGAF. If a task was unan­i­mously deemed no longer im­por­tant or rel­e­vant to the pro­ject, that’s where we would put it.

So, we got to work. We had de­cided to use Firebase, SvelteKit and Go. I started set­ting up Firebase, Grant started re­search­ing the no­ti­fi­ca­tion ser­vice, Lukas started work­ing on a cir­cu­lar sta­tus page and Byron started re­search­ing the Camera API.

As I look back at this mo­ment to­day, I re­al­ize some­thing im­por­tant about all of these tasks that ended up ben­e­fit­ing us in the long term: they were all in­de­pen­dent. None of these orig­i­nal tasks re­lied on any other to get done. We could work in par­al­lel. Down the road, this would change, but the fact that we were par­al­lel at the be­gin­ning set us up for suc­cess.

The Snow and the Crash

We kept work­ing through the night, down­ing en­ergy drinks and laugh­ing as we worked. We got the im­por­tant ser­vices and UI el­e­ment up and run­ning. Around mid­night, as my nose had pre­dicted sev­eral hours ear­lier, it started snow­ing.

As the snowflakes grew larger and ever more fluffy, I felt the teams en­ergy be­gin to dip. We were en­coun­ter­ing road­blocks, one-by-one, as our mo­ti­va­tion waned and the threat of sleep be­came more promi­nent.

Then, some­one in the main atrium (who, I don’t re­mem­ber) pro­nounced, “we are go­ing out­side.” We ran down the halls like chil­dren spread­ing the an­nounce­ment, and soon enough, there were dozens of tired com­puter sci­ence stu­dents throw­ing snow­balls in their jeans the t-shirts.

As I threw (and re­ceived) a num­ber of snow­balls, I re­al­ized some­thing im­por­tant: we were mak­ing an app about tak­ing care of your­self phys­i­cally, but had ne­glected to do so our­selves. As im­por­tant as the pro­ject may be, it won’t get done when every­one is tired, mus­cles cramped, and un­happy. To keep the mo­men­tum go­ing, breaks are re­quired.

As we filed back in­side to warm our hands un­der tap wa­ter, I swore to make sure the rest of the team would take care of them­selves–and each other.

The Conclusion

The rest of the hackathon was un­event­ful. We sat at our lap­tops, crank­ing out line af­ter line of code. We took breaks and slept when we were blocked by other tasks.

Although it was our first hackathon, we de­cided to run our pro­ject in the ad­vanced track, nor­mally re­served for hackathon vet­er­ans. It paid off, be­cause we won sec­ond-place!

Look at us: hag­gard but sat­is­fied.

There are a num­ber of grand chal­lenges my gen­er­a­tion faces. Some threaten the way we live, like the hous­ing cri­sis. Oth­ers are dif­fi­cult to solve, like space travel. More still both threaten the way we live and are dif­fi­cult to tackle, like cli­mate change and pol­lu­tion.

But of all the dis­cus­sion of the prob­lems of the mod­ern world, one is of­ten over­looked: how do we live hap­pier, more mean­ing­ful lives.

I’ve found that there are two main po­ten­tial an­swers which in­volve the way we sleep and the way we work. They are re­lated to the on­go­ing brain dam­age of mil­lions of Americans, so­cial me­dia and light­ing. By at­tempt­ing to solve this prob­lem (that of hap­pi­ness and pro­duc­tiv­ity), all other grand chal­lenges be­come eas­ier to solve.

Unlike other grand chal­lenges, like space travel, whose so­lu­tions lie in the hands of rel­a­tively few sci­en­tists and ad­min­is­tra­tors, this prob­lem of how to live well is the re­spon­si­bil­ity of both in­di­vid­u­als and busi­nesses.

Step 1: Sleep

As a high school stu­dent, I had an ad­ver­sar­ial re­la­tion­ship with sleep. The way I saw it, every minute asleep was a minute of home­work not done, a minute of friend­ship not cher­ished. A minute of life lost.

I went many nights com­pletely for­go­ing it en­tirely, be­liev­ing that it was merely a pre­view of death. In hind­sight, I think it re­flects well on my work ethic, but poorly on my work tech­nique. The an­cient Greeks seemed to agree with me. Ac­cord­ing to them, god of sleep was Hypnos, twin brother of death.

I could­n’t have been more wrong, for sleep is in­cred­i­bly im­por­tant. In fact, I may have re­ceived mild brain dam­age for my de­ci­sions. Sleep is not mere lack of ac­tiv­ity. In the book Why We Sleep by Matthew Walker, he dis­cusses why sleep is crit­i­cal for liv­ing a life con­tain­ing depth of work and depth of be­ing.

There are two types of sleep, and each are equally im­por­tant.

NREM (Non-Rapid Eye Movement) Sleep

NREM sleep is crit­i­cal in the in­te­gra­tion and so­lid­i­fi­ca­tion of mem­ory. This is the por­tion of sleep where your eyes are sta­tion­ary, thus the name. In fact, NREM sleep seems to be the only time the brain ac­tively works to re­tain mem­ory. Since NREM sleep is more preva­lent in the ear­lier hours of the night, go­ing to bed two hours hours later than usual re­sults in a 70% re­duc­tion in re­ten­tion of fac­tual in­for­ma­tion the next day.

REM Sleep

REM sleep is piv­otal in cre­ative think­ing and emo­tional pro­cess­ing.

Walker mod­els ideas as a knowl­edge graph. Dur­ing wake­ful­ness, tra­ver­sal across this graph for the pur­pose of prob­lem solv­ing is some­what iso­lated. In other words, peo­ple who are awake are only think­ing of so­lu­tions or mak­ing con­nec­tions that are con­cep­tu­ally sim­i­lar to the ex­ist­ing so­lu­tions and ideas. Dur­ing REM sleep, how­ever, the brain makes finds longer-dis­tances re­la­tion­ships, from much fur­ther-apart sec­tions of the graph.

PTSD pa­tients al­ways have poor qual­ity sleep from to night­mares. It is­n’t just a cor­re­la­tion, it is lit­er­ally re­quired in the di­ag­no­sis. Walker claims this is be­cause the brain is at­tempt­ing to process the neg­a­tive emo­tions as­so­ci­ated with trauma, but, since the emo­tions are so strong, wakes it­self up. One of the main goals with cog­ni­tive be­hav­ioral ther­apy for PTSD pa­tients is get the vic­tim through a full night of sleep. By giv­ing the brain the op­por­tu­nity to prop­erly process the neg­a­tive ex­pe­ri­ence (in REM sleep), they are able to dra­mat­i­cally speed up re­cov­ery.

Main take­away: sleep more and you will live a longer, health­ier, more im­pact­ful life.

The need for sleep varies across your life­time less than many peo­ple think. The most des­per­ate need is dur­ing in­fancy, with ba­bies and tod­dlers re­quir­ing as much as 18 hours of sleep per day. As you get older, de­creases un­til lev­el­ing off at eight and half hours of time in bed. No, that is not time asleep it is time in bed. It is a myth that se­niors re­quire less sleep. In truth, they re­quire just as much sleep as in mid­dle age, but have greater dif­fi­culty achiev­ing it. This is pri­mar­ily due to the cor­re­lated dif­fi­culty breath­ing, and sec­on­dar­ily due to the ear­lier bed-time se­niors re­quire.

There are a num­ber of traits of the mod­ern world that have re­sult­ing in the WHO di­ag­no­sis of sleep de­pri­va­tion as a pan­demic. More than 28% of Americans are chron­i­cally sleep de­prived.

The Danger of Sleep Deprivation

Chronic sleep de­pri­va­tion can re­sult in brain dam­age. While you are awake, the glym­phatic sys­tem (which is sim­i­lar in func­tion, dif­fer­ent in im­ple­men­ta­tion to the lym­phatic sys­tem) is in­ac­tive. As a re­sult, there is a grad­ual buildup of garbage in the brain, block­ing neu­ro­trans­mit­ters and gen­er­ally dis­rupt­ing the abil­ity for neu­rons to com­mu­ni­cate with each other. One pro­tein that builds up: beta amy­loid, the same pro­tein that causes Alzheimer’s dis­ease. When you sleep, the glymph sys­tem starts up and cleans up the garbage wake­ful­ness ac­cu­mu­lated. How­ever, if not given enough time to do its work (by sleep­ing), the glym­phatic sys­tem is not able to do its job en­tirely. This is why your like­li­hood of get­ting Alzheimers in­creases the less you sleep.

Sleep de­pri­va­tion also causes in­creased con­cen­tra­tions of cannabi­noids. Just like Marijuana, these in­creases ap­petite for un­healthy foods. Ad­di­tion­ally, sleep is an en­ergy in­ten­sive process. The body burns more calo­ries at night dur­ing sleep than dur­ing harm­ful wake­ful­ness. All in all, there is a very strong con­nec­tion be­tween sleep de­pri­va­tion and obe­sity.

Matthew Walker high­lights one es­pe­cially crit­i­cal time when phys­i­cal and men­tal health (especially mem­ory re­ten­tion) are im­por­tant: school. The pri­mary goal of school is to learn, to which NREM sleep is crit­i­cal (due to its role in mem­ory re­ten­tion).

Starting in mid­dle school, chil­dren’s cir­ca­dian rhythms start to shift later. In other words, teenagers nat­u­rally fall asleep and wake up later than other age groups. Walker at­trib­utes this to the need for teens to be­come more in­de­pen­dent. Evo­lu­tion pushes them to op­er­ate by them­selves by forc­ing their par­ents to go to bed ear­lier.

Schools op­er­ate un­der the cir­ca­dian rhythms of par­ents and teach­ers. 7 o’­clock in the morn­ing is the ideal time for them, but not for the stu­dents. But we find that stu­dents don’t go to bed any ear­lier, even though they are forced to awake at the same time as their par­ents. The end re­sult: mil­lions of mid­dle and high school stu­dents are cur­rently ex­pe­ri­enc­ing chronic sleep de­pri­va­tion, just be­cause school starts too early.

The eat­ing and phys­i­cal habits de­vel­oped dur­ing one’s school years serve as the tem­plate for the re­main­der of their lives. If one spends their de­vel­op­ing years un­der sleep de­pri­va­tion (which is the case for mil­lions of stu­dents in the U.S.) they are learn­ing how to live their life un­der the in­flu­ence of cannabi­noids, all the while get­ting grad­ual brain dam­age from the buildup of beta amy­loid.

Sleeping Pills

As an aside, I feel the need to ad­dress sleep­ing pills. Do not take them.

There are cur­rently no med­ica­tions on the mar­ket that in­duce real sleep. There are med­ica­tions that slow and stop brain func­tion, like Ambien. They do not pro­vide real sleep, and as such do not re­sult in mem­ory in­te­gra­tion, emo­tional pro­cess­ing or any of the other ben­e­fits of sleep. In fact, stud­ies with Ambien show that in­duced “sleep” ac­tu­ally re­sults in a net loss of mem­ory, com­pared with not sleep­ing at all. Not only does Ambien stop nat­ural mem­ory in­te­gra­tion, it ac­tively causes for­get­ful­ness.

Phones and Blue LEDs

The part of the brain that runs your cir­ca­dian rhythm is called the su­per­chi­as­matic nu­cleus. This is an ex­tremely small clus­ter of neu­rons that sits on the in­ter­sec­tion of your two op­tic nerves. It watches for sig­nals of blue light. If is any is de­tected (since the only sig­nif­i­cant, nat­ural blue is from the sky) it can safely as­sume it is day and will slowly ad­just it­self un­der that as­sump­tion.

Phones and other sources of blue light mess with this process. If your eyes de­tected any at night, you are guar­an­teed to sleep worse.

There are other neu­ro­log­i­cal ef­fects at play. Most ac­tiv­i­ties that take place on a phone ac­ti­vate the part of the brain called the amyg­dala, which we most com­monly as­so­ci­ate with the fight or flight re­sponse. When ac­ti­vated, your body pre­pares it­self for sur­vival. It slows or halts di­ges­tion, di­lates the pupils and in­creases me­tab­o­lism. In other words, pre­pares your body for ac­tion, not rest.

The is­sue: one of the most com­mons sta­ples of mod­ern of­fice spaces are the rows upon rows of flo­res­cent lights. All peo­ple work­ing in build­ings out­fit­ted with these lights may be ex­pe­ri­enc­ing worst qual­ity and quan­tity of sleep as a re­sult, es­pe­cially those work­ing later or longer hours.

In the search for pro­duc­ing deep work and liv­ing a full life, get­ting enough sleep is para­mount. It is the sin­gle most ef­fec­tive move one can make, since it makes all other ac­tions more ef­fec­tive.

However, as I pre­vi­ously pointed out, suc­cess in the new econ­omy re­lies par­tic­u­larly on deep work, which re­quires deep fo­cus.

Step 2: Deep Focus