The automation

Apple Music doesn’t expose a “library export” command in its AppleScript dictionary, so the only option is GUI scripting through System Events. The script:

1. Activates Music.app
2. Navigates the menu: File > Library > Export Library…
3. Uses Cmd+Shift+G in the save dialog to jump to the project directory
4. Clicks Save
5. Waits for the ~46MB XML file to finish writing (by polling file size until it stabilizes)
6. Runs the existing update_music Ruby script to regenerate the page
7. Commits any changes to blog/ and assets/ and pushes to deploy

./utilities/export_and_update_music

The interesting part was discovering that Music.app opens a standalone window "Save" rather than the more common sheet 1 of window 1 pattern that most macOS apps use for save dialogs. That small difference was the only real debugging needed.

Running it on a schedule

Since GUI scripting requires a logged-in session with screen access, a plain cron job won’t work. Instead, I’m using a launchd agent with LimitLoadToSessionType: Aqua, which ensures it only fires when I’m actually at my Mac.

<key>LimitLoadToSessionType</key>
<string>Aqua</string>

It runs weekly on Sunday mornings. Unlike cron, launchd with StartCalendarInterval will fire a missed job on wake, so if my laptop was sleeping during the scheduled time, it catches up as soon as I open the lid.

The other launchd gotcha: the agent runs with a minimal environment, not your shell profile. I had to set PATH (to find Homebrew’s Ruby and bundle) and LANG (to en_US.UTF-8, since the plist parser chokes on non-ASCII track metadata without it) in the plist’s EnvironmentVariables.

Requirements

The prerequisite is granting Accessibility permissions (System Settings > Privacy & Security > Accessibility). When running from a terminal, your terminal app needs the permission. When running via launchd, /usr/bin/env needs it instead. Since the script’s shebang uses #!/usr/bin/env bash, env is the parent process that macOS checks for Accessibility access.

The full script is in the repo.

The Critic agent I built runs on a cron schedule. It monitors my RSS feed, reads new posts, searches my garden for related writing, and emails me a critique. That’s good for reflection. I read the critique over coffee the next morning, think about it, sometimes update the post. But it means publishing first and polishing later. For a post I cared about getting right before it went out, I wanted the feedback loop tighter.

Bring the feedback to the source

Feedback is more useful the closer it is to the action. An email critique that arrives hours later is a thought-provoker, only affecting future behavior. A critique that appears inline against your prose, while you’re still shaping it, is a collaborator. I wanted something like inline semantic linting.

I already had the infrastructure: the Critic val on Val Town, the Anthropic API, the garden search tools. I needed two things: a way to critique unpublished drafts, and a way to see the results in my editor.

The :Critique command

I added a POST /draft endpoint to the Critic val that accepts a title and content (password-protected), runs the same critique pipeline, and returns the result. Then I wired it into a neovim command:

:Critique

The command runs asynchronously via jobstart() (I get my editor back immediately). About a minute later, two things happen: the full critique opens in a background tab, and inline annotations appear in my buffer via ALE.

Note

If you’re not familiar with ALE and/or [neo]vim, think of these inline annotations as the squiggly spellchecker lines you see in your Microsoft Word and Google Docs.

The annotations use ALE’s other_source API, which lets you push linter-style results from any external process. Each annotation has a line number, a severity (I for suggestions, W for clarity issues, E for errors), and a short message. When the feedback targets a specific phrase, ALE highlights just those words rather than the whole line.

With this, I can navigate around the file and read the feedback inline, or :lopen the location list window to view all of them at once. Or I can tab to the full-prose critique and see the full context from the critic. In practice, I do all these things and then revise, rinse, and repeat.

The annotation step is deliberately separate from the critique step. The Critic agent has a single job: read the post, research the garden, write a critique in prose. A second, cheaper call maps that prose onto line numbers and phrases. The separation matters for several reasons:

• I have a hunch that the critique agent produces better output when it’s not distracted by linter formatting
• The critique stays useful as standalone prose; it’s not locked to a display format
• The annotation mapping is composable: I can map any critique-and-source pair, not just ones the Critic generated
• I can use different model tiers for each: Opus for the critique, Sonnet for the mapping

Two resolutions of the same feedback

Seeing the critique at two resolutions simultaneously changed how I process it.

The full critique in the background tab gives me the arc: what’s working, what’s missing, how the piece connects to my other writing. The inline annotations give me specific pressure against specific sentences. I read the tab first to understand the big picture, then work through the inline feedback phrase by phrase.

This also taught me to edit in phases. Saving the file clears the ALE annotations (the linter display is tied to the buffer state), so I make several edits before saving. That batch-editing rhythm turns out to be better anyway; I’m responding to a coherent set of feedback rather than fixing things one at a time.

The async email critic still runs for every published post. It’s more of a thought-provoker, and only sometimes pushes me to update something. The inline critic, because it’s right there next to my words, makes me edit more. Proximity matters.

Agents write to me, I edit my own files

A principle I’m finding: agents should communicate to me, not edit over my work. Code is now an agent’s artifact. The critique is the agent’s artifact. Whatever I’m writing is mine: my thinking, possibly refined by the agent’s interrogation. A linter never rewrites your code; it tells you what to reconsider. The Critic works the same way.

How it works

The Critic val now has three relevant endpoints:

• POST /draft - accepts {title, content}, runs Sonnet for research (searching the garden, reading linked sources) and Opus for the final critique. Returns the critique as markdown and HTML.
• POST /annotate - accepts {content, critique}, uses Sonnet to map each critique point to a line number, severity, and optional verbatim phrase from the source. Returns a JSON array of annotations.
• GET /cron - the original: processes new RSS entries and emails critiques.

The neovim :Critique command chains /draft and /annotate asynchronously. It writes the critique to /tmp (so it’s automatically cleaned up), opens it in a background tab, then pushes annotations to ALE. The phrase-to-column resolution happens in vimscript: if the annotation includes a phrase, stridx() finds it on the target line and sets col/end_col for precise highlighting.

The Sonnet-for-research, Opus-for-critique split was originally a performance optimization - the val was timing out on Val Town’s free tier. It turned out to be the right architecture regardless. No noticeable difference in critique quality, meaningfully faster, and cheaper.

What’s next

The composable annotation endpoint opens other possibilities. Any document paired with any feedback (from an agent or a human) could be mapped to inline annotations: code review comments against a diff, editor notes against a manuscript, study questions against a reading. The pattern generalizes beyond my specific critic.

For now, though, the main thing is simpler: I write drafts, I :Critique them, and I make more edits because the feedback is right there. The agents write to me. I write my own prose.

I’ve been building this knowledge garden for years, and the collection has grown to thousands of notes, blog posts, highlights, and replies. I know the latent connections between them are there, but tracing the threads takes work. I usually write from personal experience and prior reading/writing, but want to include actual links to relevant work. Additionally, I don’t always remember prior work that would contradict or inform my current thinking. Having someone check for those things would help me improve.

So I’ve been building agents to push my critical thinking and tend the garden alongside me. Three of them now, each with a different role.

The Pre-Reader walks in front

I built Pre-Read to help me figure out whether I have an opinion on a piece. It can help before diving into a long article someone sent me or that I found in my feed. I give it a URL and it searches my garden for things I’ve already written or saved that might relate to the piece. It frames what I already know before I start reading.

This is useful when I haven’t quite solidified my opinion on something. The pre-reader jogs loose some thoughts I can then maybe turn into a note. It walks ahead of me on the trail, scouting what’s familiar.

It produces three perspectives on any given piece: a Proponent, an Opponent, and a Questioner. These mirror how I naturally read things. I usually give an author the benefit of the doubt first — I agree, I look for where it reinforces what I already believe. Then I force myself to take the opposing stance and poke holes in the argument. And when I’m really stuck, I try to think of questions for the author that would open up a better conversation around the topic. The three personas externalize that cycle so I don’t get stuck on step one, which is what happens when I’m just saving a quick note.

