Luke Hsiao's blog

Using Changesets in a polyglot monorepo

2026-02-20T00:00:00+00:00

One of the nice things about working in a smaller business is you can enjoy using things that don't need to scale to extreme sizes. One example in the software world is monorepos. While monorepos can scale well (see Google, Facebook, and others), doing so requires special tooling and infrastructure. With plain git, you can only go so far. While you can use it, it has meaningful advantages, like being able to make atomic changes that affect many parts of the system in a single commit, which eliminates whole classes of compatibility and integration issues. You can always split a monorepo later (see git-filter-repo).

So, suppose you're a small-to-medium team using a monorepo. Let's go further and say that this monorepo stores all your company's code, meaning it spans many different programming languages—it's a polyglot monorepo. What tool can you use to manage versioning in a consistent way?

I argue that changesets is a solid choice, even if it's primarily focused on the JavaScript/TypeScript ecosystem.

There is an open discussion about native polyglot monorepo support. However, even without native support, changesets has the hooks needed to implement this as-is for many setups.

Background

For any versioning tool, you are typically looking for how to:

define what content appears in the changelog/release notes
influence the version numbers of the packages
automate the commits doing the actual metadata bumps and tagging
automate the builds that happen in response

changesets assumes per-package semantic versioning (i.e., all packages have their own version). In addition, each package has its own CHANGELOG.md.

The changesets team also has a GitHub Action, changesets/action which importantly allows specifying custom scripts for the version and publish commands. That customization is what gives changesets support for polyglot repositories.

In changesets, engineers commit "changeset" files to the repository that define what content ends up in changelogs, and what packages versions are bumped (i.e., major, minor, patch).

See the changesets documentation for more details.

Implementing an automated release process on GitHub

I'm a fan of just. I also really like uv scripts. The example below uses both.

I'm also going to assume you are in a enterprise setting where all your monorepo is private, not open-source.

Repository setup

My recommended organization (at least at time of writing) is something like the following.

.
├── .changeset
│   ├── config.json
│   └── README.md
├── contrib
│   └── utils
├── docker
│   └── Dockerfile
├── docs
│   ├── package.json
│   ├── pnpm-lock.yaml
│   ├── ...
│   └── pnpm-workspace.yaml
├── Justfile
├── package-lock.json
├── package.json
├── packages
│   ├── python-one
│   │   ├── ...
│   │   └── package.json
│   ├── rust-one
│   │   ├── ...
│   │   └── package.json
│   └── rust-two
│   │   ├── ...
│   │   └── package.json
├── pnpm-workspace.yaml
└── third-party

Put all packages in a packages/ directory, no matter what language they are. I also enjoy having documentation as code, so let's say you have a docs/ directory, too, and that your docs is written in a javascript-based frontend (like Starlight), for the purposes of highlighting a nuance later.

Changeset configuration

With this setup, you can configure changesets with a proxy pnpm workspace at the root with all your packages.

# pnpm-workspace.yaml
packages:
  - "packages/**"

And, declare your changesets dependencies:

// package.json
{
  "name": "example-monorepo",
  "private": true,
  "devDependencies": {
    "@changesets/changelog-git": "^0.2.0",
    "@changesets/cli": "^2.29.0"
  }
}

You should now also update your .gitignore:

node_modules/

Because changesets is built for JavaScript, we also need "proxy" package.json files for all of our packages; changesets uses these to perform version bumps.

These can be as simple as:

// packages/python-one/package.json
{
  "name": "python-one",
  "version": "0.1.0",
  "private": true
}

With this setup, note how we are intentionally trying to exclude our internal docs/ as a pnpm workspace member—we only want to version packages. To do so, declare the docs/ directory its own pnpm workspace, otherwise it will try and combine the docs/ dependencies into the root package-lock.json. This can be as simple as:

# docs/pnpm-workspace.pyml
packages: []

Next, we can add our changeset configuration:

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
  "changelog": "@changesets/changelog-git",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": [],
  "privatePackages": {
    "version": true,
    "tag": true
  },
  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
    "onlyUpdatePeerDependentsWhenOutOfRange": true
  }
}

Automating releases with GitHub

The glue to create polyglot versioning PRs

Next, we want to automate our releases. That is, generating the changelog PRs, bumping package metadata, pushing tags, and triggering builds on those tags.

Let's start with our GitHub Workflow definition, and unpack the scripts it calls.

name: Release

on:
  push:
    branches:
      - main

concurrency: ${{ github.workflow }}-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          cache: npm
      - uses: astral-sh/setup-uv@v7
      - uses: taiki-e/install-action@just
      - run: npm install
      - name: Create Release Pull Request or Tag
        uses: changesets/action@v1
        with:
          version: just version
          publish: npx @changesets/cli publish
          # I like conventional commits
          commit: "chore(release): version packages"
          title: "chore(release): version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.CHANGESETS_PAT }}

The usage of a special personal access token (PAT) is important. If you just use secrets.GITHUB_TOKEN, later workflows that depend on tag pushes will not trigger.

Setting version: just version is the key to polyglot support.

# Version packages based on changesets
[doc('Consume changesets: bump versions, update changelogs, sync native version files.')]
[group('release')]
version:
    npx @changesets/cli version
    uv run --script contrib/utils/sync-versions.py

The meat of the glue for polyglot support then, is how you implement sync-versions.py.

The key bit here is we rely on changesets to bump the versions in package.json for us when we call npx @changesets/cli version, but then it is up to us to propagate that version to the respective language's metadata appropriately.

Here is an example that uses pretty naive parsing. You can write something similar (or better!) for the languages you use.

#!/usr/bin/env -S uv run --script
#
# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///
#
# Sync versions from package.json files (updated by changesets) to native
# package manifests (Cargo.toml, pyproject.toml, etc.).

import json
import re
import subprocess
from enum import Enum, auto
from pathlib import Path

PACKAGES_DIR = Path(__file__).resolve().parent.parent.parent / "packages"


class SyncResult(Enum):
    NOT_FOUND = auto()
    UP_TO_DATE = auto()
    UPDATED = auto()


def read_package_json(pkg_dir: Path) -> dict | None:
    """Read and parse a package.json file."""
    pkg_json = pkg_dir / "package.json"
    if not pkg_json.exists():
        return None
    return json.loads(pkg_json.read_text())


def update_cargo_toml(pkg_dir: Path, version: str) -> SyncResult:
    """Update version in [package] section of Cargo.toml."""
    cargo_toml = pkg_dir / "Cargo.toml"
    if not cargo_toml.exists():
        return SyncResult.NOT_FOUND

    lines = cargo_toml.read_text().splitlines(keepends=True)
    in_package_section = False

    for i, line in enumerate(lines):
        stripped = line.strip()

        # Track which TOML section we're in
        if stripped.startswith("["):
            in_package_section = stripped == "[package]"
            continue

        if in_package_section and stripped.startswith("version"):
            new_line = re.sub(
                r'^(\s*version\s*=\s*")([^"]+)(")',
                rf"\g<1>{version}\3",
                line,
            )
            if new_line != line:
                lines[i] = new_line
                cargo_toml.write_text("".join(lines))
                rel = cargo_toml.relative_to(PACKAGES_DIR.parent)
                print(f"  Updated {rel}")
                return SyncResult.UPDATED
            return SyncResult.UP_TO_DATE

    return SyncResult.UP_TO_DATE


def update_pyproject_toml(pkg_dir: Path, version: str) -> SyncResult:
    """Update version in [project] section of pyproject.toml."""
    pyproject = pkg_dir / "pyproject.toml"
    if not pyproject.exists():
        return SyncResult.NOT_FOUND

    lines = pyproject.read_text().splitlines(keepends=True)
    in_project_section = False

    for i, line in enumerate(lines):
        stripped = line.strip()

        # Track which TOML section we're in
        if stripped.startswith("["):
            in_project_section = stripped == "[project]"
            continue

        if in_project_section and stripped.startswith("version"):
            new_line = re.sub(
                r'^(\s*version\s*=\s*")([^"]+)(")',
                rf"\g<1>{version}\3",
                line,
            )
            if new_line != line:
                lines[i] = new_line
                pyproject.write_text("".join(lines))
                rel = pyproject.relative_to(PACKAGES_DIR.parent)
                print(f"  Updated {rel}")
                return SyncResult.UPDATED
            return SyncResult.UP_TO_DATE

    return SyncResult.UP_TO_DATE

def refresh_lockfiles() -> None:
    """Refresh all lockfiles under the repo to match updated versions."""
    repo_root = PACKAGES_DIR.parent

    print("Refreshing lockfiles...")

    # Cargo.lock — root workspace + any standalone crate lockfiles
    cargo_locks = sorted(
        set(repo_root.glob("Cargo.lock")) | set(PACKAGES_DIR.rglob("Cargo.lock"))
    )
    for cargo_lock in cargo_locks:
        lock_dir = cargo_lock.parent
        rel = lock_dir.relative_to(repo_root) or Path(".")
        print(f"  cargo update --workspace in {rel}")
        subprocess.run(["cargo", "update", "--workspace"], cwd=lock_dir, check=True)

    # uv.lock — Python packages
    for uv_lock in sorted(PACKAGES_DIR.rglob("uv.lock")):
        lock_dir = uv_lock.parent
        print(f"  uv lock in {lock_dir.relative_to(repo_root)}")
        subprocess.run(["uv", "lock"], cwd=lock_dir, check=True)

def main() -> None:
    print("Syncing versions from package.json to native manifests...")
    print()

    updated = 0
    for pkg_json in sorted(PACKAGES_DIR.rglob("package.json")):
        pkg_dir = pkg_json.parent
        pkg_data = read_package_json(pkg_dir)
        if pkg_data is None:
            continue

        version = pkg_data.get("version")
        if version is None:
            continue

        name = pkg_data.get("name", pkg_dir.name)
        print(f"{name} @ {version}")

        results = [
            update_cargo_toml(pkg_dir, version),
            update_pyproject_toml(pkg_dir, version),
        ]

        if any(r == SyncResult.UPDATED for r in results):
            updated += 1
        elif all(r == SyncResult.NOT_FOUND for r in results):
            print("  (no native manifest found)")
        else:
            print("  (already up to date)")

    print()
    print(f"Synced {updated} package(s).")
    print()

    refresh_lockfiles()
    print()
    print("Done.")


if __name__ == "__main__":
    main()

Reacting to package tags

In the standard changesets flow, you will now have a pull request on GitHub with the appropriate CHANGELOG.md updates, as well as the metadata updates for all the relevant packages.

Once that is merged, the very same action will run, realize all the .changeset files are consumed, and push tags.

With our example configuration, changesets will only push tags, not publish packages, because we set

"privatePackages": {
    "version": true,
    "tag": true
}

in our .changeset/config.json and have all the packages set to private: true.

Typically, you'll then want to react to these pushed tags. For example, to build new docker images.

For that, just set up your docker build workflows to trigger on the relevant tags for your package. For example, maybe you have a few docker images, one of which should trigger only when certain packages are updated.

on:
  push:
    tags:
      # trigger only on these packages updating
      - 'rust-one@*'
      - 'python-one@*'

on:
  push:
    tags:
      # trigger on all packages updating except python-one
      - '*@*'
      - '!python-one@*'

Summary

changesets can manage per-package semantic versioning and changelogs in polyglot monorepos today, even without direct native support for multiple languages. The trick is to treat JavaScript package manifests as the canonical source of version bumps, and then syncing those bumps via your own scripts to the language-native manifests.

A few gotchas exist (like explicitly making independent pnpm-workspace.yaml files for subdirectories you want to be independent, or using a separate personal access token to push tags), but none are blockers to being able to benefit from changesets's convenient workflow.

I used to suggest versioning monorepos with a single global version using a tool like semantic-release. Since trying changesets, I'm sold on the benefits of letting people write commit messages for future internal engineers while also adding a separate changelog note for end users. These are often two distinct audiences, and relying on a single conventional commit to serve both is often suboptimal.

Fixing missing Omarchy boot entries

2026-01-24T00:00:00+00:00

In a normal Omarchy installation, the expected behavior is that you will see two new boot options in your BIOS: Omarchy and Limine. There are two for good reason. Omarchy boots straight to Omarchy, and is what should be first in your boot order, typically. Limine goes to the Limine boot loader menu, which allows you to restore from snapshots, which is useful.

However, in my experience, sometimes a fresh install will fail to set up these boot entries. Unfortunately, I have not spent the effort to discover the true root cause. Regardless, fixing it is easy.

As a concrete example, I recently installed Omarchy on a ThinkPad T14 Gen 4, and after what appeared to be a successful installation, I had the Limine boot entry, but was missing the Omarchy one, meaning when I booted, I was wasting time in the Limine menu each boot.

The /boot partition was set up as expected, though.

❯ lt /boot/EFI/
drwxr-xr-x    - root 23 Jan 15:50 /boot/EFI
drwxr-xr-x    - root 23 Jan 15:48 ├── BOOT
.rwxr-xr-x 291k root 23 Jan 15:48 │   ├── BOOTIA32.EFI
.rwxr-xr-x 283k root 23 Jan 15:48 │   └── BOOTX64.EFI
drwxr-xr-x    - root 23 Jan 15:49 ├── limine
.rwxr-xr-x 287k root 23 Jan 15:49 │   ├── limine_x64.bak
.rwxr-xr-x 283k root 23 Jan 15:49 │   └── limine_x64.efi
drwxr-xr-x    - root 23 Jan 15:50 └── Linux
.rwxr-xr-x  47M root  6 Jan 10:29     └── omarchy_linux.efi

And, with that, it's very easy to fix the boot entries with efibootmgr.

First, let's look at drive names.

