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 FOOS?

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.

Soon it discovered the upper window and has been drunk on that unfiltered sunlight for so long that it had plastered itself all over the glass. Its leaves were burnt from the heat and it was stifling its own growth.

So I took some time over the weekend to bend it away from the light, back into our lives. I hope it respects my help and lives with us for many more years.

• grouped by project/directory
• take me directly to the relevant terminal pane if clicked
• persisted until I act on them

Read that original post for details, but generally I have Claude send me notifications in two channels: general prompt and hooks.

In that previous configuration, I was using Apple’s built-in notifications via AppleScript. Now, I’ve finally bitten the bullet and upgraded to julienXX’s terminal-notifier package that lets you customize much more. Specifically, it lets you set:

• an application to activate upon notification click
• a shell command to execute upon notification click
• a group identifier for grouping notifications
• and a bunch of other options

So, where previously all the Claude notifications were bunched together and clicking any did nothing but bring up AppleScripts, now I can have each Claude instance send its own notifications to its own group and when I click one I’m brought directly to that Claude Code panel in my terminal.

Installation

You’ll need to install:

• terminal-notifier
• a terminal that allows for programmatic tab/panel activation
  • I use WezTerm
  • (you could replicate this in tmux or kitty, for example)

Once you have those installed, you can install a Claude Code Hook to get a desktop notification whenever it needs you to unblock its progress on a task. It will ping you when it needs permission or input on a task, with details about the permission.

Here’s what I have in my ~/.claude/settings.json user settings:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.message' | xargs -I {} terminal-notifier -message \"{}\" -title \"Claude Hook\" -group \"$(pwd):hook\" -execute \"/opt/homebrew/bin/wezterm cli activate-pane --pane-id $WEZTERM_PANE\" -activate com.github.wez.wezterm"
          }
        ]
      }
    ]
  }
}

Breaking that down:

# parse out the message field from the hook payload sent by Claude Code
jq -r '.message' | \
# pipe that into terminal-notifier as the message
xargs -I {} terminal-notifier -message \"{}\" \
# title it Claude Hook so I can distinguish it from Claude itself
-title \"Claude Hook\" \
# group it by the directory Claude is operating in, suffixed with ':hook'
-group \"$(pwd):hook\" \
# focus this Claude instance's pane within the terminal multiplexer when the notification is clicked
-execute \"/opt/homebrew/bin/wezterm cli activate-pane --pane-id $WEZTERM_PANE\" \
# activate WezTerm when the notification is clicked
-activate com.github.wez.wezterm

This is using WezTerm’s activate-pane CLI command and its $WEZTERM_PANE environment variable for each session.

So that takes care of notifying me when Claude needs permission for something. I also tell Claude Code to notify me when it accomplishes something (and it’s about to stop). Here’s the relevant section in my user settings prompt ~/.claude/CLAUDE.md:

After making a set of changes to files or satisfying a task, you MUST display a `terminal-notifier` notification to tell me what's been done. Use a title and a brief descriptive message. Here's an example:

```bash
terminal-notifier -message "I've finished refactoring the FooBar class into smaller methods" -title "Claude Code" -group $PWD -execute "/opt/homebrew/bin/wezterm cli activate-pane --pane-id $WEZTERM_PANE" -activate com.github.wez.wezterm
```

This is very similar to the hook implementation but I just have it grouping by the present working directory. Since I make git worktrees for each of my different tasks these days, each task tends to have its own dedicated directory.

For this to reliably be available for Claude, I also add a permission to my user settings to allow terminal-notifier commands:

{
  "permissions": {
    "allow": [
      "Bash(terminal-notifier:*)"
    ]
  }
}

Another change I’ve made with this new configuration is that I have the notifications persist until I dismiss or click them. You can set this in System Preferences under Notifications > terminal-notifier.

I know others have been building more… complex interfaces for managing lots of Claude instances, but I like to keep as close to the terminal as possible (as close to the actual Claude and its code/changeset as possible). With this new setup, I’m even more confident running handfuls of concurrent Claude coders. Each one gets its own notification queue and I can be sure of finding them in just a single click.

So, the operators of a merge-queue will often implement staleness checks/guarantees like:

• PRs can only be merged if they are less than X commits behind the target branch
• Code will only be tested in CI if it is less than X commits behind main/trunk

So, the engineers need to get into a habit of tracking staleness and proactively rebasing their changes on the active target/trunk. I”m having to do this quite a lot, so I built gh-pr-staleness.

gh-pr-staleness is a GitHub CLI extension that calculates the staleness (how many commits behind TARGET branch) of a pull request.