The Suggester walks behind

There are already hundreds of notes here that I’ve neglected to write about. I built an Uncommented Notes page that surfaces them - notes where I saved a quote or a link but never added my own thoughts. From there, the Suggest Comments page takes any post and generates suggested comments I might add: connections to other posts, reactions I haven’t articulated, threads I haven’t pulled. Each suggestion comes as a short paragraph with markdown links to related garden posts.

This gives me a starting point to write my own expansion on the note. I don’t want to copy and paste this output mechanically: the point here is to kickstart my own thinking and put my own words into the system.

These are tools for downtime. On the train, waiting in line - I open the uncommented list, pick a note, and let the suggester stimulate a thought. It helps me fill in blanks productively, which is better than scrolling social media. It walks behind me, picking up what I dropped.

The suggester uses the same three personas (Proponent, Opponent, Questioner) applied to my own posts instead of someone else’s. The same reading cycle works in reverse: where do I agree with my past self, where would I push back now, and what questions does the note leave open?

The Critic walks beside

The newest agent is the one I’m most excited about. The Critic runs on a cron schedule every few hours. It monitors my site’s RSS feed, and when I publish something new (a blog post, a note, an exercise log, anything) it reads the post, follows any linked sources (both internal garden links and external pages), searches the garden for related prior writing, and emails me a critique.

It’s a simplistic agent. It’s not constantly expanding its context scope, so it doesn’t fall prey to compounding error rates. This simplicity is a deliberate design choice for this tool. LLMs perform well in this sweet spot where they’re given a tight context window, allowed to agentically operate in that window, and then state is output/saved for recursive processing.

Note

The critic doesn’t retain memory of past critiques or track whether I acted on its feedback. That compounding memory might be a future improvement, to make it a full entity.

The critique covers argument strength, writing clarity, connections to other posts, how I engaged with sources, and growth edges. It’s constructive, specific, and it cites passages. It walks beside me: it reads what I’ve just written, and later that day or the next morning over coffee I read a critique as if from a colleague. I consider it and hopefully incorporate it into an edit or a follow-on post. I want it to feel collaborative: a feedforward mechanism for my own writing process.

I chose a strong model for this (Anthropic’s Opus). The other agents use Sonnet, which is fast and good enough for search-and-suggest work. But I want a writing mentor to be as sharp as possible. Lower-quality models still sound like parrots, echoing your context window back at you and telling you what you want to hear. I want genuine pushback. The critic runs infrequently enough that the cost is not a concern.

Early results

I’ve been using the suggester for a few days now, and every day I’ve updated at least one note with new comments and links. I’m finding myself using the pre-reader on my backlog of reading - things I would have skimmed in the past, but now I can see them through the lens of what I’ve already written. I’m already getting ideas for how the pre-reader could evolve: giving it more agency to recommend whether I should read the full piece or not, pulling quotes into its summaries.

The critic is newest, but the first critiques have been pointed enough that I’m optimistic. I used it repeatedly on this very post and it pushed me to refine wording, expand things I only gestured toward, and found source links to support my words. It also challenged some of my earlier claims, so that I strengthened them or removed them. It has made me engage much more than I would have previously with this writing.

Importantly, I’m not copying and pasting the output from these agents, or letting them edit my writing directly. I want influence and collaboration, not delegation (feedforward context that shapes environment, not writing output for me). Unlike how I’m using agents to write code on my behalf, I want to be writing this prose myself. I need to actually write things, as output, to have them fully change my thinking. Code was always an intermediary between the system and behavior I was designing and the computer that would enact it, so with coding agents I operate at a system design level, now rarely editing lines of code directly. With prose, I communicate directly with the minds of the audience, and the writing is a tool for my own mind; having an agent write it on my behalf cheats myself (see the SloppyPasta source at the top).

A modern website

Any one of these agents is a neat trick, but together, they’re something more: a living feedback loop built into my reading and writing on this site. The pre-reader prepares me before I read. The suggester fills in gaps when I have spare attention. The critic holds me accountable after I publish. A modern blogging website in this age of LLM agents should have AI feedback loops like these built in. I think this is the prose writing equivalent of my claude code software writing feedback loops.

This has been an evolution based on experience, not theory. The three agents replace the Insight widget I built last year (and the prior RAG-based insights before that), which tried to do everything in one pass.

Using the basic RAG, I eventually found it uncreative. Using the agent, I found two distinct needs: suggesting connections and critiquing writing. Splitting them into dedicated agents with different triggers and interaction patterns serves each need better. It’s also now trivially easy to manage many vals for many distinct purposes when LLM agents are doing the coding, testing, and development for me.

I don’t want to just collect and hoard links. I want to integrate, connect, and digest. I can do that in conversation with colleagues, but I can’t always find a sparring partner at the moment I need one. These agents are tireless, and they know my entire body of work. They fill the gaps between conversations, keeping the garden tended when I’m not paying attention.

How the Critic works

The whole thing is built on Val Town, which has become my go-to for this kind of lightweight agent infrastructure. It encourages small compositional units, exposes a nice CLI for managing things, supports email/HTTP/cron as agent triggers, has minimal-but-complete storage, etc. The stack:

• RSS feed parsing to detect new posts
• Blob storage to track the last processed post and avoid duplicates
• An agentic tool-use loop where the LLM can search my garden via the MCP server I built for this site, read specific posts, and fetch external pages via jina.ai
• HTML email with the critique, sent via Val Town’s built-in email service
• HTTP routes for ad-hoc testing — a /preview?url= endpoint that renders the critique as a web page

I built each interface by orchestrating Claude Code agents. I designed a skill for them to know how to create and manage vals on Val Town. They tested and iterated using the Chrome DevTools MCP server to render the pages in real time.

All of the source code is public. The Critic, Pre-Reader, and Suggester vals are on Val Town. The Val Town dev skill for Claude Code is on GitHub. If you have a site with an RSS feed and a search index, you could wire up something similar.

The software engineering industry has had a standard of adding a README.md file to the root of projects and also the root of any subdirectory of those projects where deemed necessary. These files are easily discoverable by operators of the codebase, and their contents - while not standard - have been embraced as a place to put instructions for patterns and how to operate in the codebase.

with the rise of coding agents over the last couple years, people found that they needed to give them special instructions because they were error prone in certain ways, and we hadn’t built out the harnesses and capabilities for them to replicate how human operators work in a code base. That is no longer true today.

We We have incredibly capable models and the harnesses and tooling that we give them (like shell access and MCPs for browser control, among hundreds of other tools), being that they can do everything that a human operator can do to operate on the code. Everything I would say to a human operator in the codebase, I would say to an LLM agent working in that same codebase.

So, I just revamped my project’s READMEs and symlinked them to the AGENTS.md location. It’s not useful to separate the instructions for humans from LLM agents. In fact, when we separate them, we increase the likelihood that they will operate in different ways and do things that the other does not expect or intend. This actively slows down development on both sides.

Solidifying a single place - the old README.md standard, that is present in all modern software - is the path forward. I’m symlinking my READMEs to conform to this standard for now, because it’s free and doesn’t clutter anything for me, but I hope it eventually falls away.

This one popped into my head after seeing some coworkers blindly trusting an LLM/AI agent’s output, which was entirely incorrect.

This is my little reminder to always check the output of today’s AI agents. Know the checks applied to their work before it reaches us. Understand the provenance of their output. Their incentives are not your own.

Same impulse that led me to build iCal feeds for my entire blog history. A calendar is the tool I already use for planning around time. Price data is time data — it just happens to come from a utility instead of a CMS. If I can see that electricity drops to near-zero at 2am and spikes at 6pm, I can plan around it the same way I plan around meetings.

So I built a small Val.town server that generates an iCal feed of price changes. It pulls the last 24 hours of 5-minute prices from ComEd’s public API, averages them into hourly buckets, and grabs the next day’s prices from their (undocumented) day-ahead endpoint. Then it compares consecutive hours and emits a calendar event whenever the price shifts by more than a threshold:

↑ 3.7c/kWh (+0.9c)
↓ 2.1c/kWh (-0.3c)

Stable hours produce no event — gaps in the calendar mean the price isn’t moving. The sensitivity, lookback window, and lookahead are all configurable via query parameters, so I (or you!) can tune it to only surface the swings I care about.

Note

Day-ahead prices aren’t always available — ComEd publishes them on their own schedule, typically in the evening for the following day — so the feed only includes forward-looking events when the data is there.

The next step is pairing this with batteries to buffer my high-draw appliances — grow lights, the computer desk — into cheap hours automatically. For now, just seeing the price rhythm on my calendar alongside everything else is enough to shift my habits. Everywhere a calendar.

The Approach

Letterboxd doesn’t have a public API (though they have a private beta API), but the like count is embedded in the review page’s HTML. When you view a review, there’s an element with a data-count attribute holding the number:

data-likes-page="/joshbeckman/film/the-french-connection/likes/"
data-format="count"
data-count="1"
data-owner="joshbeckman"

So the plan was simple: fetch the review page, parse out that data-count value, and update the link text.

The Implementation

I added a loadLetterboxd() function alongside my existing social platform loaders. These all fire when the comments section scrolls into view, using an IntersectionObserver to avoid unnecessary requests on page load.

function loadLetterboxd() {
    var letterboxd = document.querySelector('.social-letterboxd');
    if (!letterboxd) {
        return;
    }
    var url = letterboxd.getAttribute('href');
    fetch(url)
        .then(response => response.text())
        .then(html => {
            var match = html.match(/data-count="(\d+)"/);
            if (match) {
                var likes = parseInt(match[1], 10);
                if (likes > 0) {
                    letterboxd.textContent = `${likes} ${pluralize(likes, 'like')} on Letterboxd`;
                }
            }
        })
        .catch(error => console.error('Error fetching Letterboxd review:', error));
}

The CORS Problem

This didn’t work. The browser blocked the request:

Fetch API cannot load https://letterboxd.com/... due to access control checks.

Letterboxd doesn’t set CORS headers allowing cross-origin requests from browsers. This is the same problem you hit with any site that hasn’t explicitly opted into being fetched by client-side JavaScript from other domains.

The Fix: A CORS Proxy

The solution is to route the request through a proxy that adds the appropriate headers. I tried a few options:

1. corsproxy.io - Worked locally but blocks HTML content in production due to phishing concerns. Only JSON, XML, and CSV are allowed.

2. allorigins.win - Supports HTML, but was painfully slow in my testing.

3. cors.lol - Fast, supports HTML, and has a simple API. This is what I ended up using.

The CORS Proxies gist is a useful reference for finding working proxies, though the landscape changes frequently as services get abused and shut down.

The final implementation:

var url = letterboxd.getAttribute('href');
fetch(`https://api.cors.lol/?url=${encodeURIComponent(url)}`)
    .then(response => response.text())
    // ... rest unchanged

This adds a dependency on a third-party service, which isn’t ideal. If cors.lol goes away or starts blocking HTML, I could set up a Cloudflare Worker to proxy these requests, or fetch the data at Jekyll build time instead of client-side. For now, the simplicity of a hosted proxy wins.

The Result

Movie review posts now show like counts from Letterboxd right alongside the other social metrics. It’s a small addition, but it makes the social section feel more complete.

Note

Philip uses Lob to print and mail his issues, which includes a single QR code on the header/mailing page to direct the reader to the single source article. BUT I didn’t grok that at first (it’s not labeled as anything and I assumed it was errata from Lob) and I think there should be a general solution to this outside of using Lob.

This isn’t a new problem. Over a decade ago, I wrote about how The Great Discontent handled links in their first print issue - they used numbered footnotes with shortened URLs. Back then, I noted that QR codes felt “large and intrusive.” But they’ve become ubiquitous since, and at 64 pixels square they’re unobtrusive enough to include alongside each URL.

I wanted to make link-following possible on my site. When someone prints one of my posts, I want them to still be able to follow the links I included.

The Solution: QR Code Footnotes

I wanted to take a similar approach to what Stripe Press does in its books (e.g. An Elegant Puzzle): footnotes with full links and QR codes.

When you print any page on this site now, every link gets:

1. A superscript footnote marker (like L1, L2, etc.)
2. A corresponding entry in a “[L]inks” section at the end with the full URL and a QR code

The L prefix distinguishes these from any regular footnotes on the page, and ties visually to the “[L]inks” header. Readers can either type the URL or scan the QR code with their phone to follow the link.

How It Works

The implementation uses the browser’s beforeprint event to generate footnotes just before printing. The qrcodejs library is preloaded so it’s ready when needed:

<script src="https://cdn.jsdelivr.net/gh/davidshimjs/qrcodejs/qrcode.min.js" async></script>

Building the Link List

When printing is triggered, it collects all unique links from the page content, seeding the list with the current page URL as item 0:

var links = [{href: document.location.href, anchor: null, label: 'This page:'}];
var seenUrls = new Set([document.location.href]);

// you would replace this selector with something specific to your content's page structure
var anchors = document.querySelectorAll('article a[href], .text a[href], .h-entry a[href]');
anchors.forEach(function(anchor) {
    var href = anchor.href;
    var rawHref = anchor.getAttribute('href');
    // Skip hash links, javascript:, hidden elements, and duplicates
    if (rawHref.startsWith('javascript:') || rawHref.startsWith('#') || anchor.closest('.print-hidden')) {
        return;
    }
    if (!seenUrls.has(href)) {
        seenUrls.add(href);
        links.push({href: href, anchor: anchor, label: null});
    }
});

The selector targets links within article content specifically - navigation, masthead, and footer links are already hidden in print via .print-hidden, so we skip those.

Generating Footnotes and QR Codes

For each link, we add a superscript to the anchor (if it exists) and create a footnote entry:

links.forEach(function(link, index) {
    if (link.anchor) {
        var sup = document.createElement('sup');
        sup.className = 'print-footnote-ref print-only';
        sup.textContent = 'L' + index;
        link.anchor.appendChild(sup);
    }

    var li = document.createElement('li');
    li.value = index;

    // QR code first for easy scanning alignment
    var qrContainer = document.createElement('div');
    qrContainer.style.cssText = 'width:64px;height:64px;display:inline-block;vertical-align:middle;margin-right:8px';
    li.appendChild(qrContainer);

    var urlSpan = document.createElement('span');
    urlSpan.textContent = link.href;
    li.appendChild(urlSpan);

    new QRCode(qrContainer, {
        text: link.href,
        width: 64,
        height: 64,
        correctLevel: QRCode.CorrectLevel.L
    });
});

CSS Considerations

A few CSS details make this work:

1. Print-only visibility: The .print-only class hides elements on screen but shows them in print. The superscripts and footnotes section both use this.

2. Inline superscripts: The .print-only class uses display: block !important, so the superscript refs need display: inline !important to stay inline with the link text.

3. List markers: Using display: flex on list items hides the default markers. Switching to display: list-item with explicit list-style-type: decimal brings them back.

.print-only {
  display: none;
}
@media print {
  .print-only {
    display: block !important;
  }
  #print-footnotes ol {
    list-style-type: decimal !important;
    list-style-position: outside;
  }
  #print-footnotes li {
    display: list-item !important;
  }
  .print-footnote-ref {
    display: inline !important;
  }
}

Gotchas