❯ df -h
Filesystem        Size  Used Avail Use% Mounted on
dev               7.7G     0  7.7G   0% /dev
run               7.7G  1.9M  7.7G   1% /run
efivarfs          196K  118K   74K  62% /sys/firmware/efi/efivars
/dev/mapper/root  237G   21G  214G   9% /
tmpfs             7.7G  580K  7.7G   1% /dev/shm
none              1.0M     0  1.0M   0% /run/credentials/systemd-journald.service
none              1.0M     0  1.0M   0% /run/credentials/systemd-resolved.service
none              1.0M     0  1.0M   0% /run/credentials/systemd-networkd.service
tmpfs             7.7G  8.0K  7.7G   1% /tmp
/dev/mapper/root  237G   21G  214G   9% /var/log
/dev/mapper/root  237G   21G  214G   9% /var/cache/pacman/pkg
/dev/mapper/root  237G   21G  214G   9% /home
/dev/nvme0n1p1    2.0G  144M  1.9G   8% /boot
tmpfs             1.6G  228K  1.6G   1% /run/user/1000

With these two pieces of information, adding an Omarchy boot entry is simple.

First, you can run sudo efibootmgr to see your existing boot entries. You'll be able to confirm whether you're missing entries here.

I should've recorded the output before the fix, but didn't think I'd write a post about it until after the fact. Hindsight is 20/20.

Then, to add a new boot entry you can simply run:

sudo efibootmgr \
  --create \
  --disk /dev/{drive-name} \
  --part {partition-num} \
  --loader /path/from/boot/to/efi \
  --label "YourLabel"

So, given the output of df, where I see my /boot is mounted to /dev/nvme0n1p1, I know /dev/nvme0n1 is my drive name, and it's on p1 or partition 1. Thus, my specific call would be the following.

sudo efibootmgr \
  --create \
  --disk /dev/nvme0n1 \
  --part 1 \
  --loader /EFI/Linux/omarchy_linux.efi \
  --label "Omarchy"

Same deal if you were missing a Limine entry (using my specifics as an example again).

sudo efibootmgr \
  --create \
  --disk /dev/nvme0n1 \
  --part 1 \
  --loader /EFI/limine/limine_x64.efi \
  --label "Limine"

Once that's done, you should be able to see the boot entries in efibootmgr, as well as in your BIOS.

❯ sudo efibootmgr
BootCurrent: 0000
Timeout: 0 seconds
BootOrder: 0000,0001,001E,001F,0021,0020,0022,0023,0024,0025,0026
Boot0000* Omarchy       HD(1,GPT,e7363f48-0ae8-47bb-bb0f-298baceaff27,0x800,0x400000)/\EFI\Linux\omarchy_linux.efi
Boot0001* Limine        HD(1,GPT,e7363f48-0ae8-47bb-bb0f-298baceaff27,0x800,0x400000)/\EFI\limine\limine_x64.efi
Boot0010  Setup FvFile(721c8b66-426c-4e86-8e99-3457c46ab0b9)
Boot0011  Boot Menu     FvFile(126a762d-5758-4fca-8531-201a7f57f850)
Boot0012  Diagnostic Splash Screen      FvFile(a7d8d9a6-6ab0-4aeb-ad9d-163e59a7a380)
Boot0013  Lenovo Diagnostics    FvFile(3f7e615b-0d45-4f80-88dc-26b234958560)
Boot0014  Asset Information     FvFile(da465b87-a26f-4c12-b78a-0361428fa026)
Boot0015  Regulatory Information        FvFile(478c92a0-2622-42b7-a65d-5894169e4d24)
Boot0016  ThinkShield secure wipe       FvFile(3593a0d5-bd52-43a0-808e-cbff5ece2477)
Boot0017  ThinkShield Passwordless Power-On Device Manager      FvFile(08448b41-7f83-49be-82a7-0e84790ab133)
Boot0018  Wi-Fi Configuration   FvFile(d3aaff0f-cb22-4792-896c-802c2e9383ba)2d004100700070000000
Boot0019  Reinstall Windows from Cloud  FvFile(3edbaac4-5017-4870-8cc4-721f9ef1974f)2d004100700070000000
Boot001A  Intel(R) MEBx FvFile(29a70110-7762-4211-ae88-fab19b7665be)
Boot001B  Startup Interrupt Menu        FvFile(f46ee6f4-4785-43a3-923d-7f786c3c8479)
Boot001C  Rescue and Recovery   FvFile(665d3f60-ad3e-4cad-8e26-db46eee9f1b5)
Boot001D  Lenovo Memory Self Repair     FvFile(4ddd67e7-bdf5-4473-8ab0-02821c084338)
Boot001E  USB CD        VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,86701296aa5a7848b66cd49dd3ba6a55)
Boot001F  USB FDD       VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,6ff015a28830b543a8b8641009461e49)
Boot0020  NVMe0 VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,001c199932d94c4eae9aa0b6e98eb8a400)
Boot0021* USB HDD       VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,33e821aaaf33bc4789bd419f88c50803)
Boot0022  PXE BOOT      VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,78a84aaf2b2afc4ea79cf5cc8f3d3803)
Boot0023  LENOVO CLOUD  VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,ad38ccbbf7edf04d959cf42aa74d3650)/Uri(https://download.lenovo.com/pccbbs/cdeploy/efi/boot.efi)
Boot0024  ON-PREMISE    VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,ad38ccbbf7edf04d959cf42aa74d3650)/Uri()
Boot0025  Other CD      VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,aea2090adfde214e8b3a5e471856a35400)
Boot0026  Other HDD     VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,ca88c2349e7ae947beeb43038a5aeae700)
Boot0027* IDER BOOT CDROM       PciRoot(0x0)/Pci(0x14,0x0)/USB(11,1)
Boot0028* IDER BOOT Floppy      PciRoot(0x0)/Pci(0x14,0x0)/USB(11,0)
Boot0029* ATA HDD       VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,91af625956449f41a7b91f4f892ab0f6)
Boot002A* ATAPI CD      VenMsg(bc7838d2-0f82-4d60-8316-c068ee79d25b,aea2090adfde214e8b3a5e471856a354)

Setting Omarchy to your first boot option will then boot straight to Omarchy.

The outsized impact of cultural idiosyncrasies

2026-01-21T00:00:00+00:00

In the context of companies, cultural idiosyncrasies are fascinating to me. I'm of the opinion that culture (including mission, principles, and values) is one of the biggest factors that differentiates companies from one another. Sure, the product or service is often the largest differentiator, but culture—and in particular, cultural idiosyncrasies—has an outsized impact on both public company image as well as internal culture and job satisfaction.

Why?

I believe it's because these idiosyncrasies are evidence of what a company does, and not just what it says it does. They reflect principles and values in uniquely powerful ways to both potential customers and employees.

Some examples

Let me draw some examples from my own lived experience, and I'm sure I'm missing some compelling examples further back (Sun Microsystems, Xerox PARC).

Also, and importantly, I'm not saying any of these idiosyncrasies are "right", but I am saying they all have an outsized impact on my perception of the companies.

Google

One of the earliest examples from my own memory is Google. Not only did I experience how Google Search took over the market with its minimalism and effectiveness, but I also grew up hearing all sorts of news about how Google was "the best place to work". In those articles, did they talk about search? Nope. They talked about cultural idiosyncrasies: free meals from on-site cooks, nap pods, 20%-projects, slides in the lobbies, micro-kitchens, laundry services!

Oxide Computer

Oxide is a prime example. They frequently feature in online discussion, but in my perception, the majority of this discussion isn't about their product; it's about their culture, and often with highly positive sentiment. They find this so core to their company that they dedicated a podcast episode to it.

Some examples are demo Fridays, morning water-cooler, no-meet Wednesdays, recorded meetings, dog-pile debugging, RFDs (requests for discussion), no performance reviews, an overwhelmingly writing-focused hiring process, and uniform and transparent pay, to name a few.

GitLab

GitLab may not have the popularity of GitHub, but they have made a strong impression on me for at least two of their idiosyncrasies.

One of the first of these was particularly prominent during the COVID-19 pandemic: a global, all-remote workforce. They are one of the largest all-remote companies with over 1,500 members in 65+ countries.

They are also known for their transparent, handbook-first approach. They publish their handbook for all to see. This is not brief, either. It comprehensively covers everything: engineering, finance, sales, legal, and more.

This is an incredible show of transparency and goodwill in sharing hard-earned lessons publicly.

37signals

Not to be outdone, the 37signals folks also publish their handbook.

In their case, they have also published highly profitable books about their idiosyncrasies and culture, such as Shape Up (an engineering methodology that many companies are now adopting), REWORK (unconventional business advice), and REMOTE (on remote work).

They also have idiosyncrasies like Omarchy, an opinionated distribution of Arch Linux. They liked it so much they ditched MacBooks as the standard-issue developer laptop and switched to Framework laptops.

Tonari

Tonari is a small Japanese tech startup making some of the most interesting audio/video portals available.

Despite being very small, they contribute significant pieces of their stack to open source, such as innernet, a private network system using WireGuard under the hood.

They also value a heterogeneous compute mix for their developers and were early on the Rust train (note how each of the four engineers mentioned in this blog runs a different operating system: macOS, Arch, Ubuntu, and Pop!_OS).

Palantir

Palantir breaks the mold a bit in this list, because most of the public discussion around it is controversial and focused on the ethics of its business.

That said, they are known for their idiosyncratic chaos culture, where "everything is up for debate"—even a random engineer confronting the CEO at all-hands—and where they do almost anything to move fast—like chartering a private jet to Palo Alto to get the engineering team together during the COVID-19 pandemic.

People I know who have worked there tell me this is an accurate representation.

Jane Street

Notoriously, it's the OCaml shop people know about. Compensation so high, even for interns, that it's an idiosyncrasy.

And, most notably to me, they have one of the most interesting tech blogs around. For example, their code review process has such a good reputation that other tech bloggers carve out exceptions for it when talking about code review problems. They care so much about rigor in tests that they not only leverage bleeding-edge strategies like deterministic simulation testing (DST) but they also led the funding round of Antithesis, the pioneers in DST. This is highly idiosyncratic.

Amazon

Even for massive companies like Amazon, some cultural idiosyncrasies still have an outsized impact.

For example, I suspect most people have heard of Amazon's 6-page memo approach to meetings. In this approach, no attendees prepare beforehand, and instead of using PowerPoint, Amazon executives sit around a table and read six-page memos in silence before discussion commences.

Likewise, Amazon is well known for its two-pizza teams, where the idea is that a team should not be larger than can be fed with two pizzas. That way it remains small, cohesive, and has efficient working relationships.

Zappos

Zappos is well known for its unique pay-to-quit approach to making sure the team is invested. It provides an attractive off-ramp for those who are not as committed or interested in the company after their training period, instead of staying despite lacking passion the work.

Patagonia

Patagonia is well known for its Let My People Go Surfing policy, which prioritizes work-life balance, purpose, and employee autonomy. The policy encourages staff to embrace flexibility and spontaneity in balancing work and play. If the waves are good or the powder fresh, staff are trusted to step away, surf, or enjoy nature, returning to work with renewed purpose.

Valve

Valve is the famously "flat" company, or "flatland", as their public handbook calls it. They "don't have any management, and nobody reports to anybody." They playfully poke at Google's 20% time by saying that at Valve, it's 100%. Of course, this comes with its challenges, but this idiosyncrasy has become an integral part of my perception of Valve.

Vannevar Labs

Sample size of 1, but I've had a friend that really appreciates Vannevar's $250/month stipend for mental/physical health and $300/month stipend to pay for house cleaners. These dedicated benefits are particularly on-point for a mostly remote team. As a company that heavily hires forward deployed engineers (FDEs), they also have very high autonomy.

Thoughts

I'm sure this list could be ten times longer with some more thought. But perhaps that supports the point. All of these examples came almost immediately off the top of my head!

If you're running a company, I think it's important to be intentional about your culture. Both in the mission, principles, and values you profess and in the idiosyncrasies that uniquely evolve because of them.

People will talk about your cultural idiosyncrasies to the benefit or detriment of your company. Your employees will reach for your idiosyncrasies when they talk about what is good or bad about working for your company. Your customers will point to your idiosyncrasies as evidence for or against value alignment. Your future employees will compare and contrast your idiosyncrasies with their experiences as they consider their next career move.

And random people like me will evidently spend (too much?) time thinking about your idiosyncrasies and trying to theory-craft the perfect set of cultural idiosyncrasies for their hypothetical future company.

2026 is the year I return to rigorous planning

2026-01-08T00:00:00+00:00

2026 is the year I return to some rigorous planning and productivity habits I've let slip over the years. Specifically, time-block planning (à la Cal Newport) and full-task capture (à la Getting Things Done (GTD) by David Allen).

The motivation for this change is that I anticipate this will be an unusually busy year for me at work, at home, and in my communities. I want to make sure I make the most of the opportunities.

The motivation for this post is twofold. First, for a bit of documentation and musing on how I have specifically implemented these ideas this time around. Second, for a little bit of self-accountability. Who knows, maybe this will also motivate someone else to reevaluate their productivity habits.

While we're only a week into this year, this is a system I have used extensively since early high school—just less so recently. Consequently, I already know that it is an effective catalyst for my own productivity.

The methods

I'll refer you to the links at the top of this post for more thorough exploration on what these systems mean. However, for the purpose of this post, I want to briefly describe these two methods.

Time-block planning

Time-block planning is an intentional method for planning your days—hopefully a method that leads to being able to do deep work, which I, in agreement with Newport, believe is vitally important in our modern distracted world. This is particularly well-suited to knowledge workers, and it also served me well when I was a student.