This is very useful for determining which PRs are actionably mergeable, especially in highly active monorepo or merge-queue environments. It’s simple and fast and easy to use in scripts.

What I also want is for GitHub to display the PR staleness in their actual pull request user interface, but I think they are resistant because it’s kind of an expensive calculation.

This is my second gh extension. Previously released: gh-view-md - A GitHub CLI Extension for LLM-Optimized Issue and PR Viewing

Installation

gh extension install joshbeckman/gh-pr-staleness

That’s it. If you have the GitHub CLI installed and authenticated, you’re ready to go.

gh pr-staleness <github_pr_url_or_number>
# or, if you are on a branch that has a PR already, it will be inferred:
gh pr-staleness

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

I got inspired by Carl Barenbrug’s site layout that features an off-center, 3-column grid that balances text readability with large inline images. I’ve seen other sites that rely on centered text and centered images for this kind of thing, but this ratio feels much more elegant to me; it evokes the golden ratio.

Carl’s site is very minimalist with low contrast elements. I retained my high-contrast, high-legibility aspects and mostly took layout styles.

The test page has a full list of example elements/rendering, but here are some before+after examples:

So I’ve been increasingly using the command line script (stored in bin/preview-md) that I wrote a while ago:

#!/bin/bash

if [[ "$1" == "-h" ]] || [[ "$1" == "--help" ]]; then
    echo "preview-md - Preview markdown as HTML in your browser"
    echo ""
    echo "Usage: preview-md [FILE]"
    echo "       preview-md \"STRING\""
    echo "       command | preview-md"
    echo "       preview-md < file.md"
    echo ""
    echo "Reads markdown from stdin, a file, or a string argument and opens it as HTML in your browser."
    echo "Uses pandoc to convert GitHub Flavored Markdown to HTML."
    exit 0
fi

if ! command -v pandoc &> /dev/null; then
    echo "Error: pandoc is not installed." >&2
    echo "Please install pandoc to use this tool:" >&2
    echo "  macOS: brew install pandoc" >&2
    echo "  Ubuntu/Debian: sudo apt-get install pandoc" >&2
    echo "  Other: https://pandoc.org/installing.html" >&2
    exit 1
fi

timestamp=$(date +%Y%m%d_%H%M%S)
tmpfile="/tmp/preview-md-${timestamp}-$$.html"

# Add cleanup trap to remove tmpfile after browser opens
trap "sleep 5; rm -f '$tmpfile'" EXIT

echo '<link href="https://www.joshbeckman.org/assets/css/site.css" rel="stylesheet"><style>body { max-width: 800px; margin: 1em auto; padding: 1em; font-family: "IBM Plex Sans", sans-serif; }</style>' > "$tmpfile"

if [[ $# -eq 1 ]]; then
    if [[ -f "$1" ]]; then
        pandoc -f gfm -t html "$1" >> "$tmpfile"
    else
        echo "$1" | pandoc -f gfm -t html >> "$tmpfile"
    fi
else
    pandoc -f gfm -t html >> "$tmpfile"
fi

open "$tmpfile"

This little script allows you to pipe a file or string output or just give it a file path and it will use pandoc to render an HTML page and open it in your browser for you. Beautifully flexible.

I have it rendering the HTML with my own site’s CSS because I like that style and specifically those fonts, but you can remove that by simplifying this line:

echo '<style>body { max-width: 800px; margin: 1em auto; padding: 1em; font-family: sans-serif; }</style>' > "$tmpfile"

In Vim

Since this script is so flexible, I’ve hooked it up in a few key places. For one, I have a (Neo)vim command to open the current buffer as a markdown preview:

command! PreviewMd call PreviewMarkdown()

function! PreviewMarkdown()
    let filepath = expand("%:p")
    execute "!preview-md " . shellescape(filepath)
endfunction

In Claude

And I also have made a Claude slash command to have the LLM agent render its last message to me as a markdown preview in the browser:

---
description: Preview Last Response as Markdown
allowed-tools: Bash(preview-md:*)
---

Please take your last response and pass it directly to the `preview-md` command as a string argument for visual preview.

Do this by:
1. Taking the full content of your previous response
2. Running the command: `preview-md "YOUR_LAST_RESPONSE_AS_MARKDOWN"`

Make sure to:
- Escape any double quotes in the content with \"
- Preserve all markdown formatting (headers, lists, code blocks, links, etc.)
- Include any code blocks with proper language identifiers
- Keep all line breaks and whitespace

Just run the command directly without explanation.

So I can now run /preview-md in any Claude conversation and view the LLM’s response nicely formatted.