href property vs attribute: The anchor.href property returns the fully resolved URL (e.g., https://example.com/page#section), while getAttribute('href') returns the raw attribute value (#section). Using the attribute makes it easy to filter out in-page anchor links.

CSS display conflicts: The .print-only class uses display: block !important for print media. Superscript elements inside links need display: inline !important to stay inline with the link text rather than breaking to a new line.

Why This Matters

This isn’t just for mailed print publications like Philip’s. I sometimes print web pages to archive on my physical bookshelf, or print recipes, instructions, and reference tables to use around the house. Others save web pages to PDF. In all these cases, the links in the original content become dead text unless you preserve them somehow.

Now when someone prints an article from my site, the links stick around. They can scan a QR code or type a URL. The reference is preserved.

Note

This is of course based on incomplete data, as many people (including myself) now browse the web with tracking blockers. But directionally this should be indicative of traffic.

This data is publicly available here.

Totals

~30,140 visits in the year, with a peak of 7,613 on 2025-08-11.

I published 215 blog posts, 23 replies, 192 notes, 343 exercises, and 7 proverbs. I hope to publish more than that in 2026.

Top Posts

I’m actually kind of embarrassed that the Jury Duty post is so popular. In retrospect, I only half stand behind it; I think it’s too flippant.

I’m happy the UAI post did so well - it was a concept I developed and anchored on at work all year and I think it has been immensely useful for aiming my teams.

Top Referrers

I think the high proportion of (unknown) referrals is coming from internally-shared links to my site. I love that! It tells me that people find my writing useful enough to share themselves rather than just consuming it from a feed or something. I want my work to be a helpful reference.

At the time I removed them, I wasn’t getting any webmentions sent to my site and I wasn’t sending any webmentions because the sites I was linking to didn’t support them. I thought it was a dead end and instead built POSSE for this site to the likes of Mastodon and Bluesky.

Recently, I have started seeing webmentions for some of my more popular posts, and I started displaying them on post pages and added a simple little form for people to manually send them when they write their own responses to my things. I’m receiving them through webmention.io and displaying them through their simple+fast API.

Because I have I’ve started seeing a slight uptick in people sending me webmentions and I started displaying them, I figured I should re-enable my automations to send them to others. Here’s how that works:

• I have a GitHub workflow that runs twice daily
• A Ruby script pulls the RSS feed for my site and iterates through the recent posts
• The script uses indieweb/webmention-client-ruby (A Ruby gem for sending and verifying Webmention notifications) to test/find endpoints for any sites linked-to from the post and send a mention where possible

require 'net/http'
require 'webmention'
require 'uri'
require 'nokogiri'

class SendMentionsFromRss
  Config = Struct.new(
    'MentionsFromRssConfig',
    :feed_url,
    :item_selector,
    :item_href_proc,
    :excluded_url_matcher,
    :verbose,
    keyword_init: true
  )

  def self.execute(config)
    raise ArgumentError, 'Must use a Config' unless config.is_a?(Config)

    puts "Loading RSS feed from #{config.feed_url}"
    export_uri = URI.parse(config.feed_url)
    export_req = Net::HTTP::Get.new(export_uri)
    export_res = Net::HTTP.start(export_uri.hostname, export_uri.port, use_ssl: true) do |http|
      http.request(export_req)
    end
    raise StandardError, 'Feed request failed' unless export_res.is_a?(Net::HTTPSuccess)

    doc = Nokogiri::XML(export_res.body)
    doc.css(config.item_selector).each do |link|
      href = config.item_href_proc.call(link)
      Webmention.mentioned_urls(href).each do |url|
        if url.match?(config.excluded_url_matcher)
          puts "skipping #{url}" if config.verbose
          next
        end

        result = Webmention.send_webmention(href, url)
        if result.ok?
          puts "Sent mention of #{url} by #{href}"
        else
          puts result.message
        end
      end
    end
  end
end

site_config = SendMentionsFromRss::Config.new(
  feed_url: 'https://www.joshbeckman.org/feed.xml',
  item_selector: 'entry link',
  item_href_proc: -> (link) { link['href'] },
  excluded_url_matcher: [
    /www.joshbeckman.org/,
    /notes.joshbeckman.org/,
    /readwise.io\/open\//,
    /readwise.io\/reader\//,
    /s2.googleusercontent.com/,
    /gravatar.com\/avatar/,
    /indieweb.org\/Webmention/
  ].join('|'),
  verbose: false
)
SendMentionsFromRss.execute(site_config)

I hope to see it discover endpoints on sites I’m linking to and sending webmentions out in the new year.

Note

See last year’s data at My GitHub Wrapped 2024 or (for fun) I generated My GitHub Wrapped 2019 with my new gh-wrapped script.

Contribution Summary

Activity Patterns

• Busiest day of week: Tuesday (1228 contributions)
• Longest streak: 236 days (2025-04-28 to 2025-12-19)
• Active days: 329 / 365 (90.1%)
• Peak day: 2025-06-10 with 68 contributions

Activity by Day of Week

Sunday      763 ████████████████████████
Monday     1160 █████████████████████████████████████
Tuesday    1228 ████████████████████████████████████████
Wednesday  1191 ██████████████████████████████████████
Thursday    998 ████████████████████████████████
Friday     1046 ██████████████████████████████████
Saturday    671 █████████████████████

Monthly Breakdown

Jan   263 ██████████
Feb   400 ███████████████
Mar   438 ████████████████
Apr   246 █████████
May   500 ███████████████████
Jun   637 ████████████████████████
Jul   451 █████████████████
Aug  1032 ████████████████████████████████████████
Sep   815 ███████████████████████████████
Oct   766 █████████████████████████████
Nov   929 ████████████████████████████████████
Dec   580 ██████████████████████

Top Languages (by commits to public repos)

Top Repositories (by commits to public repos)

Repositories Created in 2025

Gists Created in 2025

Total: 11 gists (0 public, 11 private)

GitHub Sponsors

Supporting: @tpope, @wez, @jaredhanson

Profile Stats

2024 vs 2025 Comparison

Activity Patterns

Monthly Highlights

• 2024 peak month: December (448)
• 2025 peak month: August (1,032)

Notes

2025 has way way more commits than 2024 for a couple reasons:

• Claude Code was released and completely changed my workflow
• I set up more frequent syndication and automations on my personal site that committed changes under my signature

Here’s how I was working with Claude Code for the latter 2/3 of 2025:

• Have an idea for something to build or fix or explore in a code repository
• Open a new git-worktree in the repository, in a tab in my WezTerm terminal
• Split the tab/window into two panes:
  • The left pane is for me to view files, edit in Neovim, run shell commands, etc.
  • The right pane is for me to run a Claude Code session/chat
• Write a pretty lengthy prompt explaining what I want to do (or use one of my dozens of commands for e.g. fixing a bug, writing a test, etc.) and send Claude Code on its merry way
• While it’s running, review changes, edit my own, etc. in parallel
• Rely on Directed Notifications for Claude Code Async Programming to tell me when I need to give permission or intervene

This allowed me to be running a half-dozen parallel ideas/tasks on a project at once, with Claude Code committing as went went along.

I really leaned into GitHub’s CLI extension system in 2025 (examples), which helped me package my ideas and share them with the wider organization at Shopify. I think 2026 should shift my focus to Claude Code extensions; I’ve been building and privately distributing a bunch of them all year, but I think I should shift to open-sourcing them and building a proper library out of them. I’ve hesitated in 2025 because I think the systems were too fresh and in flux, but I expect things to calm down and consolidate in 2026.

I didn’t gain any sponsors in 2025 but it’s because I’m only working on small (though many!) tools and projects. I think people only want to sponsor big ideas.

But there’s one thing the GitHub web UI does really well: @-mention autocomplete. Start typing @ and it suggests teammates, reviewers, anyone you might want to loop in. That was unavailable in neovim. Until now.

I built gh-nvim-username-keywords.

Note

gh-nvim-username-keywords is a GitHub CLI extension that adds GitHub usernames to your nvim keywords file for autocomplete. It discovers usernames from your GitHub teams and PR activity, making it easy to @-mention colleagues.

Installation

gh extension install joshbeckman/gh-nvim-username-keywords

That’s it. Run the gh nvim-username-keywords command whenever you want to sync your recent username interactions to your local nvim dictionary keywords. Then they’re just a tab-complete away while you’re editing.

How It Works

The extension collects usernames from two sources:

1. GitHub Teams — members of teams you’re on
2. PR Activity — authors, reviewers, and commenters from PRs you’ve authored or reviewed

If you don’t specify teams or repos explicitly, it auto-discovers defaults from your most recent activity. It filters out known bot accounts, compares against your existing keywords file, and appends only new usernames (prefixed with @). The keywords file is append-only—existing entries are never removed.

# Use auto-discovered defaults
gh nvim-username-keywords

# Specify teams explicitly
gh nvim-username-keywords --team myorg/engineering --team myorg/design

# Preview what would be added
gh nvim-username-keywords --dry-run --verbose

Nvim Setup

Your nvim needs a keywords file at ~/.config/nvim/keywords.txt (or wherever $XDG_CONFIG_HOME/nvim/ points). If you’re not already using a keywords file for autocomplete, add this to your nvim config:

vim.opt.dictionary:append(vim.fn.stdpath("config") .. "/keywords.txt")
vim.opt.complete:append("k")

Now <C-n> or <C-p> in insert mode will suggest from your keywords file, including all those @username entries.

I also recommend configuring nvim to not break words on hypens. This is because many users have hyphens in their handles and in the default configuration, nvim will break their names and only tab-complete sections at a time. Here’s how you can change that:

" include hyphens in keyword completion (for usernames like @Gasser-Aly)
set iskeyword+=-

Note

This is my fourth gh extension. Previously released: gh-wrapped, gh-pr-staleness, and gh-view-md

The source is on GitHub. Contributions welcome!

1. They only work for public contributions, and a lot of mine are now in private repos.
2. They miss gists, repos created, and sponsorship data, but these are part of how I use GitHub.
3. They’re only available during a narrow window in December or only consider the single year
4. You can only check your own stats

I got tired of wondering, so I built gh-wrapped to give you a complete GitHub Wrapped on demand.

Note

gh-wrapped is a GitHub CLI extension that generates a year-in-review summary of your GitHub activity, inspired by Spotify Wrapped. Get detailed stats on your contributions, activity patterns, top languages, and more—all as formatted markdown.

Installation

gh extension install joshbeckman/gh-wrapped

That’s it. You have the GitHub CLI installed and authenticated (and jq for JSON parsing), you’re ready to go.

Run It Any Time, For Any Year, For Anyone

# Your stats for this year
gh wrapped

# Your stats for 2023
gh wrapped 2023

# Check someone else's public activity
gh wrapped 2024 octocat

# Save it as a gist
gh wrapped 2024 | gh gist create -f wrapped-2024.md

The third-party websites that appear each December are fine for a quick shareable image, but I wanted something I could run any time I’m curious. How did Q1 compare to Q4? What was my busiest month? Did I actually contribute more this year than last? These questions don’t care about December.

What You Get

The tool pulls from GitHub’s GraphQL contributionsCollection endpoint which is the same data source that powers your profile’s contribution graph. This means it includes both public and private contributions in the totals.

• Contribution Summary with public/private breakdown
• Activity Patterns: busiest day of week, longest streak, peak activity day
• Visual Charts for daily and monthly activity (ASCII bar charts in your terminal)
• Top Languages by commits
• Top Repositories by commits
• Repositories Created that year
• Gists Created (including private ones)
• GitHub Sponsors activity (when checking your own stats)
• Profile Stats: stars, followers, following

Note

See an example at this gist of my 20219 GitHub Wrapped generated with this script.

Private Contributions

This was the main reason I built this. GitHub’s API provides the total count of private contributions through restrictedContributionsCount, which those web-based tools often ignore or can’t access. The detailed per-repo and per-language breakdowns only cover public repos (GitHub’s API doesn’t expose private repo details), but at least your totals reflect reality.

Warning

GitHub only provides the contribution count (not details on whether they are commits/PRs/etc) for private repos. I tried making it actually crawl through a year’s worth of private repo commits/PRs/etc. to calculate the count, but GitHub API rate limits inevitably make the whole thing come crashing down.

The output clearly labels what’s public vs private so you know exactly what you’re looking at.

Note

This is my third gh extension. Previously released: gh-pr-staleness and gh-view-md

The source is on GitHub with examples and full documentation. Contributions are welcome!

They’ve been providing their own version of “Raycast Wrapped” for years and I just got mine for 2025:

Note

These stats (and the ones below) are just from my work machine. It’s where I spend the majority of my computing time.

I think a change for 2025 was that I leaned further into quicklinks. I still need to remember to use my bookmarks and history extension/integration for faster recall of pages (so I can close tabs more aggressively).

2024

2023

Elsewhere, Flow had several other big projects launch, like a whole “test your workflows before you activate them” system and a complete editor redesign: Shopify Editions Winter ‘26: The Renaissance Edition.

It was difficult to get here, and I’m so proud of my team.

Note

Full Shopify blog post: How Shopify Flow Automation Got Faster, Safer, and Smarter in 2025

See also the ~10:40 mark in The Unofficial Shopify Podcast.

But I didn’t make mine exactly to pattern. I wanted to make mind a bit “my own” and so I simplified the dimensions and complicated the fastening to eliminate the offset.¹ To fasten without an offset, I found some 1/4” bamboo garden stakes and cut them into 2” dowel rods. I drilled holes and then glued the dowels in place to hold the whole assembly through and through.

I used 3/4” A/C birch plywood for mine because I love the endgrain it brings to a sandwich alignment like this. I finished mine with boiled linseed oil (as I do with most wood these days) to really bring out the whorls and grain.

I don’t have a table saw - only my jigsaw - so the cuts aren’t straight on this, but the seat feels perfectly firm and stable.

Future

I’ve long wanted to build my own Rietveld-esque crate stool / table (written up by Piper Haywood), so maybe that will be my next build. The whole idea of crate furniture obviously appeals to me: so functional and efficient and customizable to your own comfort.

Another suggestion from a colleague was to make a traditional Japanese tool box.

More crate furniture (or “box furniture”) reading/watching:

• Reclaiming simplicity, thrift, and utility
• Tom Sachs speaking at IKEA: My Personal Journey with Chairs
• Donald Judd Furniture
  • I’d love to make a Double Back Bench 20
• “Nomadic Furniture:” DIY Designs from the 1970s
• Another I want to make many of: Berlin Hocker stool (stackable and composable into so many things!)
• Another I want to make: Steltman chair

Recently I found the two-sentence journal via De minimis non curat Lex. In it, Alexander describes how he’s adapted a game mechanic from Thousand Year Old Vampire for his own journaling. In the game, your vampire has finite memory, composed of experiences that you have written down during the game (and as the centuries pass, you must choose which aspects of your vampire’s life to retain or forget).

An Experience should be a single evocative sentence. An Experience is the distillation of an event—a single sentence that combines what happened and why it matters to your vampire. A good format for an Experience is “[description of the event]; [how I feel or what I did about it].”

As for how an experience might be written, the rulebook offers the following example:

Stalking the deserts over lonely years, I watch generations of Christian knights waste themselves on the swords of the Saracen; it’s a certainty that Charles is among them—I dream of his touch as I sleep beneath the burning sand.

Alexander took this into a journaling habit of his own:

I would aim to constrain each day’s entry to one or two key things, and limit their expression to one or two sentences. I allowed myself that latter tweak because the initial Thousand Year Old Vampire rule encourages improper semicolon usage and ugly run-on sentences, both of which strain language in hopes of cramming in as much as possible.

I fully agree with Alexander on loosening the constraint to two sentences; it’s much more beautiful that way. Two sentences allow narrative arcs, short stories, and juxtaposition to form. But you still can’t ramble and writing a sentence or two is always easy.

Digital Form

Inspired by this two-sentence journal and the physical structure of our Some Lines A Day notebook, I wanted to make a digital space for both.

So, I wrote a little command line program, journal, that will set up the structure of a daily, annualized journal in a markdown file, opening it to today. Then you write your one or two sentences and close it.

#!/usr/bin/env bash

set -euo pipefail

JOURNAL_FILE="JOURNAL.md"
CURRENT_DATE=$(date +"%B-%d")
CURRENT_YEAR=$(date +"%Y")

if [[ ! -f "$JOURNAL_FILE" ]]; then
    {
        echo "# Journal"
        echo ""
        for month in {1..12}; do
            days_in_month=$(cal $month $CURRENT_YEAR | awk 'NF {DAYS = $NF} END {print DAYS}')

            for day in $(seq 1 $days_in_month); do
                month_padded=$(printf "%02d" $month)
                day_padded=$(printf "%02d" $day)
                day_date=$(date -j -f "%Y-%m-%d" "${CURRENT_YEAR}-${month_padded}-${day_padded}" "+%B-%d" 2>/dev/null)

                echo "## $day_date"
                echo ""
            done
        done
    } > "$JOURNAL_FILE"
fi

if ! awk -v date="$CURRENT_DATE" -v year="$CURRENT_YEAR" '
    /^## / { in_day = 0 }
    $0 ~ "^## " date "$" { in_day = 1 }
    in_day && /^### / && $2 == year { found = 1; exit }
    END { exit !found }
' "$JOURNAL_FILE"; then
    awk -v date="$CURRENT_DATE" -v year="$CURRENT_YEAR" '
        /^## / {
            if (in_day && !year_added) {
                print ""
            }
            in_day = 0
            year_added = 0
        }
        $0 ~ "^## " date "$" {
            in_day = 1
            print
            print ""
            print "### " year
            year_added = 1
            next
        }
        { print }
    ' "$JOURNAL_FILE" > "${JOURNAL_FILE}.tmp"
    mv "${JOURNAL_FILE}.tmp" "$JOURNAL_FILE"