Many knowledge workers spend their day reacting. Reacting to messages, emails, changing priorities, changing requirements, meetings, etc. This often leads to anxiety, overload, a lack of clarity, a feeling of chaos, and often impedes progress on things that require deep, focused effort.

Time-blocking is all about proactive intention. Each day you fill out your calendar with time blocks representing a preliminary plan that gives every minute a purpose. If you get knocked off this schedule, you simply update it the next time you have a chance.

This sounds simple.

It is.

You can get things done in a chaotic environment.

Full task capture

This probably isn't the right term in a GTD context, but it conveys the methodology I find useful. The idea here is that you should capture everything that has your attention (tasks, ideas, etc.) into an external system so that you can free your mind from lingering unproductively and unreliably on them. This capture should be both complete and as immediate as possible, and should go into a single designated spot (e.g., an "inbox"). Then, you can process this list later with intention, either scheduling things, stashing things for later, or intentionally discarding things.

If you're the type of person who frequently has things "fall through the cracks" or finds yourself up at night repeatedly looping through things you need to do, you might find this technique refreshingly freeing.

My implementation

So, now that you have the basic ideas, I want to share my current implementation.

Implementation is a highly personal choice. Some people prefer pen and paper (like Newport does). To go further, some people might implement these ideas in the context of notebook-specific systems, like bullet journaling, or a Hobonichi Techo.

Others might use special, purpose-built apps on their computer or phone. Others might use intentionally basic apps or systems like todo.txt. Others might use a big whiteboard in their office.

While those who know me know I love stationery, I've found that the single most important factor for success with these systems is low friction. If I remember a task in the middle of the night, and that means I need to go find a pen and my notebook, it's not happening. But I can always find my phone for a quick note.

So, I use Google Calendar and Google Tasks. They are already on my phone. They are easily accessible on both phone and computer. They have sufficient features to implement the systems.

Time block planning in Google Calendar

A good work week usually looks something like this.

Time-blocking in Google Calendar.

I have several Google accounts, so they all feed into a master view on my phone that includes time blocking before and after work hours.

While the image above shows a fully-populated week, I actually only time-block one day ahead. That is, during the "shutdown ritual" of the day, I review the tasks and ideas I may have captured within the context of my current task lists, then time-block the next day based on those tasks. One exception here is recurring events are scheduled as recurring, and thus are already populated on their respective days. While the screenshot above doesn't show this well, it's also important to have some empty buffer time to absorb unexpected events, or variance in how long things take. This is another advantage of digital over paper: I can easily schedule events far into the future and not lose the information. With a paper planner, it's hard to schedule someone's wedding in a year.

As the day proceeds, if things do not go according to plan, I adjust the blocks on the calendar to reflect reality. This is a valuable exercise both as an artifact to review where I actually spent my time on a given day and as useful feedback to improve my time estimations. For example, you may notice I spent about three full days testing in the screenshot above. I had initially anticipated that would take a single day. The act of making things reflect reality is a good way to calibrate myself on how long to expect for similar work. It goes the other way too: sometimes things take much less time than expected.

When it comes to deep work, it feels good to see those larger, uninterrupted blocks of time. If those blocks were short and highly interrupted, I'd take it as a signal to make adjustments that allow me to do deeper, more meaningful work with less context switching.

You can see how time-block planning would work effectively in a knowledge worker's or student's life, but likely not in the life of an emergency room nurse.

Full task capture in Google Tasks

The last time I used Google Tasks was a few years ago, and they've made some nice improvements since. For the purpose of full task capture, I keep a relatively simple system. Not quite as simple as a todo.txt, but still minimal while offering nice organization features like recurring tasks, scheduled tasks, and sub-tasks.

Full task capture with Google Tasks.

I organize Google Tasks somewhat Kanban-style.

Google Tasks has a default list you cannot delete. I use that as my "inbox", but I title it "Maybe?". All quick notes go into here for later processing if I don't have time to put it in the right list immediately. If I decide to do it, it goes into the appropriate list. If I don't, it gets deleted from here. I sort this with "My order" sorting so I can arbitrarily sort it with highest priority at the top.

On the left, I have my "Not now" list. These are things I want to do at some point, but they aren't urgent. I just don't want to lose them, so this is much like a backlog. This is also sorted "My order", with highest priority at the top.

In the middle, I have "In progress", which could also be named "To do". These are things I'm actively working on. Everything in this list has a date indicating when I intend to work on it. I might add deadlines if relevant. I sort this list by "Date" so that the things I need to do today are always up top, and I can quickly see what I need to do next.

This is the only list that I mark things as "complete" from!

Conveniently, these also show up in Google Calendar as you do them, providing a useful artifact of tasks you completed that day.

Next, I have "On hold". These are things I was working on, but are now blocked for some reason. A holding area. When they become unblocked, they will go back to "In progress" with the appropriate dates. Sorted in "My order", with highest priority at the top.

Finally, "Ideas". This is just a list of ideas sorted in "My order" with most interesting at the top. I also find it handy to jot down things like gift ideas for people in the moment I discover them.

When I add these items, I also occasionally use todo.txt-style tags like +{project} or @{context}, even though Google Tasks has now way to filter for those.

When I was a student, this was a superpower; I still give the advice today. As a student, I would start each semester by inputting all coursework dates from every class syllabus. I always knew what was due, which weeks would be heavy, and which would be light.

Another common question from fellow knowledge workers is how this fits in with other task tracking systems you might have at work (e.g., Linear, Jira, etc.). The answer there is that this is far more lightweight. I'm not writing lengthy descriptions or logging progress and notes on these items. These are written as "just enough" context to know what they refer to clearly. This is a personal system that complements the systems your teams might be using.

Thoughts so far

I should never have stopped doing this! When you develop a productivity system that works for you personally, it feels like a bandwidth multiplier.

There is also much more to discuss about setting goals, having a vision for your career, and other high-level planning that ultimately feeds your day-to-day work, but those are out of scope for this particular post.

This is all about the nitty-gritty of day-to-day productivity.

This system might not work for you, but I hope it has sparked some ideas as you work on your own systems.

My favorite software in 2025

2025-12-17T00:00:00+00:00

As an engineer, I'm always refining which tools are in my toolbox. Here's a big list of software I enjoy using in 2025. Like 2024, I'm omitting things I don't touch at least once in a month. So, please refer to 2023 for some honorable, but less regular, mentions.

The List

aerc

This is my email client of choice. I tried mutt, but the configuration was too complex for me. aerc, on the other hand, is very simple to configure, and works great in the terminal. I'm an advocate for using plaintext email, and aerc works great for using email for git patches. It lets me use my $EDITOR of choice, search and filtering works well, and it's quick. Let me also call out a new discovery here: carddav-query. This works far better than the largely unmaintained goobook I was using previously.

atuin

You don't realize how useful synced shell history is until you try it. You should absolutely try it. Installed it on a whim, and have been delighted since.

bat

I've aliased cat to bat and never looked back. The syntax highlighting, the line numbers, the git integration, the paging, it all just makes it nice to use.

Berkeley Mono (TX-02)

This is my favorite coding font, and this year they released new versions! Not only was it worth the initial $75, I paid more for a new web license. Importantly, the new version includes more slender versions and variable fonts, so I really don't miss Iosevka anymore.

bottom

btm is a better top (and htop). I originally thought I wouldn't need more than htop, until I tried to run it on a massive server with over 150 cores. htop you need to configure differently to see anything at all (dropping all the CPU bars), and it is slow. btm handles it just fine out of the box. The filtering on the processes widget is very convenient. The ability to see all the other stuff like temps, GPU memory usage, network utilization, disk utilization, those are all cherries on top. I'll also call out that btop is also very fun, but I find bottom more useful.

chezmoi

I've tried a few different ways to manage my personal dotfiles. Before chezmoi, I stored them as a bare git repo, as found on HN. But, the killer feature for me was templating. Even though I don't use much of chezmoi's fancier features, just being able to use templates so that I could populate dotfiles based on the machine I was on was great.

Ever since switching to Omarchy, I've revamped usage of my dotfile repo.

choose

choose is a human-friendly alternative to cut and (sometimes) awk. I used to use awk for most of this type of task, but choose just makes it easier. It makes it easy to chop out columns I want while piping things around.

codebook

codebook is another spell-checker for code, like typos. It's high quality and I enjoy it as a default LSP for text.

D2

This is a new addition. In general, I'm a big fan of "declarative diagraming", and D2 is the new one on the block (vs PlantUML, MermaidJS, GraphViz, etc.) So far, I love the syntax and functionality. If I'm drawing up something quick that doesn't warrant something like draw.io, I've been reaching for D2 first and excalidraw second. Their TALA layout engine is proprietary, but looking quite nice.

delta

delta is the best syntax-highlighting pager for git, diff, and grep output I've seen. I used to use diff-so-fancy, but since switching to delta, I haven't looked back. This makes the experience of using git in the terminal much improved.

difftastic

difftastic is the another key tool I use side-by-side with delta. It is a structural diff tool that understand syntax. This means that many times, it is a much more succinct diff for files. I have this aliased in git as well, and often use both delta and difftastic when looking at diffs.

dust

This is like du, but better. It's faster, and its visually nicer. This is my go-to way for figuring out where my disk space is being used.

eza

This is a replacement for ls that is just better. Similar to bat, after aliasing ls to eza, I haven't looked back.

fd

fd is a replacement for find. Similar to exa and bat, this is another rust-based tool that feels more intuitive and does the job better.

fish

Fish has been a great shell. I just used plain bash before this. I switched a couple of years ago, and while I don't think there has been any particularly large "killer feature" for me, I have had no reason to switch to anything else since. The UI niceties (e.g., autosuggestions, tab completions, syntax highlighting, 24-bit color) all make the terminal experience pleasant. It's also being slowly rewritten in rust.

I'm interested in trying nushell at some point soon, but I haven't jumped in yet.

Ghostty

I've switched from Wezterm to Ghostty. While there is still 1 killer feature I'm missing, I've thoroughly enjoyed Ghostty's performance and simplicity. I appreciate the dedication to correctness and performance.

git

git is my favorite version control software. Yes, that might be because it's pretty much ubiquitous, and I've spent the time to get over the learning curve. It's a fantastic tool.

If you haven't leveraged aliases (here are mine), then I hope reading this is a plug to go enjoy those.

Since it's git-related, I'll also mention I'm a strong proponent of conventional commits, and using useful git trailers like they do for git itself and Linux.

While we're all used to the PR/MR type of workflow, if you haven't experienced working with git the truly distributed way (via git-send-email) its also worth trying.

git-absorb

This fits exactly into my normal git workflow, and it's algorithm is simple and effective. If you are used to making fixup commits yourself, definitely try this out!

git-cliff

If you're following conventional commits, then git-cliff is a fantastic tool for automatically generating useful changelogs. I use this in the vast majority of my repositories.

git-grab

This is a small tool that clones a git repository to a standard location, organized by domain name and path. I used to just have a repos/ directory full of random repos. At one point, I tried to organize these better (e.g., "personal", "forks", etc.), but it didn't work well. Now, I just use git-grab and stick with that structure.

gping

"Ping, but with a graph." That's an accurate description, but don't underestimate the niceness of a graph. It also has features like graphing multiple hosts at the same time, or graphing execution times of commands. Similar to bat, exa, fd, btm, if you have gping, you really don't need to go to ping anymore.

helix

I'm embarrassed to say, but I didn't really learn how to use vim until 2017. But, that was such a positive experience that I've been on modal editors since. I went from vim, to neovim, and then, most recently, to hx.

Going from electron-based editors to vim was a big jump. Going from vim to these others was just incremental. I had developed a very custom nvim experience with plugins and all sorts of customizations.

That, surprisingly, is part of the reason I've enjoyed hx so much: I use it pretty much stock. It's got all the right basics built-in (LSP, file pickers, tree-sitter, etc.) such that I don't need to customize it much.

If you're interested in experimenting with a new editor, I highly recommend helix.

hurl

hurl is an easy way to test HTTP requests with plain text. Since it can chain requests, capture values, etc., I actually often use it to "script" some request chains for testing purposes. I haven't used this extensively, but so far, it seems very useful.

hyperfine

hyperfine is the best command-line benchmarking tool around. It should be the standard, in my opinion. If you ever want to benchmark how long a particular command-line command takes in a robust way, look no further.

jaq

jaq is a clone of the ubiquitous jq JSON processing tool. But, it is more correct and faster. As long as you aren't doing crazy stuff with jq, jaq might be an easy alias to make for some small wins.

jless

jless is a command-line JSON viewer. If you're viewing JSON files with some combination of jq (or jaq), less, cat, etc., then jless might be just what you're looking for. It makes it easy to quickly peruse a JSON file and espand/collapse objects and arrays.

Jujutsu

jj is a git-compatible version-control system that is both simple and powerful. This is the surprise of the year for me. While it doesn't really solve any concrete problems for me from git, it does do some fun things, like let me rebase all of my branches at once.

I've enjoyed the experiment using this over the past couple months, and suspect I will continue to do so.

just

just is a versatile command runner that takes inspiration from make, but without the baggage. This is a new entry on this list, and not one I have used as extensively, but so far, it seems nice. There are many situations where I have a Makefile with a bunch of .PHONY targets because I'm just trying to use make as a command runner. Well, now I have a nice command runner.

There are several repositories I've worked with with a scripts/ folder that could just be absorbed into a justfile.

lychee

The web is great, but it is unfortunate when you come across broken links. lychee is a great way to help prevent that (they even have a GitHub Action). It's incredibly fast. I use it to check most of my repositories for dead links, as well as my blogs.

Mosh

