Then it stopped working.

The last commit to the open-source project landed in 2021, and somewhere between macOS updates and Xcode releases, the app wouldn’t build anymore. The codebase, written in Objective-C with roots going back to the Mac OS X 10.4 Tiger era, had accumulated just enough technical debt that modern development tools rejected it.

The Fix

I forked the repository and asked Claude Opus 4.6 to investigate why it wouldn’t build, initially through the mobile app. It connected to the GitHub repository, ran the build tools, parsed through the compilation errors, and identified three specific problems with how the code handled function pointers and linker settings.

The solution? Two type casts and one deleted line. That’s it. No architectural rewrites, no Swift migration, no “modernization.” Just enough to satisfy modern compilers while preserving everything that made the app good.

The entire process, from initial investigation on mobile to a working build on my machine, happened in less than 2 hours. After the code was fixed through the mobile app, I cloned the repository locally to my Mac and ran it in Xcode to verify everything worked. The subsequent packaging and release management was handled through Claude Code in the terminal.

What impressed me most: it never suggested rewriting the entire thing in Swift or “modernizing” the architecture. It understood the goal was minimal intervention: just enough to build, nothing more. The AI’s strength wasn’t in replacing human judgment about what to preserve; it was in executing the tedious work of tracking down compiler errors and making type-safe fixes.

What’s Still There

The codebase still generates hundreds of deprecation warnings for Carbon File Manager APIs, legacy AppKit methods, and old OpenSSL dependencies. These are all deprecated but continue to work on both Intel and Apple Silicon Macs through macOS 15. A proper modernization would require rewriting significant portions of the app—but that’s unnecessary for getting it running today.

The codebase is a time capsule of Mac development practices from 2006-2012: Carbon APIs, FSRef file management, hand-rolled crypto, minimal dependencies. It predates ARC, blocks, Grand Central Dispatch, and most of modern Cocoa.

The Distribution Problem

Building the app was only half the battle. Distributing it revealed a second issue: macOS Gatekeeper.

When users download the app and try to open it, macOS blocks it with a security warning:

“Notational Velocity” cannot be opened because Apple cannot verify it is free of malware.

This is expected behavior for unsigned apps. Here’s how to work around it:

For Users: System Settings Workaround

1. Download the DMG and drag the app to Applications
2. Try to open it (it will be blocked)
3. Go to System Settings → Privacy & Security
4. Scroll to “Security” and click “Open Anyway”
5. Confirm in the dialog

Alternatively, right-click the app and select “Open”—this bypasses Gatekeeper on the first launch.

Upstream Contribution

I’ve submitted a pull request with these fixes to the original Notational Velocity repository. If the original author merges it, users will be able to get signed releases directly from the official project.

If the PR isn’t merged, I’ll distribute properly signed and notarized releases from my fork once my Apple Developer account is approved (currently pending). The Developer account enables:

1. Code signing with a Developer ID certificate
2. Notarization via Apple’s automated malware scan
3. Distribution without security warnings

The Result

The modernized build is available now:

Repository: github.com/and/nv4 Release: v1.0 - Modern macOS Build

The release includes:

• DMG installer ready to run on macOS Sequoia (and earlier versions)
• Full compatibility with Apple Silicon and Intel Macs
• All original features intact

Why It Matters

In an era of Electron apps, subscription note services, and feature-bloated productivity suites, Notational Velocity remains a masterclass in focused software design. It:

• Launches instantly (< 0.5 seconds cold start)
• Searches instantly (incremental search as you type)
• Stays out of your way (no chrome, no sidebars, no “experiences”)
• Stores notes as plain text files (future-proof, greppable, version-controllable)
• Works entirely from the keyboard (mouse optional)

But it’s also a reminder that software doesn’t have to be constantly rewritten to stay valuable. Sometimes the right intervention is the smallest one: just enough modern compatibility to keep running on current hardware, without sacrificing the characteristics that made it good in the first place.

Some software deserves to keep working.

TL;DR: For Developers

What Claude Found

Three specific compilation errors when building on Xcode 16 with macOS SDK 26.2:

1. Incompatible Function Pointer Types in LinkingEditor.m (Line 980)

Code that dynamically swaps cursor implementations assigned function pointers to IMP types without proper casting:

method_setImplementation(defaultIBeamCursorMethod,
    shouldBeWhite ? whiteIBeamCursorIMP : defaultIBeamCursorIMP);

Error: “incompatible function pointer types passing ‘id ()(Class, SEL)’ to parameter of type ‘IMP’ (aka ‘void ()(void)’)”.

Fix: Add explicit cast to IMP:

method_setImplementation(defaultIBeamCursorMethod,
    (IMP)(shouldBeWhite ? whiteIBeamCursorIMP : defaultIBeamCursorIMP));

2. Incompatible Function Pointer Types in GlobalPrefs.m (Line 102)

methodForSelector: returns an IMP but was being assigned to a typed function pointer without explicit cast:

runCallbacksIMP = [self methodForSelector:@selector(notifyCallbacksForSelector:excludingSender:)];

Fix: Cast the IMP to the specific function pointer type:

runCallbacksIMP = (id (*)(GlobalPrefs*, SEL, SEL, id))[self methodForSelector:@selector(notifyCallbacksForSelector:excludingSender:)];

3. Unknown Linker Option

The Xcode project included -whatsloaded in OTHER_LDFLAGS, a legacy flag removed in modern linkers.

Fix: Delete the flag from project settings:

OTHER_LDFLAGS = (
    "-whatsloaded",  // ← Deleted this line
    "-weak_framework",
    PDFKit,
    ...
);

What’s Not Fixed

The codebase still has:

• Hundreds of deprecation warnings for Carbon File Manager APIs (FSRef, FSSpec, etc.)
• Warnings about deprecated NSAlert methods (NSRunAlertPanel, etc.)
• Warnings about legacy pasteboard types
• OpenSSL dependencies (should migrate to CommonCrypto)

These generate warnings but don’t prevent compilation. They work through OS compatibility shims.

If you’re interested in helping maintain or extend this project, contributions are welcome at github.com/and/nv4. Special areas for improvement: migrating to CommonCrypto, replacing Carbon File Manager calls with modern equivalents, and adding proper code signing infrastructure.

The Setup

The system uses two repositories:

• A private repo where I write posts as issues
• A public repo (and.github.io) that serves the Jekyll blog via GitHub Pages

A GitHub Actions workflow watches for the publish label. When I add it to an issue, the workflow converts the issue into a Jekyll post, builds the site, and pushes it to the public repo. Removing the label or closing the issue takes the post down.

Labels double as categories — any label except publish becomes a post category.

The Image Problem

This worked immediately for text, but images broke. When you upload an image to a GitHub issue, it gets a URL like:

https://github.com/user-attachments/assets/f4742aba-1db3-4caf-ad23-05040e7b6144

In a private repo, these URLs are private. They can’t be accessed by anonymous visitors to the public blog. So the workflow needs to download the images and commit them to the public repo.

The obvious approach — curl with the GITHUB_TOKEN — doesn’t work. The automatic GITHUB_TOKEN in GitHub Actions cannot download user-uploaded attachment assets. Neither can fine-grained PATs scoped to the repo. They all return “Not Found”.

The Fix

The solution uses the GitHub REST API itself to get around this limitation:

1. Call the REST API to fetch the issue with Accept: application/vnd.github.full+json. This returns the issue body as rendered HTML in the body_html field.

2. The rendered HTML contains signed CDN URLs. Instead of the original user-attachments URL, the HTML has URLs like:

   https://private-user-images.githubusercontent.com/24557/546715488-f4742aba-....png?jwt=eyJ...
   

   These signed URLs include a JWT token and are downloadable without any authentication.

3. Match by UUID. The original URL and the signed URL both contain the same UUID (f4742aba-1db3-4caf-ad23-05040e7b6144), so the workflow maps one to the other, downloads from the signed URL, and replaces the original URL in the markdown with a local path.

The key permission requirement: the workflow needs issues: read on the GITHUB_TOKEN for the API call. This isn’t granted by default when you add an explicit permissions block — and if you add permissions at all, you also need to explicitly include contents: read for the checkout step, since the block replaces all defaults.

What the Workflow Does

When an issue gets the publish label:

1. Checks out both the private and public repos
2. Fetches the issue’s rendered HTML via the API
3. Extracts user-attachments URLs from the markdown body
4. Finds matching signed CDN URLs in the rendered HTML (by UUID)
5. Downloads each image, detects its actual MIME type, and saves it with the correct extension
6. Verifies each download is a real image (not an error page)
7. Replaces the GitHub URLs with local paths in the post body
8. Writes the Jekyll post file with front matter
9. Builds the Jekyll site
10. Commits and pushes to the public repo (with git pull --rebase to handle concurrent runs)

When the label is removed or the issue is closed, the post and its images are deleted.

The Mobile Workflow

This is really what makes it worthwhile. From my phone:

1. Open GitHub (app or browser)
2. Create a new issue
3. Write the post in markdown, drag in images
4. Add the publish label
5. Submit

The post is live in about a minute. No laptop needed, no git commands, no deploy scripts. Just write and publish.