fi

LINE_NUM=$(awk -v date="$CURRENT_DATE" -v year="$CURRENT_YEAR" '
    /^## / { in_day = 0 }
    $0 ~ "^## " date "$" { in_day = 1 }
    in_day && /^### / && $2 == year { print NR; exit }
' "$JOURNAL_FILE")

if [[ -z "$LINE_NUM" ]]; then
    LINE_NUM=$(grep -n "^## $CURRENT_DATE$" "$JOURNAL_FILE" | cut -d: -f1)
fi

if [[ -n "$LINE_NUM" ]]; then
    nvim "+${LINE_NUM}" "$JOURNAL_FILE"
else
    nvim "$JOURNAL_FILE"
fi

I won’t be switching all my journaling to this digital form (in fact, I just bought another couple Some Lines A Day journals for myself and others), but I want to start a daily journal like this for work. For work notes, I only use digital storage; I can share them with colleagues and basically everything I do for work happens digitally.

Memory

In the game, your vampire holds five “Memories,” which each have room for three “Experiences.”

Memories and Experiences are important moments that have shaped your vampire, crystallized in writing. They make up the core of the vampire’s self—the things they know and care about. An Experience is a particular event; a Memory is an arc of Experiences that are tied together by subject or theme.

I actually love this idea of constrained context. It feels like a great exercise to refocus on a structured narrative, to guide yourself into the shape you want to take. I haven’t figured out how to adopt this secondary structure into this program, yet.

I have to go to jury duty as a member of this democracy. what if I had a summons to contribute to open source software because I use FOSS?

I was so happy to go spend a day exercising my membership in this hallmark of democracy: a participation requirement in return for the benefits I enjoy under due process of the law. Ultimately, I was dismissed because of my connection with the law (several friends and family members practice law).

But it got me dreaming of a world where software developers, having enjoyed the benefits of open-source software and libraries and tools, having built their fortunes on the shared work of the community, were then summoned regularly to use their knowledge and talents to maintain and improve that shared resource.

See, previously:

• Contribute to Open Source as a Code Test
• Good First Issues Are Gifts
• After Reading: Working in Public

My version:

• displays the word count on the textarea when you focus it
• updates the count as you type

Tip

Drag this bookmarklet to your bookmarks bar:
Word Counter

How to use:

1. Drag the link above to your bookmarks bar
2. Click it on any webpage
3. Focus on any textarea to see a live word count

Full code:

document.addEventListener('focusin', (e) => {
  if (e.target.tagName === 'TEXTAREA') {
    const textarea = e.target;
    
    if (textarea.dataset.hasCounter) return;
    textarea.dataset.hasCounter = 'true';
    
    const originalPosition = textarea.style.position;
    
    if (!originalPosition || originalPosition === 'static') {
      textarea.style.position = 'relative';
    }
    
    const counter = document.createElement('div');
    counter.style.cssText = `
      position: absolute;
      bottom: 4px;
      right: 8px;
      font-size: 11px;
      color: #666;
      pointer-events: none;
      background: rgba(255, 255, 255, 0.9);
      padding: 2px 6px;
      border-radius: 3px;
      font-family: monospace;
      z-index: 1;
    `;
    
    textarea.parentElement.insertBefore(counter, textarea.nextSibling);
    
    let rafId = null;
    const updateCount = () => {
      const text = textarea.value.trim();
      const words = text ? text.split(/\s+/).length : 0;
      counter.textContent = `${words} word${words !== 1 ? 's' : ''}`;
    };
    
    textarea.addEventListener('input', () => {
      if (rafId) cancelAnimationFrame(rafId);
      rafId = requestAnimationFrame(updateCount);
    });
    
    updateCount();
    
    textarea.addEventListener('blur', () => {
      setTimeout(() => {
        if (document.activeElement !== textarea) {
          counter.remove();
          if (!originalPosition || originalPosition === 'static') {
            textarea.style.position = '';
          }
          delete textarea.dataset.hasCounter;
        }
      }, 100);
    });
  }
});

I will often explore a solution or script with an LLM agent (e.g. Claude Code) for a while. I’ll iterate on ways to extract data from the current codebase and use that to call MCP server tools, eventually getting to something I’d like to run regularly.

For example, I might want to pull all the recent errors for the application (queried from logs exposed by MCP server tools) and correlate them to find problematic areas of the codebase. In exploring this, the LLM agent can get me to an answer, but the program of getting there is locked and woven away inside the conversation history with the agent.

Increasingly, I’ve been wanting to extract a final executable script from conversations like these, so I can run them again later without needing to re-engage the LLM agent. I’ve found that asking the agent to produce a final script at the end of the conversation is often unsatisfactory, as it may not capture all the nuances of the exploration and often key data or functionality is hidden away behind an MCP server tool call that the agent made during the conversation. As I’ve written about the hidden cost of human-centric tools in LLM workflows, we’re constantly reconsidering the tools offered to LLM agents and finding ways to make them more efficient.

This is where tooling can bridge the gap.

Note

MCP (Model Context Protocol) is a standard for connecting LLM agents to external data sources and tools. MCP servers expose “tools” that agents can call - like searching your notes, querying logs, sending emails, etc. When you use Claude Code or Cursor, they’re calling MCP server tools behind the scenes.

The mcp_cli Tool

To better support scripting over MCP server tools like this, I’ve open-sourced a tool I’ve been using: mcp_cli. It’s simply a CLI for calling and interacting with MCP (Model Context Protocol) servers.

You can use mcp_cli to call MCP server tools directly from the command line, passing in inputs and receiving outputs in a structured way. This allows you to extract the core logic of your LLM agent explorations into standalone scripts that can be run independently.

For example, instead of asking an LLM agent “search my notes for posts about MCP”, you can now run:

gem exec mcp_cli call josh-notes search_posts \
  --query "MCP" \
  --limit 5 | jq '.[] | .text'

This returns structured JSON that you can pipe to other tools like jq to extract just the text content, save to a file, or process in a script.

You can use mcp_cli to:

• Call MCP server tools directly from the command line
• Explore and test MCP server tools and prompts without needing an LLM agent
• Extract and save the logic of your LLM agent explorations into reusable scripts
• Automate regular tasks by scripting MCP server tool calls
• Build your own jigs and script for LLM agents to use instead of relying on the agent to figure out MCP server tool sequences

Note

Read the mcp_cli README for installation and usage instructions and usage examples. But the simplest way to get started is to use gem exec (no installation required): gem exec mcp_cli --help.

This tool builds on two of my recent enthusiasms: MCP tool calls are just cURL calls, and the gem exec pattern for fast distribution of Ruby CLI tools.

It’s trivial to expose MCP server tools to any program because most can be translated into a simple HTTP request or Bash command. That’s essentially what mcp_cli does, along with some niceties around detecting MCP configuration you’ve set up for major LLM agent/editor platforms (Claude, Cursor, etc). And it can do it with zero dependencies beyond Ruby itself.

You could just use cURL directly to call MCP server tools, but mcp_cli makes it quite a bit more user-friendly and easier to integrate into scripts. It also makes it trivial to explore MCP server tools interactively from the command line, which is great for prototyping and testing.

The gem exec pattern means you can run mcp_cli without installation - just like npx or uvx. In this new world of fast-software where LLM agents generate and run code on the fly, I want Ruby to compete with Python and JavaScript for instant execution. Ruby remains a lovely language for building succinct, readable software, and gem exec gives it the same distribution speed.

The Dream

I keep daydreaming of a near future where I have a lengthy conversation with an LLM agent to explore a solution, and at the end of it, I can say “export this as a script” and get back a fully functioning script that uses mcp_cli calls to replicate the logic we explored together. This script could then be run independently, scheduled to run regularly, or even shared with others to use. It’s a jig that guarantees the same behavior as the LLM agent exploration, but without needing to re-engage the agent each time. It’s faster, more efficient, and more reliable.

This directly enables what Anthropic recently described in code execution with MCP: combining multiple MCP tool calls into scripts to reduce context usage, latency, and cost. Where they show TypeScript examples requiring execution infrastructure, mcp_cli makes this immediately practical with bash pipes and standard CLI patterns. An agent can compose multiple MCP operations into a single script that processes data through pipes rather than through the model’s context window - achieving the same efficiency gains without additional infrastructure.

For example, Anthropic shows fetching a document from Google Drive and attaching it to a Salesforce record. With mcp_cli, that becomes:

# Fetch transcript and pipe directly to Salesforce without going through model context
gem exec mcp_cli call gdrive getDocument --documentId "abc123" \
  | jq -r '.content' \
  | gem exec mcp_cli call salesforce updateRecord \
      --objectType "SalesMeeting" \
      --recordId "00Q5f000001abcXYZ" \
      --data "$(cat -)"

The full transcript flows through the pipe, never entering the model’s context window. For a 2-hour meeting transcript (potentially 50,000 tokens), this approach saves those tokens from being processed twice.

Here’s another contrived example:

Before: A 20-message conversation with Claude Code:

“Can you find all my blog posts about MCP from the last month?” Claude searches notes, filters by date, formats results… “Now check which ones mention security concerns” Claude filters further… “Great, now send me a summary via email” Claude composes and sends…

After: A 5-line bash script I can run anytime:

#!/bin/bash
gem exec mcp_cli call josh-notes search_posts \
  --query "MCP" --category "blog" --startDate "2024-10-01" \
  | jq '.[] | select(.text | contains("security")) | .text' \
  | gem exec mcp_cli call josh-beckman-status send_email_to_josh \
      --subject "MCP Security Posts" --body "$(cat -)" --from "mcp_script"

That’s what I’m working on next.

Shopify’s (rough (this isn’t speaking for my employer)) stance on patents is that they are net-negative but it’s best to file patents for things that are valuable, while patent law is still enforced. This protects you from being sued by patent tolls; you don’t have to use them as weapons against others. I like that stance, for a big company like Shopify.

The patent application is available on the UPSTO public search if you search for 20250335250.

In it, Goedecke maps the concepts of Seeing Like A State into a corporate atmosphere:

1. Modern organizations exert control by maximising “legibility”: by altering the system so that all parts of it can be measured, reported on, and so on.
2. However, these organizations are dependent on a huge amount of “illegible” work: work that cannot be tracked or planned for, but is nonetheless essential.
3. Increasing legibility thus often actually lowers efficiency - but the other benefits are high enough that organizations are typically willing to do so regardless.

By “legible”, I mean work that is predictable, well-estimated, has a paper trail, and doesn’t depend on any contingent factors (like the availability of specific people). Quarterly planning, OKRs, and Jira all exist to make work legible. Illegible work is everything else […]

And I tend to think the need for legibility is essentially a need for internal control. It is a known fact that many people in the organization cannot be trusted - this is why the rules of legibility exist. The paradox is that the engineers who complain most loudly about Jira and planning ceremonies are often the ones with the least illegibility budget. They haven’t earned the right to skip the process by first proving they can execute within it flawlessly.

Tip

If you are interested in this type of organizational-/systems-thinking, I highly recommend reading Systemantics - The Systems Bible.

And Goedecke even has some tips on how to break those legibility rules. But I think it’s important to understand how you, as an engineer in that system, can earn illegibility and how you should think about using that to your advantage.

I think you should always know the degree of illegibility that you are consciously allowed by your lead/organization and I think you should approach it like tending a fire or refilling a battery. You should be earning and spending your illegibility budget strategically.

The more senior¹ you get, the more illegible work you’re allowed/encouraged to do.

That’s because you are trusted much more by the organization as you gain a larger scope / get more senior. That’s essentially what a more senior role entails: trusting you to have wider effects with less oversight.

You earn trust by being legible and executing on things well. Shopify’s trust battery metaphor applies here. You earn the right to be illegible by proving that you can be highly legible when necessary.

You also gain that trust by demonstrating that you can make illegible things legible, on demand or at your own will. You can do this by:

1. taking an illegible problem (a vague product request, a very high-level problem) and
2. doing the research and reasoning and legwork to actually define the problem and
3. finding a solution and then
4. communicating that widely and clearly to the rest of the organization

For example: taking “users are frustrated by the latency of the app” and transforming it into “reducing p95 latency of these key operations by 2s by connection pooling and an API change.”

Or this could happen when your VP asks why you’ve been heads-down for the last week and you are able to legibly explain it and they agree with what you’ve been doing. If you demonstrate repeatedly that your illegibility is not a risk, but a speedup and asset, they will give you illegibility budget.

You need to ebb and flow into and out of legibility to get things done in any given month. Being successful as a senior lead is often about having great taste for when you should dip into illegibility reserves to move quickly and experiment and when you should resurface to distribute ideas legibly (building trust with those above your) and when you should embed yourself into the general teams’ legible processes temporarily (building trust with those below you). Spending too much time in illegible work will cause managers above you to question your direction, and never dipping into the wider legibility processes will cause engineers below you to discount your direction because you’re not playing fair.

Leadership is partly about legibly conveying your illegible findings/hunches. This is where I find the most value in being a senior crafter engineer: developing your taste and leaning on it to move quickly - illegibly - and then packing up your work into highly legible projects or features or strategy for the rest of the organization. Just don’t forget to recharge that battery after you’ve spent it.

70 seconds test times for a large real world app. That’s better than Google, better than Apple, better than Dropbox, better than Netflix, and better than Stripe, likely by 10-100x. A test suite that fast keeps developers happy and productivity high. And all in Ruby! One of the world’s slowest programming languages.

Inspired by this, I spent some time this week on my teams’ test suites and got them to be 70% faster in local execution, with a fraction of the noisy log output, with multiple shorthand commands for running “local CI” by the user themselves or by AI agents/editors. This means a much tighter and more accurate feedback loop for their local development (they are instructed to run local CI on all changes before proposing them, running it hundreds of times an hour).

Largely, I did this by:

• parallelizing tests (we have MacBooks with 11 CPU cores!)
• intelligent test selection (instead of all-or-nothing approaches)
• log hygiene (instead of tolerating noise)
• making affordances (easier handholds and documented practices get used much much more)

Before my changes, developers would write some code, maybe run some listing or type-checking locally, then push their changes into a pull-request to let cloud CI tell them if it was fully correct. That’s nice and holistic, but makes the feedback loop take minutes (to hours, if the CI pipelines and worker fleets are backlogged). There’s always a tension here between speed and thoroughness. As in, faster unit tests can suffer from Goodhart’s Law - optimizing for speed over actual correctness. But I believe we can have both: fast local feedback for the majority of cases, with comprehensive cloud CI as the final arbiter.

In the current world, I’m working on 5 branches (git worktrees) concurrently and 4 of them are running AI agents in a loop, feeding on their own feedback and pinging me for guidance. I/they need much faster and more accurate feedback loops to test ideas and be more confident in making changes. I want to get to a place where local CI takes a minute or two and is 99% accurate to what cloud CI will tell you, with one bash command.

Brandur describes why it’s hard to maintain local development feedback loops in large codebases:

Broadly, there are three stages in the long arc of a company’s CI trajectory:

1. Early on, the test suite is run only locally.
2. CI is set up. Test suite is runnable both locally or in CI.
3. Test suite gets too big, or too custom, or has too many dependencies. Test suite is runnable only in CI.

After the transition to stage 3 there’s a brief moment where things are still theoretically recoverable, like if a small team of dedicated engineers worked day and night for a few weeks they could walk things back from the brink, maybe. But generally speaking, you’re caught in the gravity well. After crossing the event horizon, there’s no going back. The overwhelming default will be to descend further into the black hole. The build continues to get more custom and requires more configuration and leverages more cloud constructs. There’s ~0 performance feedback now, so engineers don’t even notice half the time when they write slow tests, further degrading the morass. […] A test suite that can still run on one machine can be shaped and sped up. Once you’re cloud only, all bets are off.

I’m not as pessimistic as Brandur here; I think we can measure performance of testing even in a cloud CI environment, and deliver that feedback (with incentives) to the responsible teams to get them to improve tests. This is slowly happening on my teams. But I do agree that local CI has all the incentive alignment and feedback provided to the end user such that they are much more likely to fix things. Now, I’m running loops faster and cleaning the streets so that others feel encouraged to do so.

Also, the day after I made the big testing speed-ups, there was a cloud CI outage that halted most teams’ feedback loops - but not mine.

When I moved into a Senior Staff Engineer role at Shopify, I really felt this ambiguity. The official role description provided general guidelines, but they hardly mapped to what I spent my hours doing or what I got feedback on in Impact Reviews. I needed a way to define my own job - for my own clarity, and to agree on it with my new manager and peers.

Working with Shopify’s career coach (a great perk that more Shopifolk should take advantage of), I worked on defining my role more clearly.¹

I interviewed several other engineers in my new role and in the level above me. I asked them how they defined their role, what they spent their time on, and how they knew if they were successful. I found a lot of variation but as I summarized my notes, I found I started grouping traits into four sides.

From those sides, I developed a simple mapping framework that’s helped me and others figure out the exact responsibilities of a role and how to evolve it. It takes five minutes as a first pass, and you can keep refining it as you grow.

Draw Your Box

To understand any role (even my own), I started by asking: what would it take to replace this person? What doesn’t happen when they’re gone? As I described what they do and don’t do, a box emerged.

Left Side: Priorities

Write out your priorities and responsibilities. This is the input to your day: how you’re directed to fill your time. These come from company strategies, product initiatives, team goals. If you don’t know these like the back of your hand, your next meeting should focus on clarifying them. It’s your lead’s critical responsibility that you know these like your own name.

At levels of leadership, you have control over these priorities. You should be able to articulate them clearly and negotiate them as needed. If you can’t, you’re not in a leadership role yet. You can spend more or less time on this “Left Side” - thinking about and agreeing on priorities - depending on your appetite and the organization’s needs. But priorities don’t really affect change until acted on, so this side is only half the equation.

Right Side: Output

Write out what you’re actually spending your time doing. This is your output, your impact, the actual work. Look at your calendar, your commits, your reviews, your shipped changes, your mentoring, your 1:1s. Writing something hand-wavy will impede yourself because you won’t see the gap between priorities and activities.

On my first pass at the “Right Side,” I actually mapped out calendar time according to categories of work I was doing every day. I did this for about a month, then averaged it out. This gave me a clear picture of where my time was going, and I could see the gaps between what I thought I was doing and what I was actually doing. I was spending way more time in interviews than I thought, and way less time on strategic thinking.

Bottom Side: Delegation

Write out what you’re not doing, shouldn’t be doing, or have delegated. This is the distinction between your current role and what you used to do, or what team members below you handle. If you’re having trouble filling this side, look at what people one level below you spend their time on. There should be clear differences.

You can also clearly identify things you don’t want to delegate. For example, many Senior Staff Engineers are not in on-call rotations. I specifically agreed with my manager that I remain in rotation so that I stay connected to the product and team and pain points. This is a conscious trade-off of my time, at the expense of other things I could be doing.

Top Side: Reaching

Write out what you see others above you doing, or what you want to be doing but haven’t been given responsibility for yet. This is your growth edge. These are things you can practice and try; things that, once you do them well, will necessarily pull you up to the next level of scope.

For me, this includes things like cross-org prototyping, writing org strategy, and being vocal at the company level. I now allot time in my calendar to work on these things, or ask for stretch assignments that let me practice them. I also look for people above me doing these things and take notes on how they do them.

Using Your Box as a Map

I took this map of my role and wrote it up as a document. It is very specific about how I expect to spend my time, what I prioritize, what I delegate, and what I’m reaching for. I share it with my manager and peers to get their feedback and agreement. This way, we all have a shared understanding of my role and how they can complement it and where I might try to reach.

Once drawn, this box becomes a lens: a map of where you are and where to go. I update mine regularly, whenever org strategy shifts, or when I feel lost. Armed with my box, I have no ambiguity going into impact reviews or 1:1s. I can clearly articulate what I’m doing, why, and where I want to go.

If you draw your current box and don’t like its shape, you need to focus on moving/shaping the box by change one or more of those sides.

Moving to a New Box

Want to move into a new role? You can use this framework two ways:

• Proactively: Map out the box you want to fill, then start doing that work
• Retroactively: Map your current activities and discover you’ve already moved into a new box—best to recognize it and formalize it

Either way, for you to take that position (move into a ‘new box’), the organization must have a gap shaped like that box. You need to align with everyone that:

1. The gap exists
2. You’re already doing work shaped like that box
3. You’re the best person to fill it

Reshaping Your Current Box

Want to change your current role? Focus on moving one or more sides:

• Push the top up by taking on stretch responsibilities
• Pull the bottom up by delegating more effectively
• Shift the left side by renegotiating priorities
• Align the right side by changing how you spend your time

Remember: the box’s total area is generally constant. We only have so many hours in the day. Reaching upward (raising the top edge) requires delegating more (raising the bottom edge). The trade-off exists side-to-side too: spending more time defining priorities (moving left) means less time for productive output (pulling from the right).

Start Drawing

The box is zero-zum but your impact shouldn’t be. Good leaders need to be striving for positive-sum work at all times. By default, time flows like a stream: constantly away from us. The leadership challenge is planting seeds in that box instead of letting effort flow away.

Take five minutes and sketch your box. You might be surprised by the gaps between what you think the shape is and what you actually draw out. More importantly, they might explain why your last review felt off, why you’re exhausted, or where you need to focus next.

I’m on a recent version of the operating system. The calendar is the most basic version Apple Calendar provides me. I am typing the words exactly. Other calendar apps return results based on the same query. I made the event weeks ago. Other search terms return results.

Why do I have to rely on my own memory instead of Apple’s software? Now I question every use of this app, if this most basic functionality does not work.