The mobile shell that allows roaming, supports intermittent connectivity, and provides intelligent local echo. A recent release also brought true color support, which was the only thing that bothered me before. 99% of the time I say I'm "ssh"-ing, I'm actually just using mosh. The ability to start a session, get a tmux session all set up, close my laptop, go somewhere else, open it and just pick up where I was is too good to ignore.

This is an example of software that is pretty much "complete". Lack of activity on the repository shouldn't scare you one bit, its because it has a rock solid history and does what it sets out to do.

mpv

mpv is the best media player I know of. I prefer this to VLC or others. It "just works" and is extremely minimal and performant. It's integration with yt-dl (or better yet, yt-dlp) means I often just play web videos (even YouTube) via mpv.

Omarchy

Omarchy is a beautiful, modern, and opinionated Linux distribution build on hyprland and Arch. This is my favorite find of the year. I'm a big fan of tiling window managers and Linux on the desktop. Earlier in the year, I built my own spin of Wayblue sway, but since Omarchy came out, it has checked every box for me.

There are many things that are just integrated incredibly well within this distro. I won't bother calling them out explicitly as items on this list, but I'll highlight that Omarchy uses tools like impala, gpu-screen-recorder, or things like waybar, hyprland, walker, limine, etc., all beautifully. I wouldn't know about many of these were it not for Omarchy, and now I just use them.

passage

passage is a fork of pass, very simple password store that follows Unix philosophy. Unlike pass, passage uses age encryption as the backend.

I don't miss having a password manager app on my mobile phone, so on desktop, this has served me well. I'm a big fan of its simplicity, and the fact that my passwords are just flat files I can version in a git repo.

In addition, I love being able to use a yubikey, and age-plugin-yubikey makes this very easy.

ripgrep

This is grep on steroids. Stop using grep and start using ripgrep and you'll never go back. It is significantly faster, and has a bunch of great features (e.g., searching file types, regex, automatic filtering, etc.). It is often thought of as the gold standard for excellent Rust code.

Satty

When it comes to taking screenshots, Satty is my favorite on Linux. (I still use Flameshot on macOS.) Easy to adjust, annotate (i.e., arrows, boxes, text, blur, etc.), and save to clipboard or file. Integrates well in Omarchy.

sd

sd is an intuitive rust rewrite of sed. Much like the other tools in this list (e.g., bat, exa, etc.) it is just a better option in most cases. I frequently use it in combination with fd to find and replace across a project directory.

sshx &

sshx is the best live terminal sharing application I've ever used. I used to reach for things like tmate for this, but it's more constraining (e.g., I want to still use zellij). It also does not look as nice. sshx has a level of polish no other tool I've tried in this space has had. This is by go-to tool for pair programming. They also just released the killer feature of read-only sharing, which makes this extremely handy in a whole slew of scenarios. This largely solved the screen sharing problem you might have if you use Slack or similar, but have an ultrawide monitor and your coworkers do not. With sshx, the latency is impressively low and the text will be crystal clear. In a screen share, you have a compressed mess.

Starlight

Starlight is my new go-to documentation framework. It does all of the important things I used from Material for MkDocs, but often in more intuitive, ergonomic ways. It is blazingly fast. It looks good. I don't have to deal with ridiculous Python virtual environments.

While we're talking about documentation, I'll mention that I'm a strong proponent of the Diátaxis documentation system. If you're wondering how you should organize your documentation, please consider it!

starship

I started using starship about the same time I started using fish. It's a fun, fast, extremely customizable prompt with nice defaults. I've enjoyed it enough that I just haven't stopped using it since first adding it to try. If you're the type that has some line in your .bashrc to know what git branch your on, you might enjoy starship as well.

Tailscale

Thanks to wireguard, tailscale makes private mesh networking stupid easy. It's my go-to tool when it comes to sharing things on a private network (e.g., self-hosted stuff with my family, ssh-ing into my desktop when out and about, etc.). It's performant, well documented, and pretty much just works and gets out of your way.

tokei

tokei is the best way to get statistics around counting code in a repository. It shows you the total number of files and total lines within those files broken down by code, comments, blanks, and organized by language.

It seems both faster and more accurate than tools like cloc, sloccount, etc. There are other great blogs posts about code counters.

typos

typos is a very handy spellchecker that seems to work in a code context better than other things I've tried. They have a CLI, as well as an LSP. It's worth checking out!

I usually have a config like this:

[files]
extend-exclude = ["*.svg"]

[default]
extend-ignore-re = ["\\w{51,}"]

Typst

Almost anytime I would've reached for LaTeX, I now reach for typst. The ecosystem has seriously grown over the years. The performance, control, and error messages remain excellent.

And, it looks just as good as LaTeX.

The only thing still on my wishlist is variable font support.

watchexec

watchexec simply runs a command when files in the current directory change (and it's awesome). Made my the same folks who make cargo watch, this is a general purpose tool that can make your development loop feel faster when immediately starting long processes (linting, tests, etc.) immediately in response to code changes. Oftentimes, the checks/build/tests are finished by the time I'm ready to craft my commit. Definitely worth trying.

xh

xh is very similar to HTTPie. While I haven't used the latter, I'm a big fan of xh over curl. The interface just seems more intuitive and friendly. And, it still has a --curl flag so I can get a curl command in case I need to share it with a teammate.

YNAB

I used to use Mint, but when they shut down, I migrated to YNAB. I wanted to be more hands on, more intentional, and more aware of my spending, and YNAB seems to be a great tool for that job.

zellij

I spend the vast majority of my time every day inside a zellij session. I'm a fairly basic user, but the terminal multiplexing, scrollback buffer/search, ability to have multiple sessions and attach/detach is all I really need. zellij and mosh are a perfect combo. I like the visuals and UX enough to have had this replace tmux.

Zola

For non-documentation sites, my favorite static site generator is Zola. The template engine is great, and its fairly simple and easy to grok how themes work and can be modified. I use it for this site, as well as several others I've made.

Final thoughts

Omarchy and the cascade of software that that showed me was the big change this year, with a couple of other fun highlights like Ghostty, jj, and age.

Otherwise, the trusty toolbox has largely remained trusty!

Switching from GPG to age

2025-11-04T00:00:00+00:00

It's been several years since I went through all the trouble of setting up my own GPG keys and securing them in YubiKeys following drduh's guide. With that approach, you generate one key securely offline and store it on multiple YubiKeys, along with a backup.

It has worked well for me for years, and as the Lindy effect suggests, it would almost certainly continue to.

But as my sub-keys were nearing expiration, I was faced with either renewing (more convenient, no forward secrecy) or rotating them (rather painful, but potentially more secure). However, I've realized that I essentially only use these keys for encryption, and almost never for signing. So, instead of doing either of the usual options, I'm going to let my keys expire entirely.

I'm now experimenting with age, which touts itself as "simple, modern, and secure encryption". If needed, I will use minisign for signatures.

Workflow changes

This required changing a couple of things in my typical workflow.

Password manager

First, and foremost, I needed to switch from pass to passage, a fork of pass that uses age as the backend. This was actually surprisingly easy because passage includes a simple bash script to do the migration.

#! /usr/bin/env bash
set -eou pipefail
cd "${PASSWORD_STORE_DIR:-$HOME/.password-store}"
while read -r -d "" passfile; do
  name="${passfile#./}"; name="${name%.gpg}"
  [[ -f "${PASSAGE_DIR:-$HOME/.passage/store}/$name.age" ]] && continue
  pass "$name" | passage insert -m "$name" || { passage rm "$name"; break; }
done < <(find . -path '*/.git' -prune -o -iname '*.gpg' -print0)

There is no installer for passage, and no Arch packages. But it's easy enough to install because it's just a shell script you can throw on your $PATH. Note that for Arch, I also needed to install tree, which it assumes you have.

I also name passage as pass on my machine.

The benefit of this is everything that had pass integration has continued to "just work". For example, aerc, my email client of choice, behaved exactly the same after the migration.

No more `gpg-agent`

I would occasionally use gpg-agent as my SSH agent on my machines. It was convenient. However, I also like the idea of having a dedicated SSH key per machine. It makes monitoring their usage and revoking them much finer-grained.

The absence of gpg-agent forced me to set up new keys on all my machines and add them to various servers/services.

Benefits of the `age` approach

Easy encryption with chezmoi

While I was tending to the encryption area of my personal tech "garden", I also started leveraging chezmoi's encryption features. I already use chezmoi for my configuration files, but with encryption, I could also easily add "secrets" to my public dotfiles repo. In my case so far, this just means my copies of my favorite paid font: Berkeley Mono.

chezmoi also has a nice guide for configuring chezmoi to encrypt while asking for a passphrase only once for age.

Easy YubiKey configuration

I was also very pleasantly surprised with how easy it was to switch to age! Last time I set up the GPG keys on my YubiKeys, I spent several hours.

This time, with the help of age-plugin-yubikey and embracing the idea of having unique keys on each YubiKey, but encrypting everything for multiple recipients, setting up my keys was surprisingly trivial. It also generates the keys securely on the hardware key itself, which is nice. The whole process probably took 30 minutes. It was so easy that in the future, I'm very much not intimidated by the thought of rotating keys.

Thoughts

Did I need to switch to age? Of course not.

However, over my career, I repeatedly find that exploring new tools for your core workflows (part of investing in interfaces) is just plain fun. I often learn new ways of thinking about problems. Sometimes, you walk away with a new default that brings some fresh ideas and some delight to your life. Other times, you walk away with your trusty old tool, with greater appreciation for its history and the hard-earned approach it has established. For my uses at the moment, age definitely falls into the former camp.

This post made it to Hacker News. See the thread for some additional discussion.

First impressions of jj from a git fan

2025-10-25T00:00:00+00:00

What is `jj`?

Jujutsu (jj) is a distributed version control system (like git, hg, darcs, pijul, etc.). However, it is rather unique in that it is git-compatible—it uses git as a storage layer, meaning you can use it right now on your existing git repos without disrupting anyone else.

It also provides other features, such as

conflicts as a first-class object
no explicit index
revset language
operation log and powerful undo
automatic rebase and conflict resolution

It also clearly has a (currently small but) passionate group of users, which is a good sign of a useful tool.

Some of these users strongly dislike git, finding its user interface unintuitive and clunky. I, however, am very much not part of that group. I love git. Over the years, I've curated a configuration that I find a joy to use. I've built up years' worth of muscle memory. As a result, even though I love investing in interfaces, such as new software tools, I haven't ever felt motivated enough to try jj. That changed this past week when I learned that Steve Klabnik found jj so interesting that he's leaving Oxide to pursue it further.

As an experiment, I've committed to using only jj for at least a couple of weeks.

As a git user, the tutorial that clicked best for me is Steve's. So, if you're a git fan, I suggest starting there.

First impressions

What I miss from `git`

I quickly ran into two features that I wish were supported.

First, jj does not support submodules. Sure, submodules are not great in many cases. However, one very common case I use them for is Zola themes, such as the theme for this blog. My customization lives in my repository, and the theme for the site lives in a git submodule. However, it looks like they are working on that actively and with great care.

Second, I missed git-format-patch. This one is more minor, because I can always just fall back to git to do so. Even in just a few days, I've wanted to serialize a patch to a file (i.e., git format-patch) or apply some patch I have sitting around with git am. One example is a patch file I keep around that customizes an environment for debugging purposes. As a jj-native approach, I've been keeping a change separate that I can rebase into my patch series and move out later if needed.

Then, there are a handful of more rarely used things that I have not needed yet, and consequently have not figured out equivalents for. For example, I'm not sure about an equivalent for view release notes via tags. With git, I used an alias like

[alias]
    tlog = tag --sort=-v:refname -l --format='%(color:red)%(refname:strip=2)%(color:reset) - %(color:yellow)%(contents:subject)%(color:reset) by %(taggername) on %(taggerdate:human)\n\n%(contents:body)'

But, then it seems right now jj only supports lightweight tags, not annotated git tags.

I'm not sure an equivalent for git shortlog. Most likely would need to build some template.

I don't have some jj equivalent of git-stats. But again, it's git-compatible, so I can just keep using git-stats.

I'm sure there will be a long tail of things like this.

Things I like more about `jj`

Steve and others have described jj as "both simpler and easier than git, but at the same time, it is more powerful." I'm not sure I fully agree. In some ways, it has better defaults (e.g., jj split, jj absorb), but in other ways, it is complex (e.g., revset language). That said, I do see how it is more powerful.

You cannot exactly your git mental model to directly onto jj's. That said, one of the main things I enjoy at $WORK is that for a repository, git's default "view" (for lack of a better word) is a branch, whereas jj's default view is much higher level. I find jj's approach more intuitive: it's always pretty trivial to see what branches/PRs I have ongoing at a glance (i.e., with jj log -r "@ | ancestors(trunk()..(visible_heads() & mine()), 2) | trunk()"). It also means you can easily do fun stuff like rebase all of your branches at the same time, and push them all simultaneously to your remote! This is made even better by the fact that conflicts are first-class objects, meaning you can rebase all your branches, and deal with conflicts later.

In a similar vein: jj emphasizes commits or changes in a way I find pleasing. Even though in git I have ways to do similar things, jj does indeed make them easier. For example, splitting one commit into multiple is easier. In git, you'd probably do something like

git rebase -i
# select the commit you want to split for editing
git reset HEAD~1 --mixed
# add the subset of changes you want in the first commit
git commit -c ORIG_HEAD
# tweak if necessary
git add -u
git commit
# write a commit message for the 2nd patch from scratch

In jj, jj split just does the more intuitive thing. Instead, the same process looks more like

jj split -r {REVISION}
# select the subset of changes you want in the first commit
# automatically presented with the original commit message, tweak if necessary
# remaining changes automatically put in 2nd commit, presented with original commit message to tweak again

As another example, I'm a huge fan of git-absorb. It makes folding follow-up changes into an appropriate earlier commit easy and effective.

However, it isn't built into git. Meanwhile, jj ships with jj absorb, which does the same thing.

I found that in git, I was already following a workflow close to the squash workflow recommended by jj's creator, Martin.

Things I still find awkward

The main thing I still feel clumsy with is named bookmarks (similar to git branches). Specifically, I find it hard to remember to set the bookmark when I make updates, and how to rebase them without looking up commands. That said, it's becoming more familiar over time.

My configs

Much like git, I've also found that jj's defaults aren't entirely sufficient for me. I needed to make some tweaks. You can see my up-to-date dotfiles here, but as a snapshot, these are changes I found to be particularly valuable right from the start.

#:schema https://jj-vcs.github.io/jj/latest/config-schema.json

[user]
name = "Luke Hsiao"
email = "{{ .email }}"

[git]
auto-local-bookmark = true
# Prevent pushing work in progress or anything explicitly labeled "private"
private-commits = "description(glob:'wip:*') | description(glob:'private:*')"

[ui]
editor = "hx"
pager=["delta", "--pager", "less -FRX"] # Keeps output from the terminal after closing the pager
diff-formatter = ":git" # required by `delta`

# These options allow for `jj diff` and `jj show` to clear the output from the terminal after closing the pager.
[[--scope]]
--when.commands = ["diff", "show"]

[--scope.ui]
pager = "delta"

[template-aliases]
commit_template = '''"JJ: <type>(<scope>): (If applied, this commit will...) <subject> (Max 50 char)
JJ: |<---- Try to limit to a max of 50 char ---->|

JJ: Explain why this change is being made
JJ: |<----- Try to limit each line to a maximum of 72 characters ----->|

JJ: Provide links or keys to any relevant tickets, articles or other resources
JJ: Example: GitHub issue #23, BREAKING CHANGE: <description>, Ref: 5119ae

JJ: --- COMMIT END ---
JJ: Type can be
JJ:   build:    changes that affect the build system or external dependencies
JJ:   chore:    updating grunt tasks; no production code change
JJ:   ci:       changes to our ci configuration files and scripts
JJ:   docs:     changes to documentation
JJ:   feat:     new feature, correlates with MINOR
JJ:   fix:      bug fix, correlates with PATCH
JJ:   perf:     a code change that improves performance
JJ:   refactor: refactoring production code; neither fixes a bug nor adds a feature
JJ:   revert:   for reverts, revert: <old subject>; state reverted hash in body
JJ:   style:    formatting, missing semicolons, etc; no change in code behavior
JJ:   test:     adding or refactoring tests; no production code change
JJ:
JJ: Scope refers to the file, directory, or system that is being modified.
JJ:
JJ: Follow the type(scope) with an '!' to indicate a breaking change.
JJ: Example: refactor(api)!: remove the accident-prone delete_all button
JJ: --------------------
JJ: Remember to
JJ:    Use the imperative mood in the subject line
JJ:    Do not end the subject line with a period
JJ:    Separate subject from body with a blank line
JJ:    Use the body to explain what and why vs. how
JJ:    Can use multiple lines with '-' for bullet points in body
JJ:    BREAKING CHANGE: to correlate with MAJOR
JJ:
JJ: See: https://www.conventionalcommits.org/en/v1.0.0/)"
'''

[templates]
git_push_bookmark = '"lwh/" ++ change_id.short()'
draft_commit_description ='''
    concat(
      coalesce(description, commit_template, "\n"),
      surround(
        "\nJJ: This commit contains the following changes:\n", "",
        indent("JJ:     ", diff.stat(72)),
      ),
      "\nJJ: ignore-rest\n",
      diff.git(),
    )
'''

[aliases]
cl = ["log", "-r", "trunk()..@-", "--reversed", "-T", "description ++ '\n---\n\n'", "--no-graph", "--no-pager"]
l = ["log", "-r", "@ | ancestors(trunk()..(visible_heads() & mine()), 2) | trunk()"]
la = ["log", "-r", "all()"]
pba = ["git", "push", "-b", "glob:lwh/*"]
rba = ["rebase", "-s", "all:roots(mutable())", "-d", "trunk()"]
tug = ["bookmark", "move", "--from", "heads(::@- & bookmarks())", "--to", "@-"]

First, I strongly prefer delta over the default viewer. jj also makes it easy to view with another tool with --tool. For example, I also like using difft.

I added a config from this discussion so jj log doesn't clear the screen on quit.

Second, I like having my conventional commit template automatically populated on jj describe. I also have the diff included, which mimics the config I had with git using

[commit]
    template = ~/.config/git/commit-template
    verbose = true

Third, I changed the default git push bookmark prefix to lwh/.

Finally, I added a bunch of aliases I use frequently. I use jj cl to copy-paste commit descriptions into PR descriptions. I use jj l to view all the logs most relevant to me. This was discovered courtesy of Will Richardson. I use jj la to view all logs. I use jj pba and jj rba to push all my bookmarks, and rebase all my changes on main, respectively. Finally, I use jj tug to move my bookmark to the latest change (I found this one thanks to Shaddy).

Thoughts so far

I actually find jj quite fun! Again, I do not think it "solved" any pain points I had with git. I was already a very happy user. Ultimately, jj's interface and mental model do feel refreshing enough that I'm likely to continue using it.

ASUS PA32QCV: a programmer's review

2025-10-15T00:00:00+00:00

Those who know me know that I invest in interfaces. Previously, I had an LG 38GN950-B (38" Ultrawide, 3840×1600 @ 144Hz). It was expensive, but had a little extra vertical resolution vs its competitors, and the high refresh rate was great for casual gaming. But, over the years, I play games less, and my eyes are aging! I find myself appreciating larger and more crisp fonts for programming.

With that in mind, I started looking for a high resolution "retina"-class display. There are only a handful of these around at the time of writing. In the 27" 5K group: Apple Studio Display/ProArt PA27JCV/Samsung S9/Kuycon G27P. Then, there is the 32" 6K group: Apple XDR/ProArt PA32QCV/Kuycon G32P/Dell U3225KB/LG 32U990A-S. Then, there is the even more sparse 8K group: Dell UP3218K/ProArt PA32KCX.

I know I wanted to avoid fractional scaling, so I was searching for either 6K or 8K.

I immediately discovered that 8K is way out of my price range.

In the land of 6K, this ProArt PA32QCV met a sweet spot: (1) being available for purchase right now, (2) having relatively modern hardware, and (3) not being ridiculously expensive. So, I bought it.

First impressions

WOW.

I'm a big fan. As soon as I switched, I understood why people like these high-resolution displays. Text is crisp and delightful to look at! I do not miss the ultrawide at all.

I run at 2× scaling, and have been loving looking at it.

Yes, I do notice the drop from 144Hz to 60Hz. However, because I'm mostly programming, I really don't notice it during a typical workday unless I go looking for it (e.g., dragging a window quickly).

The colors look great.

In other words, when it comes to the display itself, it seems fantastic, which is what I was looking for.

Some people complain about the matte "LuxPixel" finish. I think it looks fantastic, and appreciate the lack of glare. This is an important feature, in my opinion.

The less good

When it comes to some of the other features, they are notably less useful.

Speakers

These are fairly awful, as one would expect. What confuses me is why these are here at all. This is a "pro" monitor, and I see no value in having speakers. I wish they saved some cost or reduced size/weight instead.

KVM

I frequently multiplex between a work laptop and a personal desktop. So, a built-in KVM is actually very appealing! However, I've never found one that works well for my needs, so I've always reverted to separate display cables and a USB switch. The same is true here.

Yes, this monitor has a KVM, but it does not have enough USB ports for my needs. It has 3 USB ports, and 1 thunderbolt port. The good news is that this lets me use 4 USB devices just fine on MacOS. The bad news is that the 1 thunderbolt port does NOT work on my desktop, leaving me with just 3 devices. Typically, I want four: a mouse, keyboard, webcam, and audio interface. Five, if you count a security key. So, good idea and will work for just a keyboard an mouse, but not enough for me.

Another fatal flaw is that the KVM doesn't appear to activate immediately upon switching input. This is vital because if your other machine goes to sleep, the input button will not switch until there is a display signal on that input—a signal that you have no way to initiate without a keyboard or mouse active! With a USB switch, that means I typically switch, wake up the machine, and then switch the input. With the built-in KVM, that means there is simply no way to actually switch without waking up the machine first some other way. Not cool.

That said, my normal USB switch setup works well.

Light sync

The "Light Sync" feature actually sounded great: I work right by a window, and frequently do adjust brightness to compensate for the ambient light. It would be awesome if it could do it for me!

However, after using it, as far as I can tell there is no way to set the baseline/target brightness you want. Instead, it ranges from acceptable (in Native color preset) to unusably dim (in M Model-P3). It is a good idea, but the implementation seems to only be viable in Native mode of the ones I tried, which means this forces you to make a color preset trade-off. Instead, they should've just let me set the target brightness.

That said, as someone not using this monitor for color accuracy, specifically, I've been quite satisfied with Native mode's behavior thus far.

The surprising

Some features/design choices I was pleasantly surprised at. Not surprised they existed, but surprised how much I liked them.

I really like buttons being on the front of the monitor, rather than needing to blindly click around on a side or bottom.
No giant power supply! I appreciate the saved desk space of having the power supply built-in.

Compatibility

The box came with the display itself, a stand, a Thunderbolt 4 cable, an "ultra 8K" HDMI cable, and a power cable.

After reading Michael Stapelberg's review of the 6K Dell, I was a little worried about compatibility. I was optimistic that with a brand-new release, more compatibility issues would've been ironed out.

I have two machines I use with this display: an M1 MacBook Pro, and my custom workstation (Radeon RX 7800 XT), running both Windows and Linux.

The monitor was clearly built with a MacBook in mind. Using the Thunderbolt 4 cable, I instantly got power and display—full 6K no problems. Colors do indeed seem highly matched with the M Model-P3 color preset.

On my desktop with Windows via the included HDMI cable there was no problem. It instantly recognized full 6K@60Hz.

My desktop with Linux via the included HDMI cable? No 6K at all.

❯ hyprctl monitors
Monitor HDMI-A-2 (ID 0):
        3008x1692@59.96700 at 0x0
        description: ASUSTek COMPUTER INC PA32QCV T7LMSV006894
        make: ASUSTek COMPUTER INC
        model: PA32QCV
        physical size (mm): 700x390
        serial: T7LMSV006894
        active workspace: 1 (1)
        special workspace: 0 ()
        reserved: 0 26 0 0
        scale: 1.00
        transform: 0
        focused: yes
        dpmsStatus: 1
        vrr: false
        solitary: 0
        solitaryBlockedBy: windowed mode,missing candidate
        activelyTearing: false
        tearingBlockedBy: next frame is not torn,user settings,missing candidate
        directScanoutTo: 0
        directScanoutBlockedBy: user settings,missing candidate
        disabled: false
        currentFormat: XRGB8888
        mirrorOf: none
        availableModes:
            3008x1692@59.97Hz
            4096x2160@60.00Hz
            4096x2160@59.94Hz
            4096x2160@50.00Hz
            4096x2160@30.00Hz
            4096x2160@29.97Hz
            4096x2160@25.00Hz
            4096x2160@24.00Hz
            4096x2160@23.98Hz
            3840x2160@60.00Hz
            3840x2160@59.94Hz
            3840x2160@60.00Hz
            ...

I first went down a bit of a rabbit hole assuming it was a Linux software issue (the same hardware works with Windows!). But, I'm running Arch, with a very recent kernel and all up-to-date drivers. I decided to try a DisplayPort cable instead.

❯ hyprctl monitors
Monitor DP-1 (ID 0):
        6016x3384@59.99200 at 0x0
        description: ASUSTek COMPUTER INC PA32QCV T7LMSV006894
        make: ASUSTek COMPUTER INC
        model: PA32QCV
        physical size (mm): 700x390
        serial: T7LMSV006894
        active workspace: 1 (1)
        special workspace: 0 ()
        reserved: 0 26 0 0
        scale: 2.00
        transform: 0
        focused: yes
        dpmsStatus: 1
        vrr: false
        solitary: 0
        solitaryBlockedBy: windowed mode,missing candidate
        activelyTearing: false
        tearingBlockedBy: next frame is not torn,user settings,missing candidate
        directScanoutTo: 0
        directScanoutBlockedBy: user settings,missing candidate
        disabled: false
        currentFormat: XRGB8888
        mirrorOf: none
        availableModes:
            6016x3384@59.99Hz
            3008x1692@59.97Hz
            6016x3384@29.99Hz
            4096x2160@60.00Hz
            4096x2160@59.94Hz
            4096x2160@50.00Hz
            4096x2160@30.00Hz
            ...

Whew! Instantly recognized the 6K@60Hz.

So, that's the tip: use DisplayPort on Linux.

Verdict

So far, after a bit more than 3 months of daily use, I'm very pleased.

One of the biggest evidences of how nice it is was when I went back to my old monitor for a little bit. The lack of text clarity was just as apparent as my initial shock at the clarity going the other direction.

We'll see how it fares long term, but this is absolutely a keeper right now.

AI etiquette

2025-10-05T00:00:00+00:00

It's the thought that counts

I recently read a great blog post from Alex Martsinovich. It expressed a concept that I've been feeling, too: proof-of-thought.

For the longest time, writing was more expensive than reading. If you encountered a body of written text, you could be sure that at the very least, a human spent some time writing it down. The text used to have an innate proof-of-thought, a basic token of humanity.

Now, AI has made text very, very, very cheap. Not only text, in fact. Code, images, video. All kinds of media. We can't rely on proof-of-thought anymore. Any text can be AI slop. If you read it, you're injured in this war. You engaged and replied – you're as good as dead. The dead internet is not just dead it's poisoned. So what do we do?

Luckily for us, AI only talks in response. Unlike Earth, AI does not emit comedy sketches into outer space on its own. To get AI slop, somebody needs to ask for it. To send it further, someone needs to retransmit it. Our problem is other humans, really.

There's nothing wrong with using AI. When you do, you know what you're getting. The transaction is fully consensual. But whenever you propagate AI output, you're at risk of intentionally or unintentionally legitimizing it with your good name, providing it with a fake proof-of-thought. In some cases, it's fine, because you did think it through and adopted the AI output as your own. But in other cases, it is not, and our scrambler brain feels violated.

He goes on to propose a simple new sense of etiquette: AI output can only be relayed if it's either adopted as your own or there is explicit consent from the receiving party, otherwise, it is horribly rude. I'd add that essentially, you either are providing proof-of-thought, or, you're explicitly acknowledging the lack of it.

This resonates.

Relatable example in the wild

It reminds me of Neven Mrgan's reflection on how it feels to get an AI email from a friend.

Recently I received an AI-written email from a friend. It wasn't sent to test AI, or to show it off, as in "ha ha check this out"; my friend had a question to ask me, and the email asked it over the course of a few paragraphs. It then disclosed that, oh by the way, I used AI to write this. My reaction to this surprised me: I was repelled, as if digital anthrax had poured out of the app. I'm trying to figure out why.

He then really breaks down how it did and didn't feel as a recipient. For example, it didn't feel like they were using it as an autocorrect to type better. It did feel like a family fridge decorated with printed stock art of children's drawings.

Years from now, could an AI that was trained on all of my friend’s emails and texts and personal documents sound convincingly like them? Could it be so advanced that I wouldn’t even be able to tell that my friend hadn’t written to me at all? Possibly. And that idea saddens me the most.

Another is the bleakly entertaining rant by Bryan Cantrill: Your intellectual fly is open.

When you use an LLM to author a post, you may think you are generating plausible writing, but you aren't: to anyone who has seen even a modicum of LLM-generated content (a rapidly expanding demographic!), the LLM tells are impossible to ignore. Bluntly, your intellectual fly is open: lots of people notice — but no one is pointing it out. And the problem isn't merely embarrassment: when you — person whose perspective I want to hear! — are obviously using an LLM to write posts for you, I don't know what's real and what is in fact generated fanfic. You definitely don't sound like you, so...is the actual content real? I mean, maybe? But also maybe not. Regardless, I stop reading — and so do lots of others.

My pledge

The words on this blog have been and will always be, manually and intentionally typed by me (on a keyboard that I find delightful). Yes, I am a big em dash (and en dash!) user—I even have macros in my editor to make the substitutions. No, that's not AI. Yes, you'll find typos and grammar errors in my posts; I'm human (but if you do, please send me a note so I can fix it). Still, I find writing a good way to clarify my own thoughts and, while I primarily write for myself, occasionally someone else benefits, too.

While we have no formal way to provide proof-of-thought, my pledge to both you and myself is that this place will remain a place for human thought, and more specifically, my personal ramblings.

Repairing my Windows bootloader after Omarchy

2025-09-09T00:00:00+00:00

The problem

Before I switched to Omarchy, I was running omakase-blue on one NVME drive, and Windows on another. Part of this is because I want to use full disk encryption, and part of this is because I was originally playing with Project Bluefin, which doesn't support dual-boot off of a single disk.

I installed Omarchy via online ISO, and pointed it at my Linux drive.

After it installed, I no longer could boot into Windows. My BIOS didn't even show the 2nd NVME drive as a boot option.

The solution

After some digging, I figured out a way to get things back without needing to reinstall any operating systems. My system looked like this after the Omarchy install:

❯ lsblk --output NAME,PTTYPE,PARTLABEL,FSTYPE,FSVER,LABEL,FSSIZE,FSAVAIL,FSUSE%,MOUNTPOINTS
NAME        PTTYPE PARTLABEL                    FSTYPE      FSVER LABEL FSSIZE FSAVAIL FSUSE% MOUNTPOINTS
zram0                                           swap        1     zram0                       [SWAP]
nvme0n1     gpt
├─nvme0n1p1 gpt                                 vfat        FAT32           2G    1.8G     9% /boot
└─nvme0n1p2 gpt                                 crypto_LUKS 2
  └─root                                        btrfs                     1.8T    1.8T     2% /var/log
                                                                                              /home
                                                                                              /var/cache/pacman/pkg
                                                                                              /
nvme1n1     gpt
├─nvme1n1p1 gpt    Microsoft reserved partition
├─nvme1n1p2 gpt    Basic data partition         ntfs
└─nvme1n1p3 gpt                                 ntfs

That is, the vfat, FAT32 partition with the bootloader was on nvme0n1, and it didn't seem there was any corresponding partition on nvme1n1.

The good news is that this indicated that I could probably just restore the required boot files to nvme0n1p1 for Windows and be on my way.

Repairing the Windows bootloader files

To do so, I used Hiren's BootCD PE on a USB drive with Ventoy.

Once in the Windows PE environment, we can restore the files with diskpart and bcdboot in the command prompt.

diskpart

> list volumes

# find the fat32 one, let's call it X
> select volume X
> assign letter K:

Now that we've assigned a letter, we can fix the files:

  bcdboot C:\Windows /s K: /f ALL

where /s specifies the volume letter of the system partition, and /f specifies the firmware type (ALL copies all of them).

At this point, I could once again boot from this drive and land in Windows.

Adding Windows to Limine

But, we could do even better! Having to use the BIOS boot menu is annoying: you typically have to spam an F-key at startup, and if you miss your opportunity, need to restart again. It would be nice to be able to just boot to the same bootloader and select Windows, like in a traditional single-drive, dual-boot setup.

Turns out that isn't hard, since Omarchy uses Limine out of the box.

In Linux, we can just edit the boot config.

sudoedit /boot/limine.conf

Then, I added the following entry after the Omarchy ones, and before the EFI fallback.

/Windows
comment: Windows
comment: order-priority=40
    protocol: efi
    path: boot():/EFI/Microsoft/Boot/bootmgfw.efi

With this, I then configured my BIOS to with Limine as the first boot option, and disabled the others. Now, it boots to Limine on startup, and my Windows drive is once again an easy option to select. Nice.

Berkeley Mono Variable (TX-02) in Ghostty

2025-09-07T00:00:00+00:00

Inspired by Michael Bommarito's post, I'm just dropping some quick notes on getting Berkeley Mono Variable (TX-02) to work in Ghostty. Specifically, Berkeley Mono 2.002, released on 2024-12-31, running in Ghostty 1.1.3-arch1. Using the variable version of the font is highly convenient: it is very fast to change styles and tweak things until it is exactly how you like it, without having to iterate with installing static fonts.

I suggest you read his post first for lots of nice context on fonts and their features.

Then, the key bit of information I needed to get this working was the following. TX-02, the updated version of Berkeley Mono, has different OpenType features than the original. There is no documentation I could find on exactly what they mean, but via some trial and error, I've landed on the following config.

font-family = "Berkeley Mono Variable"

# Font width (60 to 100)
#  60 = UltraCondensed
#  70 = ExtraCondensed
#  80 = Condensed
#  90 = SemiCondensed
# 100 = Normal
font-variation = wdth=90

# Font weight (100 to 900)
# 100 = Thin
# 200 = ExtraLight
# 300 = Light
# 350 = SemiLight
# 400 = Regular
# 500 = Medium
# 600 = SemiBold
# 700 = Bold
# 800 = ExtraBold
# 900 = Black
font-variation = wght=400

# Font slant (0 to -16)
#   0 = Regular
# -16 = Oblique
font-variation = slnt=0

# otfinfo -f ~/.local/share/fonts/Berkeley\ Mono\ Variable.otf
# aalt    Access All Alternates
# calt    Contextual Alternates
# ccmp    Glyph Composition/Decomposition
# mark    Mark Positioning
# mkmk    Mark to Mark Positioning
# salt    Stylistic Alternates
# ss01    Stylistic Set 1 <- slashed 0
# ss02    Stylistic Set 2 <- dotted 0
# ss03    Stylistic Set 3 <- gap 0
# ss04    Stylistic Set 4 <- slashed 0, slash 7
# ss05    Stylistic Set 5 <- dotted 0, slash 7
# ss06    Stylistic Set 6 <- gap 0, slash 7
font-feature = +calt
font-feature = +ss02

font-size = 13
# Personal preference
adjust-cell-height = -2%

Specifically, I found that aalt and salt appear to change what the stylistic sets do (to different things than my comments). ccmp, mark, and mkmk don't do anything that I noticed. So, effectively, it seems to me that the only two features you actually care about are your font-variation settings, and then whether you want ligatures with calt, and what style of 0/7 you want via stylistic sets.

Another tip: if you have static versions of Berkeley Mono installed, I noticed that that sometimes breaks Ghostty from loading Berkeley Mono Variable. I'm unsure why, but I was able to resolve it by removing the static fonts, configuring things, and then putting them back.

The youngest sibling advantage

2025-08-31T00:00:00+00:00

I am the youngest child in my family.

I've heard a lot of discussion around the stereotypical traits of the youngest child. In fact, many of these are so commonly echoed that they have their own name: youngest child syndrome. Sure, some of these arguably apply to me (certainly my older siblings would label me spoiled), and others do not. But, what I haven't heard in many of these discussions is what I consider to be the biggest single advantage: life scouts. No, not like Boys Scouts of America "Life" scouts, like people scouting ahead for you in life.

The youngest child often has older siblings they have observed keenly, maintained a strong and open rapport with, and with whom they have shared significant life experiences. They know them at a profound level.

They then get to observe these older siblings blaze a variety of trails through life, years ahead of them. The youngest get to observe the decisions the older siblings make, often well aware of context, and then see the consequences of those decisions play out. Sometimes those consequences are positive, and sometimes they are not. Sometimes the outcome seems causal, and sometimes it seems that luck played a large role. Sometimes that whole decision-consequence cycle can happen well before a younger sibling might be faced with a similar decision.

In many ways, this is like mentorship on an amplified level. Not mentorship in terms of career or school advice, but mentorship in life—hard earned advice and examples in real time, with real stakes, resulting in real impact.

The advantage of having life scouts naturally follows. The youngest now has deeply detailed experience of highly trusted people to draw from when navigating the world ahead of them. As a kid, you already know the best parks or playgrounds nearby. You also know what areas of the neighborhood are dangerous. As a student, you're confident in navigating the school system, and the trade-offs of different schedule choices. As an adult, you have gleaned some insight on dating and partner choices, and how those can affect directions in life. You have observed different fields of study or career choices, and how those areas affect stress, income, flexibility, and more. You have witnessed glimpses of different parenting styles and parenting choices. The examples are endless.

Sure, not everything directly transfers, but I've found these "life scouts" to be priceless in my life. A shout-out to all the older siblings out there who pave paths and building organizational knowledge for those of us who come afterward. We appreciate you!

As for me, I think benefiting from such mentorship (from siblings) is also why I value mentorship in general so highly. As the youngest sibling, I might not be able to provide powerful mentorship this particular way, but I still can hopefully pay it forward to nieces and nephews and other youth in my community.

Comparing UTOPIA ISPs

2025-08-03T00:00:00+00:00

I currently use UTOPIA for my fiber connection. Their model is that they charge for the infrastructure, and then they have many ISPs on top that provide competing internet services.

Pricing

As a snapshot comparison (primarily for my own notes), here's a comparison of pricing for residential service, on the tier of 1Gbps download and upload (symmetric). This is the tier I'm currently on.

ISP	Price ($)	Notes
Centra	`43.95`	Appear more honest on their Broadband label (showing 841Mbps/884Mbps down/up, rather than 1000Mbps).
ETS	`45.00`	Up to 10Gbps.
Fusion Networks	`45.00`	1Gb is their fastest plan.
3wave	`48.00`
SenaWave	`48.00`	Very sparse on details.
Voonami	`48.95`	Comes with a free static IP on request. Also offers colo services. 2.5 Gbps fastest.
SumoFiber	`49.95`	Appear slightly more honest, stating 980 Mbps up/down.
IntelliPop	`49.95`
ConnectFast	`53.95`	Only a single plan: 1Gb
FiberNet	`53.95`	1Gb is their fastest plan, but they have infra (i.e., offers colo services).
XMission	`54.00`	Runs an extra firewall layer than can break some websites.
Miles Broadband	`54.00`
WiFiPros	`55.00`	I dislike the company name.
Advanced Stream	`55.00`	10 TB data cap, others are unlimited. Honest with specific speeds.
Brigham	`58.95`	Wordpress site, sloppy errors like discrepancies in pricing.
InfoWest	`80.00`	Unclear to me if this $80 includes UTOPIA's $30. Probably?
Beehive Broadband	N/A	Hard to find pricing is a dark pattern.
Rise Broadband	N/A	Couldn't find price.
Fastel	N/A	Sketchily sparse website and no pricing. Dark patterns.

At some point, I want to go through and learn more about their nuances. For example, XMission has an annoying trait of running their own firewall, which breaks websites occasionally. But, they also run their own datacenters and have some nice peering agreements that likely improve latency and performance.

Here's a UTOPIA-provided comparison sheet, too. There is some discrepancy in the pricing and the ISPs themselves, though.

Variable fonts and italics across browsers

2025-05-25T00:00:00+00:00

I'm a big fan of Atkinson Hyperlegible Next and Berkeley Mono (TX-02). It is my opinion that they both look great, unique, and provide valuable legibility features.

I recently refactored this site to use the variable, web versions of these fonts. I was happy that I now had only a single @font-face definition, not a handful, and went on my way. (I had haphazardly picked up these parameters on the Internet somewhere.)

@font-face {
    font-family: 'Berkeley Mono';
    src: url('../fonts/Berkeley Mono Variable.woff2') format('woff2');
    font-stretch: 60 100;
    font-weight: 100 900;
    font-style: oblique -16deg 0deg;
    font-feature-settings: calt;
    font-variant-ligatures: contextual;
}

@font-face {
    font-family: 'Atkinson Hyperlegible Next';
    src: url('../fonts/AtkinsonHyperlegibleNextVF-Variable.woff2') format('woff2');
    font-weight: 100 900;
    font-style: oblique -16deg 0deg;
}

Then, just recently, I realized that my italics were broken on this site for weeks! They worked on Chrome as I had it configured. They did not work on Firefox.

I tried a few things.

First, I tried duplicating the @font-face definition, but with font-style: italic. This made it work on Firefox, but broke Chrome.

I then found there is a new way to specify italics for variable web fonts, specifically (assuming it is supported by the font): font-variation-settings. In the case of Atkinson Hyperlegible Next, I could get my italics looking right on both Firefox and Chrome by adding the following CSS.

em {
  font-variation-settings: "ital" 1;
  font-synthesis: none;
}

But, this didn't work for Berkeley Mono.

I also tried things like using woff2-variations in my @font-face definitions and other little tweaks to no avail.

Finally, after more experimentation, I was pleasantly surprised that I could get everything working just by simplifying.

@font-face {
    font-family: 'Berkeley Mono';
    src: url('../fonts/Berkeley Mono Variable.woff2') format('woff2');
    font-stretch: 60 100;
    font-weight: 100 900;
    font-feature-settings: calt;
    font-variant-ligatures: contextual;
}

@font-face {
    font-family: 'Atkinson Hyperlegible Next';
    src: url('../fonts/AtkinsonHyperlegibleNextVF-Variable.woff2') format('woff2');
    font-weight: 100 900;
}

I dropped the (likely incorrect) font-style attribute. No need for the em class override, now, either.

With that, I have italics, both for my normal font, and for my monospace font that work on both Firefox and Chrome. All I needed to do was delete the right two lines.

Performance gains of undervolting a T480s

2025-05-23T00:00:00+00:00

I have been using a self-refurbished Thinkpad X230 for quite a while as a personal machine. I believe in the benefits of continuing to use old laptops [1, 2, 3]. However, recently, I've started to need to use a laptop to do presentations frequently, and the HDMI port on my X230 is not functioning fully, resulting in distorted colors and other distracting artifacts. I might try and repair that, someday.

However, due to pressing need, I instead picked up a used T480s from a good friend, which had a working HDMI port.

Over the first couple days of use, I noticed that this thing ran hot. Sure, I have the i7-8650u version, but the fans were spinning up far more than I'd like, and CPU temps would frequently exceed 95 °C for bursts at a time.

Naturally, I did a little digging.

It turns out, Linux and the T480s have a longstanding problem! I don't understand the problem well enough to explain it here. But, essentially, people were seeing throttling and temperature issues with these machines on Linux (but not Windows). To be clear, this issue was found on an old Linux kernel (4.15, I'm on 6.14). I do not know if this specific problem is affecting me. However, through this, I learned about a fun tool for undervolting a T480s: throttled.

Even if this issue was resolved in newer kernels, I imagined that some undervolting could still help my thermals and performance. So, I tried it. In addition, to give the attempt the best chance it had, I also replaced the thermal paste with fresh Duronaut.

I was surprised to find a 12% improvement in single-core performance and a 24% improvement in multi-core on Geekbench 6!

Metric	Original	Optimized	Change (%)
Single-core	`1341`	`1499`	`+11.8`
Multi-core	`3989`	`4948`	`+24.0`

The laptop runs much cooler, and the fans spin up much less. It's much more pleasant to use.

I ultimately landed on the following undervolt for this machine. (Remember, each chip is different, you might not be able to use these values.)

# All voltage values are expressed in mV and *MUST* be negative (i.e. undervolt)!
[UNDERVOLT]
# CPU core voltage offset (mV)
CORE: -135
# Integrated GPU voltage offset (mV)
GPU: -105
# CPU cache voltage offset (mV)
CACHE: -135
# System Agent voltage offset (mV)
UNCORE: -105
# Analog I/O voltage offset (mV)
ANALOGIO: 0

What a satisfying way to squeeze a little more performance out of a still-great laptop.

Steel man arguments, or arguing intelligently

2025-03-22T00:00:00+00:00

I'm a big fan of the idea of "steel man" argument. However, I've found that this term is far less widely known than its "straw man" counterpart. I've heard some people just call this "arguing intelligently".

Here are two good definitions if you're unfamiliar with the idea. First, Wikipedia's for the more abstract definition, and then Robin Sloan's practical example.

Wikipedia:

A steel man argument (or steelmanning) is the opposite of a straw man argument. Steelmanning is the practice of applying the rhetorical principle of charity through addressing the strongest form of the other person's argument, even if it is not the one they explicitly presented. Creating the strongest form of the opponent's argument may involve removing flawed assumptions that could be easily refuted or developing the strongest points which counter one's own position. Developing counters to steel man arguments may produce a stronger argument for one's own position.

Robin Sloan

There are two debaters, Alice and Bob. Alice takes the podium, makes her argument. Then Bob takes her place, but before he can present his counter-argument, he must summarize Alice's argument to her satisfaction — a demonstration of respect and good faith. Only when Alice agrees that Bob has got it right is he permitted to proceed with his own argument — and then, when he's finished, Alice must summarize it to his satisfaction.

The first time I saw one of these debates, it blew my mind.

Or, as Stephen R. Covey put it: "Seek first to understand, then to be understood".

Imagine if the default mode of debate was like this. A tool for persuasion, consideration, exploration, and achieving consensus (or at least clearly understanding the shape of disagreement). Instead, culturally, we're more used to debate as a stage for name-calling, politics, distraction, point-scoring, and drama.

Next time you're debating something, consider arguing more intelligently, and treating the other parties with that same human respect.

Sharing intro cards

2025-03-16T00:00:00+00:00

Those who know me know that I am fairly introverted. But, I am also someone who strongly values community, and thinks there are huge benefits to be had by building or connecting to one.

A big part of building or integrating into communities is getting to know the people in them. Some people have a natural talent for this. Others have built that skill through many years of deliberate practice. There are also some people that use software to manage and track these relationships "personal CRM"-style (e.g., Monica, or really detailed notes in Google Contacts).

I am currently none of these people.

But, I would like to build the skill.

One reason knowing people is valuable is because it helps facilitate connection. "Oh, I know X is in that industry, let me connect you." "The Y family has kids that line up with your kids age and go to Z Junior High, too." "Oh A used to live right around there, let's ask them for advice." These types of serendipitous connections can build strong bonds and strengthen a community, but you can only make them if you know enough.

To that end, I think "intro cards" are an interesting idea. Imagine that when you moved in somewhere, or went to a new group meeting, or church event, or met with the other parents for your kid's soccer team, that you could get a small physical card of pertinent information about these new people you met.

In big social settings like that, where you're meeting a lot of new people, it's very easy (for me, anyway) to have forgotten the names of the people I just talked to. Now, instead imagine that throughout the event, you were exchanging intro cards, something like the following.

An example intro card, 3"×5" sized.

During the event, you could focus completely on the current conversations, knowing you already have some notes provided to you to recall the previous ones.

Is the concept so wild? In Japan, there is a whole interesting culture around exchanging business cards. In the US, we rarely do so. Japan recently went even further, making a whole trading card game for the middle-aged members of their small rural town, connecting the youth to older generations in a heartwarming way.

Naturally, these intro cards might include personal information you probably wouldn't put on the Internet, but yet might want to provide to people depending on the context. So, of course, you should tune the content to the purpose. You should also feel things out first, before you just go handing these to everyone. For example, in the context of introducing yourself to neighbors, maybe it is something like Bart's above. If it's meeting coworkers, maybe it highlights parts of the system you're familiar with, or your favorite software or languages. If it's a hobby group, maybe it highlights more about your specific niche interests.

I've started trying this idea out in a few scenarios, to positive reception. To make it easy, just print these on 3"×5" index cards at home. An example Typst document for it is included below.

Source Code: Example Intro Card in Typst

#set text(font: "Berkeley Mono")
#set text(9pt)
#set par(leading: 0.35em)
#set page(
  width: 3in,
  height: 5in,
  margin: 0.25in,
  // background: rect(width: 100%, height: 100%, stroke: 1pt + black),
)

// Placed here because these are reused to make links
#let telephone_number = "xxx-xxx-xxxx"
#let email_address = "xxxx@example.com"
#let website = "www.example.com"

#grid(
  columns: 100%,
  rows: (1%, 1%, 40%, 2%, 2%, 1fr),
  gutter: 1.0mm,
  grid.cell(
    text(size: 11pt, weight: "bold", "Bart Simpson"),
    align: (left + horizon),
  ),
  [],
  grid.cell(
    block(clip: true, radius: 3mm, image("bart.png")),
    align: (center + horizon),
  ),
  [],
  grid.hline(stroke: (paint: gray, thickness: 0.75pt, cap: "round"), y: 4),
  [],
  grid(
    columns: (20%, 1fr),
    column-gutter: 2mm,
    row-gutter: 2.20mm,
    // stroke: 1pt + silver,
    grid.cell([*age*], align: right), grid.cell(
      [Born in XXXX],
      align: left,
    ),
    grid.cell([*family*], align: right), grid.cell(
      [Spouse: Susan \
        Children: Johnny (M, XXXX)],
      align: left,
    ),
    grid.cell([*rel-to*], align: right), grid.cell(
      [Marge (mom), Homer (dad), Lisa (sis), Maggie (sis)],
      align: left,
    ),
    grid.cell([*from*], align: right), grid.cell(
      [New York, NY (--XXXX) \ Chicago, IL (--XXXX)],
      align: left,
    ),
    grid.cell([*job*], align: right), grid.cell(
      [Manager at #link("https://www.example.com")[Example]],
      align: left,
    ),
    grid.cell([*edu*], align: right), grid.cell(
      [NYU (BS in PR, 'XX)],
      align: left,
    ),
    grid.cell([*email*], align: right), grid.cell(
      link("mailto:" + email_address, email_address),
      align: left,
    ),
    grid.cell([*phone*], align: right), grid.cell(
      link("tel:" + telephone_number, telephone_number),
      align: left,
    ),
    grid.cell([*website*], align: right), grid.cell(
      link("https://" + website, website),
      align: left,
    ),
    [], grid.cell(
      text(size: 5pt, style: "italic")[v25.03], // calver
      align: right + top,
    ),
  )
)

Teammates, not coworkers

2025-03-01T00:00:00+00:00

I was talking with a friend a while back who had gone through some jobs they didn't enjoy, and had now landed on a job they seemed to thoroughly enjoy. When I asked them about it, the key reason they provided for why this particular job seemed so much better was: "I have teammates, not coworkers."

That phrase has resonated with me since.

What distinguishes a "teammate" from a "coworker" in a way that improves job satisfaction like it did for my friend?

Here are some thoughts.

Teammates have shared principles and values

I believe explicitly listing principles and values is incredibly valuable in all sorts of contexts. I particularly think that is true in the context of a company. Many, many companies do this, and know that it is a meaningful way to differentiate themselves to potential applicants as well as provide a guiding force for the business. Sometimes it is under different names, but the purpose is generally the same: broadcast their principles, values, and way of working to attract like-minded teammates. It also goes without saying that professing principles/values doesn't stop a company from being evil (see Enron).

Sometimes, values can come into tension with each other, and that is healthy. But, it's hard to be a good teammate when there is not a large overlap in values. Instead, it will be a consistent source of friction.

Fundamentally, I think this is the key point. Then, depending on what those shared values are, it's easy to see some concrete examples. Here are some examples that I think are teammate behavior drawn from my personal values.

Teammates reduce entropy, coworkers fuel it.

Entropy in engineering shows up a lot of different ways. It could be the codebase (i.e., the software architecture, the abstractions, the tooling, etc.). It could be communication (i.e., messages that lack sufficient context, require unnecessary back-and-forth, etc.). It could be all sorts of other things (documentation, company policies, IT management, and more). I'd also classify complexity in general as a component of entropy, despite the fact that growing complexity is often fundamental to a developing product. I define complexity as APOSD does: "anything related to the structure of a software system that makes it hard to understand and modify the system". This generally pragmatic definition also applies to things outside software. Entropy is the extra noise, disorder, confusion, etc.

I've found that people I'd call teammates naturally reduce entropy (and strive to contain complexity) in their respective domains. Meanwhile, coworkers are often the source.

Some examples:

A coworker sends a bare hello, a teammate includes the context necessary to make asynchronous communication effective.
A teammate opens that PR fixing those 6 typos in the source code comments.
A coworker sends that message tagging a bunch of people to investigate a "super flaky test", only to discover the issue is a real bug and the tests were not flaking at all after people context switch to help. They do not respect others time as much as their own. A teammate is willing to context switch to help.
A coworker opens a PR with a bunch of code that "might be used in the future", even though it's not right now, increasing maintenance burden. A teammate deletes dead code.
A coworker provides unhelpful commit messages like "fix stuff", or has poorly organized commits, or general doesn't explain the why. A teammate provides thorough context that often helps future debugging efforts.
Teammates introduce tooling, frameworks, design patterns, etc. to help systematically reduce complexity.
A coworker sends you a screenshot of text, often of a token or credentials or something you need to then transcribe and enter. They claim innocence, but their actions make it clear they have no respect for your time or appreciation of optimizing communication to get things done.
A teammate is the type of person that puts their shopping carts away, regardless of whether people are watching.

Teammates are the type of people that actively educate and build the collective skills of those they work with. They are the subject of those "Alice showed me how to"- or "I picked this up from Bob"-style comments. They are the ones who introduced you to that game-changing editor feature, or taught you about dotfiles, or helped you get up to speed and build a good mental model for that part of the codebase. They recommended that book that you read that changed how you thought about something. They are the ones you frequently have deep, meaningful conversations with. Teammates share because they want to. Teammates make the people around them more effective now, while also helping them grow and expand their potential in the future.

Here's another way I see this happen. Suppose there is a task that requires some custom effort. Someone probably had to write a little script or something to do the job, maybe had to deal with some edge cases. Now, you are handed essentially that same ticket and a pointer that "it's just like last time".

If you have a teammate, you would go to that other ticket, and likely find everything you need. They probably even shared the snippet they used.

If you have a coworker, you would go that other ticket, and likely find nothing except it being marked "Done".

Coworkers aren't interested in sharing. That's not their job.

Teammates care about the team, coworkers care about themselves

Sure, the company isn't a family. It's not meant to be. But, as DHH says,

You don't have to pretend to be a family to be courteous. Or kind. Or protective. All those values can be expressed even better in principles, policies, and, most importantly, actions.

Teammates care about the team. Teammates break down silos and artificial divisions, resulting in increased unity. They are people you enjoy working with, and you can tell they genuinely care about you. Their pattern of care often extends into their other communities as well. You sincerely look forward to interactions with teammates.

Coworkers don't bother investing in relationships outside what impacts their core job. Interactions with coworkers might be laborious and taxing.

Teammates enjoy the craft, coworkers only see it as a means to an end

This one might be controversial. I think teammates enjoy the craftsmanship of whatever craft they are engaged in. They are often the people that inspire others from their enthusiasm. Maybe they play for the love of the game. Maybe they play to win. They are the ones metaphorically early to practice and always hitting the gym. Their enthusiasm and corresponding work ethic is contagious.

Coworkers are just here to get that cash and do other things.

Indeed, I think it is also common for a person to be a great teammate by this measure in some contexts while simultaneously not being a great teammate in others.

(Nikola Jokić, who I'd argue is a great teammate, is one prominent example of an exception here with the way he exemplifies team play but, in the off-season, couldn't care less about basketball.)

Conclusion

I'm sure I've missed a lot of examples here, but even so, it's been a good source of personal reflection to think about how I myself can try and be a good teammate. I certainly am convinced that striving to be a good teammate, and having good teammates, leads to improved job satisfaction and team success.

How to connect MTP to a kids profile on a Fire tablet

2025-02-08T00:00:00+00:00

This is mostly a note-to-self.

I'm a father with a kid that is starting to get old enough to appreciate some screen time. To that end, we got a cheap Amazon Fire tablet (sidenote, it seems Amazon has a corner on this market).

It was nice, we set up a kid's profile, disabled the store, disabled calling, disabled the web browser, shared VLC (for personal media) and AnkiDroid (for educational flashcards). But, then I couldn't figure out for the life of me how to get media onto the internal storage in a way that was visible to that kid profile!

Here's the trick:

Log in to the kid profile.
Bring down the settings menu by dragging down on the top.
Press and hold the Bluetooth icon until a PIN prompt appears.
Enter your pin.
The "Connected devices" menu will open, where you can change the USB setting to File transfer.
Now, the internal storage reflects this kid profile specifically.

Step 3 in particular was not obvious to me.

Oral histories are family treasures

2025-02-01T00:00:00+00:00

A few years ago, my father passed away from cancer after many tough years of treatment. That was a tough time. Once it became clear that there likely were not many years left, around Thanksgiving and Christmas, I took a trip home with one particular project on my mind: conducting some oral history interviews, particularly with my dad. The artifacts from that project have proved to be treasures to me.

The goals of this post are: (1) plant a seed of persuasion to you that this might be something you might find value in, and (2) share some tips I learned along the way.

Conducting oral history interviews

First, I want to recognize the valuable content that the UCLA Center for Oral History Research has put out. Much of my preparation was simply reading these pages. In fact, for the questions section, I am going to duplicate their page nearly verbatim, as an extra archive. Before that, I want to call out two things that I found particularly valuable before getting to the questions.

First, audio quality matters. I mean it really matters. When I went into this project, my original intention was to just conduct interviews, and then I had a more ambitious goal of actually writing up a family history book. In fact, I even got a couple chapters in, in LaTeX and everything. But, once my father passed, I gained knew appreciation for the high quality audio itself. Sure, a book might be the more effective way of transmitting and documenting information for information's sake. But there was so much value in hearing his voice. Hearing him tell his stories his way. Yes, you could do this with just a cell phone, and that would absolutely be better than nothing. But, if you have some time to do a little prep work, just spending a bit more time and money on getting equipment and learning how to use it brings the value of the audio to another level. The UCLA page suggests some gear. In my case, I went with a Motu M2 audio interface, along with a couple of relatively cheap dynamic XLR microphones, and it worked wonderfully. I recorded with a high bitrate and then distributed OPUS-encoded files to the family.

Second, get a proper release form up front. Again UCLA provides and excellent example. Tune it to your needs. Even if this feels overkill, it sets a good mindset for the interviewee about how this might be used.

Sample outline and questions

In this section, I duplicate the UCLA Center for Oral History Research's family history sample outline and questions nearly verbatim. But, I also have some suggestions on how to prepare that are likely different from a more generic process. Let's start with the outline.

Sample Outline and Questions

1 Early Childhood and Family Background

1.1 Parents and Family

When and where were you born?
Tell me about your parents or your family background
Where was your family originally from?
What did your parents do for a living?
Did you contribute to the family income or help parents in their work in any way?
What was your parents' religious background? How was religion observed in your home?
What were your parents' political beliefs? What political organizations were they involved in?
What other relatives did you have contact with growing up?
What do you remember about your grandparents?
What stories did you hear about earlier ancestors whom you never knew?
How many children were in the family, and where were you in the line-up?
Describe what your siblings were like.
Who were you closest to?
Describe the house you grew up in. Describe your room.
What were your family's economic circumstances? Do you remember any times when money was tight? Do you remember having to do without things you wanted or needed?
What were your duties around the house as a child? What were the other children's duties? How did duties break down by gender?
When did you learn to cook and who taught you? Were there any special family foods or recipes? Do you still make any traditional family foods?
What activities did the family do together?
What did you do on Christmas? Thanksgiving? Birthdays? Other holidays?

1.2 Community You Grew Up In

Describe the community you grew up in.
Describe your neighborhood.
Where did you shop? How far away were these shops and how did you get there?
What's the largest town or city you remember visiting when you were young? Can you describe your impressions of it?

1.3 Early Schooling

What was school like for you? What did you like about it? What was hard about it for you?
Who were your friends at school?
Who were your favorite teachers?
Do you remember teasing or bullying of you or anyone else?

1.4 Friends and Interests

What did you do in your spare time?
Who were your friends and what did you do when you got together?
Did you have any hobbies?
Favorite stories? Favorite games or make-believe? Favorite toys?
What did you want to be when you grew up?

2 Teenage Years

2.1 Changes in Family

How did your relationship with your parents change when you became a teenager?
If you had conflict with them, what was it over?
Did you have chores around the house? What were they?

2.2 School

What were your favorite subjects? Particular interests?
What were your least favorite subjects?
Did you have any memorable teachers? Describe their teaching style. How did they influence you?
What were the different groups at your school? Which did you belong to? How do you think you were perceived by others?
Were you involved in any extracurricular activities? What were they?
What were your plans when you finished school? Education? Work?
What did your parents think of your plans? What did your friends think? What did your friends plan to do?
Did the boys and girls in the family have different plans/expectations?

2.3 Work

Did you have jobs during your teenage years? Doing what?
Did you contribute to the family income? If not, how did you spend your money?

Who were your friends? What did you do together? What individuals did you spend the most time with during this period?
Was your group of friends single-sex, or did it include both boys and girls?
At what age did you begin dating? What kinds of activities did you do on dates? Describe your first date.
What was your parents' advice/rules related to dating/contact with opposite sex?
What were your peer group's norms with regard to dating and relationships with the opposite sex?
What were your hobbies/interests? What books did you read? What music did you listen to? What sports did you play? What crafts did you participate in?

3 Adulthood

3.1 Further Education

3.2 Work and Career

3.3 Marriage or Formation of Significant Relationship

When and where did you meet? What drew you to them?
When and how did you decide to move in together and/or marry?
What was originally the most difficult for you about being married/being in a relationship? What was most satisfying?
What advice would you give to someone today who was contemplating a serious relationship?

3.4 Children

Describe the birth of your children.
What were they each like when they were young? How have they changed or not changed?
What were their relationships with each other and with you like when they were young? Now?
What activities did the family do together?
What family traditions did you try to establish?
Does your family have any heirlooms or objects of sentimental value? What is their origin, and how have they been passed down?
What was most satisfying to you about raising children? What was most difficult?
What values did you try to raise your children with? How did you go about doing that?
What forms of discipline did you use and why?

3.5 Ongoing Interests and Hobbies

4 Overview and Evaluation

What has provided you the greatest satisfaction in life?
How would you say the world has changed since you were young?

Also, ask about historically significant events the family member lived through:

Was your family affected by the Depression?
Did you or anyone close to you serve in a war? What do you remember of that experience?
Did you support or oppose the war in Vietnam? How did you express your political opinions?
Did you participate in, or do you have any memories of any of the movements that came out of the 1950s, '60s, and '70s, such as the civil rights movement or the women's liberation movement?
If the family member belongs to a group that has traditionally been discriminated against: what were you told, both positive and negative, about your group inside your family? Outside? Did you experience discrimination? Who were your role models?
If the family member is an immigrant or the child/grandchild of immigrants: what do you know of the country you or they came from? Why did you or they immigrate? How did you or they immigrate? What were some of your or their experiences and difficulties of beginning a life in a new country?
Do you remember your first contact with such significant inventions as radio, television, or a computer? When did your family first buy these items?

I think you'll agree with me that these are an impressive set of well-considered questions. But, here's the key: customize.

Before you do the interview, maybe in collaboration with other interested parties (e.g., other family members), go through and customize this for that person in particular. For example, asking about their memories about the US civil rights movement might be a pivotal point for some, and largely irrelevant for others. Drop questions that are irrelevant. Add questions you personally want to know. One particularly effective thing to do is to seed examples you can use in the interviews.

Here are some examples. Consider question 1.2.1: "Describe the community you grew up in." This is by all means a great question. But, if you already know something you (or your preparation team) are interested in, having those seeds will make for a better answer. You'll see this technique used in celebrity interviews frequently. For example, you might as the question "Describe the community you grew up in." Then, after they respond, if they didn't touch on a point you'd like to dig into, just a little seed can nudge them the right direction: "Wasn't there a giant tree you broke your hand on once?" If you have stories you've heard in the past you'd love to capture from the primary source in their voice, just a little spark like this often does the trick.

"What did you do in your spare time? I remember you saying once you played a lot of snooker?"

"How did your relationship with your parents change as you became a teenager? I remember Auntie X telling a story about how you ____ one time?"

Finally, be sensitive to sensitive questions. Maybe you heard a story that painted some relative in a bad light. Is it worth recalling here? Does the interviewee want to immortalize this negative story with no anonymity and potentially no evidence? Provide a reminder that the goal of these is to preserve and distribute these stories and have the decency to offer alternative conversations.

Conclusion

Conducting these interviews was a fond memory. I appreciated the recurring teasing about "all this unnecessary equipment". I enjoyed the conversations—I cannot remember ever talking to my dad directly for hours about his life as I did during the course of those weeks.

But as time has passed since his passing, the value of these recordings has only continued to grow.

Luke Hsiao's blog

Using Changesets in a polyglot monorepo

Background

Implementing an automated release process on GitHub

Repository setup

Changeset configuration

Automating releases with GitHub

The glue to create polyglot versioning PRs

Reacting to package tags

Summary

Fixing missing Omarchy boot entries

The outsized impact of cultural idiosyncrasies

Some examples

Google

Oxide Computer

GitLab

37signals

Tonari

Palantir

Jane Street

Amazon

Zappos

Patagonia

Valve

Vannevar Labs

Thoughts

2026 is the year I return to rigorous planning

The methods

Time-block planning

Full task capture

My implementation

Time block planning in Google Calendar

Full task capture in Google Tasks

Thoughts so far

My favorite software in 2025

The List

Berkeley Mono (TX-02)

sshx &

Final thoughts

Switching from GPG to age

Workflow changes

Password manager

No more gpg-agent

Benefits of the age approach

Easy encryption with chezmoi

Easy YubiKey configuration

Thoughts

First impressions of jj from a git fan

What is jj?

First impressions

What I miss from git

Things I like more about jj

Things I still find awkward

My configs

Thoughts so far

ASUS PA32QCV: a programmer's review

First impressions

The less good

Speakers

KVM

Light sync

The surprising

Compatibility

Verdict

AI etiquette

It's the thought that counts

Relatable example in the wild

My pledge

Repairing my Windows bootloader after Omarchy

The problem

The solution

Repairing the Windows bootloader files

Adding Windows to Limine

Berkeley Mono Variable (TX-02) in Ghostty

The youngest sibling advantage

Comparing UTOPIA ISPs

Pricing

Variable fonts and italics across browsers

Performance gains of undervolting a T480s

Steel man arguments, or arguing intelligently

No more `gpg-agent`

Benefits of the `age` approach

What is `jj`?

What I miss from `git`

Things I like more about `jj`