Build.ms

Small Steps For Agent-Friendly Codebases

Joe Fabisevich — Wed, 11 Mar 2026 12:00:00 GMT

I’ve just released Recap 2.0 — my open source library for creating beautiful What’s New screens from markdown. The primary purpose for this update was interface improvements I need to include in Plinky for Mac (available very soon!), but the underlying story is more important.

This is my first open source release where an agent wrote 100% of the code. I was deeply involved in prompting and guiding the work, which taught me an important lesson about working with agents.

Building For Agents

I write code with agents every day — probably 90-95% of my code is the result of an agentic workflow. When I started working on Recap that number was closer to 5 or 10%, so my working style has changed a lot more than the project itself. When I started updating Recap for 2.0, I quickly realized the codebase wasn’t set up well for agents to work with.

Updating Recap felt a bit like stepping into a time machine because the project had no structure in place to make agentic development easier. The first thing I did was create an llms.txt file that defines the project’s structure and functionality. This small file makes a big difference, letting an agent be laser-focused rather than fumbling around brute forcing solutions.

Then I built a Recap Integration Skill that handles the hard work of adding Recap to your project. Something I’ve learned as an open source maintainer is that people will find the most creative ways to misuse your library. I’ve always wanted a way to prevent questions from people who’ve misunderstood how my open source project works and gotten stuck trying to fix their mistakes.

In the past I’ve solved this by writing lots of time-consuming documentation. The tradeoff is worthwhile for my projects like Boutique which have thousands of users, but there isn’t as much payoff for smaller projects. Creating a skill solves this by teaching an agent how to write the code you want, and that’s what makes the recap-integration skill the real highlight of Recap 2.0.

Updating a project for agentic workflows isn’t just for open source, it will help you in any codebase where you use tools like Claude Code, Codex, and Cursor.

Your Turn

If you want to get better at working with agents, start small. Some of the highest leverage work you can do is to make your codebase agent-friendly. Much like professional pianists still practice their scales, you can level up your fundamentals by practicing on a small project. It’s more difficult to begin with a large established codebase, but the lessons you learn in a small project will transfer over to codebases of all sizes.

The work of making your codebase agent-friendly starts with one small question: What would make your codebase easier for an agent to work with? You can figure this out by reading up on agents, taking a workshop, or even trial and error — but that question alone will point you towards the changes you need to make.

If you want to see what that looks like in practice, check out Recap on Github. It’s a concrete example of a small project restructured with agents in mind, and I’m always happy to answer any questions you may have about it.

The Hidden Cost Of Communication (A Case Against Big Companies)

Joe Fabisevich — Fri, 27 Feb 2026 12:00:00 GMT

I think Twitter is as guilty of hiring too fast as Google and most of these other companies, the problem of bloat is just way bigger at Google and has been for over a decade now.

That’s what I said in 2020 while working at Twitter, and I still believe it. Now as I watch companies like Square lay off 40% of their workforce, I’m certain now that this isn’t solely about corporate greed or AI replacing workers — this is a sectoral shift that’s been a decade in the making, and we’re finally seeing it accelerate.

People who have never worked at a large tech company believe that these companies are overstaffed. But workers at these companies will tell you the opposite — convinced their firm is understaffed because they’re constantly fighting for resources. So how do we square this circle? This isn’t directly a symptom of mismanagement, mismanagement is what happens when you underrate the hidden costs of communication.

Size Matters

These moves are rational because large companies aren’t overstaffed or understaffed — they’re overstaffed and under-focused. That’s why everyone at tech companies with 50,000 employees are always complaining that despite 49,999 coworkers, everything is inefficient. The naive solution is to hire more, but the real answer is to reduce bandwidth.

There’s a saying that the job of a CEO is to say the same thing 10 times until everyone hears it. The larger your company, the further information has to diffuse, the more people have to coordinate — and the harder it becomes to actually get anything done. Go ahead and try it out yourself.

Notice that when we go from 1 to 5 people we don’t just have 4 more people, we have 10 new connections between people. Going from 5 to 10 increases connections from 10 to 45. Going from 10 to 500 brings us to 124,750 connections, and 50,000 people takes us all the way to 1,249,975,000 connections. Building a product is a team sport, and it gets exponentially harder to play together the more people you add.

Communication Is Everything

Imagine you’re a CEO and need to make a fundamental shift in your product:

1 person: You shift the product instantly.
5 people: You get everyone in a room and decide in a few hours.
10 people: You do all that and hold a company meeting where you explain why you’re making this change.
50 people: You coordinate with your executive team on how to cascade this change through the organization.
500 people: You reshape the entire company around this change — layoffs, restructuring, and a redefined mission.
50,000 people: You execute this across every organization, team, and product, and make your case to public markets.

This is why the goal of a company is not to grow, but to avoid headcount growth while maximizing revenue and profits. Because the overhead for communication is so high, every employee you hire only produces marginal returns — maybe 10 or 20% more throughput once you account for coordination costs.

AI

It’s hard to ignore the elephant in the room: AI. AI really can make people more efficient and allow them to do more with less. But as this HBR study shows, AI doesn’t reduce work — it intensifies it.

The bottleneck was never the amount of work a person could do. It was always the number of interconnected edges in a system — the communication overhead. AI makes individuals more productive, but it doesn’t make large organizations better at coordinating. The people don’t get better at communicating as fast as the models get better at doing the work. So you can do more, but you still can’t align 50,000 people any faster than you could before.

This is why the layoffs we’re seeing aren’t just about replacing workers with AI. They’re about companies finally accepting what was always inevitable — you don’t need 50,000 people to do the work of 30,000. You never did, but AI has made this reality impossible to ignore.

Workers

Now don’t get me wrong, this essay isn’t meant to be some sort of pro-capital anti-labor screed. My heart goes out to all of the people who were laid off from Square yesterday, from Amazon before that, and from Microsoft, Google, and all the other big tech companies that have done layoffs recently. This all makes me very squirmy as a person who sometimes considers reentering the workforce.

This post isn’t meant to be solace, but a cold hard look at our reality. For companies like Square, this is a reset to focus on what matters most — with fewer employees and more efficiency. I’ve been saying this for 6 years — long before ChatGPT — so I’m confident this isn’t just an AI story.

In response, I always hear an optimistic argument — these smart people will start companies of their own and outcompete the big players. But there’s no evidence the market needs more companies selling the same products to fewer employed people. If 50 people get laid off from TikTok, there’s no natural law that says the market will suddenly clamor for more innovation in short-form video.

Some of these people will certainly create new companies and new jobs. But there’s no guarantee those jobs will be recouped — and even if they are, it may take years. In the meantime, the people laid off today are looking for work in a market that’s contracting, not expanding.

And that’s why my takeaway is that big companies are going to get smaller and smaller, and smaller companies may follow suit. I wish I had tangible advice to share, but all I can say is brace for change across the industry, because it’s a-comin’.

Automating Codex

Joe Fabisevich — Thu, 12 Feb 2026 12:00:00 GMT

There’s an adage that says using AI is like having an intern at your disposal. The metaphor usually carries a negative connotation — a lowly helper without much skill. But it’s apt because of the style of work AI actually does.

You set an intern off to go do some work
They come back saying they’ve completed their assignment
You show them where there are gaps, and nudge them in the right direction
Repeat 5-10x until they get where you wanted them to go

Last week OpenAI released an app for their coding agent Codex. ¹ At first glance, it looks like it just makes their Codex CLI more accessible — much like Claude Cowork is an interface to Claude Code for people who don’t live in a terminal. But there’s a premiere feature that instantly provided value: automations.

Automations

An automation in Codex is as simple as it sounds. You configure a task to run on a regular basis, and it goes off and does some work for you. This work can be anything — and it’s safer than other approaches because it runs in whatever sandbox environment you’ve set up.

Setting up an automation is easy. You give Codex a title, decide which projects it can access, and write a prompt to execute. Then you pick how often the automation will run — and it’ll execute whenever your computer is on. (In the future, automations will run in Codex Cloud, so you won’t need to keep your computer on.)

Your Summer Intern

Let’s push the intern analogy a little further. On their first day, an intern knows nothing and your job is to teach them the ropes. They don’t know anyone, don’t know what they’ll be doing, and don’t even know how you take your coffee. You should expect little from a college kid who’s never held down a full-time job before.

By summer’s end though, they’ll have experience under their belt. They know their projects, understand how to work with product and design, and you can leave them alone for longer stretches of time. If you’ve been working closely with them, they may even anticipate your next move.

This anticipation is what automations do so well. If you’ve defined a task well, you suddenly have an intern who understands what you need. Not only can they do it, but they’re confident and now proactive about it. This is the agentic unlock that automations bring — what really separates an automation from using ChatGPT to solve a problem.

Real World Automations

My first automation was inspired by a tweet from Dominik Kundel of OpenAI’s SDK team:

💪 Have Codex automatically become better

Add a daily task to read your past sessions in ~/.codex/sessions and update your https://t.co/DKdqY6VTPu files or update/create new skills for common tasks. pic.twitter.com/8ME7LWu3ML
— dominik kundel (@dkundel) February 2, 2026

That got me thinking: what else could I make Codex do while I slept? I wanted something small enough to easily review, but important enough to actually derive value from. Basically, I want someone to help me with all the low-hanging fruit on my roadmap — so that’s exactly the automation I set up.

Low Hanging Fruit

I built a simple automation that works like this:

Codex reads Plinky’s internal roadmap, which I keep in a Craft doc. This document is accessible via MCP, so Codex can read through my backlog of features and issues.
Codex reads my codebase to understand how easy or hard each task will be.
Then it builds a small feature, improves code quality, or fixes up some technical debt.

I turned those steps into a prompt:

We are looking to pick off one piece of low-hanging fruit based on the state of our roadmap and our codebase. (This will usually be main, but not always.) This will take the shape of a clean up task to improve code quality, a fix for some technical debt you encounter, or something small from our roadmap.

The roadmap is accessible via our plinky_roadmap MCP server.

I want you to read through our codebase so you can understand the current state of our app. Then you will read the roadmap and find an item that is not done, but you would estimate has a small level of effort but a high level of return. It’s important to note that the two may be slightly out of sync, but that the code is our source of truth. (If there’s a completed task on our roadmap that seems to not be marked as complete, you can include that in your response.)

Then I want you to execute on a code quality improvement, a feature that you think would be valuable to Plinky, or even an improvement to our documentation at an important or tricky point in the code. Every task you do requires a code review so try to not add too much work onto our plate — and focus on high leverage actions.

And the results were instantly useful! Codex cleaned up extraneous logging code from debugging Plinky’s browser extension, modernized SwiftUI call-sites from the deprecated foregroundColor API to foregroundStyle, and caught that my CSV exporter used \n instead of carriage returns.

These are small paper cuts that accumulate over 5 years of work, but fixing them one by one creates a better home for your code. Better yet, Codex went to my roadmap and found a hastily scrawled note that said “Add tests to LinksListFilterStateTests that validate ordering for pinned links.” I’d promptly forgotten about this after writing it down — but a few seconds later I had tests.

I re-ran the automation a few more times and the results got even better. Codex fixed a bug in how I parse webhook payloads, extracted repetitive code into a private helper function, and found a subtle performance improvement by pre-sorting an array I was re-sorting on every View recalculation. All I did was write a prompt and I had a bug fix, improved code, and a small scrolling hitch had been eliminated.

The Future Is Automation

It’s not hard to see where this is going — any task that fits the shape of software is a task that can be automated. An indie like me is thrilled to have extra hands, but tools like these work for teams small and large.

I started with a small scope because code review is still my bottleneck, but I’ve continued tweaking my prompts and adding more responsibility. Your intern is only as good as your prompts. I’ve spoken at length about how your ability to prompt and build context for an agentic system is paramount, but I’ve also set my coding environment up with Codex Skills to make Codex write code the way I like it written.

Automations are new, so I haven’t implemented all of these yet, but here are a few ideas you can try:

Nightly issue triage: Scan your issue tracker (Sentry, GitHub Issues, Linear) to assign priorities, identify duplicates, and suggest labels.

Prompt

Triage open issues for this project.

Review open issues from the issue tracker and recent commits for context.

For each issue, determine category, relative priority (high/medium/low), and whether it appears to be a duplicate.

Produce:

A short list of high-priority issues with justification.
Suspected duplicates and why they overlap.
Suggested labels or metadata.

Do not close issues or make destructive changes.

Automated architectural docs: Parse code changes and update or infer architectural diagrams and high-level readmes.

Prompt

Keep architectural documentation aligned with the codebase.

Review recent commits, existing README and architecture docs, and overall project structure.

Identify meaningful changes to components, data flow, boundaries, or integrations.

Propose concise updates to existing documentation, or specific additions where gaps exist.

Focus on preserving intent and helping new contributors understand the system. Keep changes minimal.

Automated test health monitor: Evaluate your test suite to find flaky tests, suggest missing edge cases, and propose new tests for untested logic.

Prompt

Evaluate the overall health of the test suite.

Review test files, recent failures or flakes, and recently changed code paths.

Identify:

Flaky or brittle tests
Important logic paths lacking coverage
Redundant or low-signal tests

Produce:

A short list of test risks.
One or two high-leverage test improvements.

Avoid broad rewrites. Optimize for confidence per line of test code.

Product surface area audit: Periodically list features users can see, can’t discover, and misunderstand. Then suggest one small affordance — a copy tweak, default, or UI nudge to reduce that gap.

Prompt

I want you to audit the current product surface area of this project.

First, read through the codebase, UI components, feature flags, onboarding flows, and any relevant product documentation to understand what the product can do today.

Then produce three short lists:

Features that are clearly visible and discoverable to users.
Features that exist but are difficult to discover without prior knowledge.
Features that users are likely to misunderstand based on naming, defaults, or UI affordances.

For each item in lists 2 and 3, propose one small, low-risk improvement (copy change, default tweak, UI hint, reordering, or documentation note).

Do not propose large redesigns or new features. Optimize for leverage and simplicity.

Solicit more ideas: If you had one uninterrupted hour today, what’s the single change that would most improve the product?

Prompt

Determine the single highest-leverage improvement I could make if I had one uninterrupted hour to work on this project today.

Review recent commits, open issues, roadmap items, and relevant documentation.

Then answer:

What is the one change that would most improve the product, developer experience, or user experience?
Why this is high leverage right now.

Constraints:

Propose only one action.
It must plausibly fit within one focused hour.
Prefer actions that reduce future work or unlock momentum.

Do not include alternatives.

And if you think of any good automations, please reach out and tell me what you’ve come up with!

The models keep getting better, and as they become more trustworthy, I’ll continue delegating more to them. This is a glimpse into the agentic coding future we’ve been promised — and there’s still so much more to do.

Footnotes

The app is currently available for macOS, but Windows and Linux are coming soon. ↩

Read The Code (Sometimes)

Joe Fabisevich — Mon, 09 Feb 2026 12:00:00 GMT

This weekend there was once again a debate about the future of programming, stemming from this comment by a longtime developer Steven Troughton-Smith. Steven has just gotten into using AI for programming, and as a result he is discovering just how powerful it is.

- Steven Troughton-Smith on Mastodon

There are a lot of people who haven’t invested much in using agentic systems to write code, for many perfectly good reasons. And often, they haven’t updated their understanding of how LLMs work, still calling them “random word predictors” or “stochastic parrots” — without considering how much more complex agentic systems like Claude Code or Codex have become. As a result, there’s often a lot of debate (particularly on Mastodon) built on false premises or misunderstandings about how LLMs work.

Then there are sensible people like Manton Reece who are not just looking to prove their worldview is right. Manton wrote a blog post titled Read The Code that I mostly approve of, but also subtly disagree with. The premise is that you still need to read the code that agentic coding tools output. I follow this rule when it comes to the Plinky — a piece of software I derive my livelihood from — but I want to share a story that directionally agrees with Steven. As programming becomes more abstracted, what matters most is not whether you can read the code, but whether you understand the problem you’re solving. Domain expertise — not code literacy — is becoming the real differentiator.

Building A Financial Model

Last night, I saw this play out firsthand. My wife Colleen and I built an app to create a visual representation for when we can retire. We spent 20 minutes writing a prompt that codified our goals and circumstances, and Claude generated a tool that let us visualize our financial options. I wanted to see what our future would look like if I stayed indie, or if I went back to work full-time for 2, 5, 7, or 10 years. We added variables like cost of living, the percentage of real GDP growth, whether we’d have a family, and a few other factors relevant to our personal life.

We asked Claude to ask us some more questions to fill in any gaps for the things we didn’t consider, and spent about 10 minutes answering those follow ups. We went through a few iterations because we had to tweak scenarios and variables — all done through prompting. At some point Colleen noticed we could never retire earlier than 2040 no matter what we changed — even if we simulated ourselves winning the lottery. Many programmers would say “this is proof an LLM can’t do math,” but it’s just code under the hood. The real problem is that most people would have accepted the incorrect output and made important life decisions based on flawed software.

But Colleen doesn’t know how to code, and instead she suggested we ask the model in plain English what assumptions it had baked in. It listed 15 assumptions, and one was “I assumed you wouldn’t want to retire before 2040.” We both exclaimed “wait, why?” — and Colleen joked that the model wants us to keep working so we can afford more tokens.

Rather than scrapping the project, we cleaned up the assumptions and kept testing until the results matched our intuitions. It was more than intuition though — we had a few known outcomes — unit tests by another name. You know what we never did though? Look at the code. The more important factor was working through this with someone who has financial modeling experience, because we could validate our assumptions and outputs in other ways.

Not Quite Assembly, But Close

It was effectively assembly to us. With no programming experience, Colleen couldn’t have understood what it was doing, so it definitely was assembly to her. But she didn’t really need to. What mattered most was that she could validate the outputs, ask the right questions, and catch the flawed assumptions baked into our financial model. In this case — and in many cases — having domain expertise is more powerful than being able to write code.

This is why I think Steven is more directionally correct than Manton, even though I still will often read the code. Not because all software will be built this way — I certainly don’t want to fly in a plane powered by software built with intuition. At the same time a reasonable amount of software will be built this way, with little or no detriment to users. Software is not just random code — it’s intuition and experience codified into syntax.

When I work with non-technical students at Pursuit or in my workshops I’ll often get questions about what they can do without knowing how to code. Some have huge ambitions so I tell them that vibe coding won’t help them build the next Google, but it will let them build software that solves real problems they have. And if you have the right foundation of knowledge, you won’t even need to look at the code.

Supporting Markdown Search For LLMs

Joe Fabisevich — Mon, 02 Feb 2026 12:00:00 GMT

This post shows you how to support markdown search for your blog, making it token-efficient to search through your content. It also has a lesson about how context windows work and markdown work. If you only want the implementation steps, you can skip all that and go straight to “So What Are We Doing?”.

If there’s one thing LLMs struggle with, it’s efficiency. I’m not talking about environmental impact — I’m talking about context windows and tokens.

LLMs know a lot of things, but they don’t know everything. When they recognize they don’t know something, they may fall back to searching the web to learn more. This is great because it means they can access the latest information available to solve the problem.

But when LLMs retrieve information from the web, they need to store it somewhere they can reference while working. You can’t keep every word of every book you’ve ever read in your head — and neither can LLMs. Instead, they store retrieved information in a small amount of quickly accessible memory called a context window.

A Primer On Context Windows

An LLM’s context window can’t be infinitely large because the data we put in it needs to be stored somewhere, and it has to be accessed quickly. Having to access it quickly rules out traditional long-term storage mechanisms like databases, because they’re too slow. In effect, we have two constraints: we want to keep only the most important information, and we need to make it as compact as possible.

Before we move on, we need to go over a few facts about context windows:

The text (or images) you put into an LLM are converted into an LLM-friendly format called tokens.
A token is a chunk of data that makes it easier for an LLM to process information.
Counting tokens isn’t as straightforward as you’d expect, but here are some rough guidelines: about 3-4 characters of text = 1 token, or roughly 1 word = 1.33 tokens.
The average Harry Potter book is 135,000 words long, or about 180,000 tokens.
The latest models at the time of this writing are Claude Opus 4.5 and GPT-5.2 — which have context windows of 200K and 400K tokens respectively.
This is a pretty limited space, so once you’ve reached the end of your token window, LLMs will do their best to summarize the conversation. Summarization, though, can lose important details.

This means you can safely fit 1-2 Harry Potter books in a context window — which is far smaller than the entirety of the internet. In practice, that’s approximately 10-15 of my blog posts, or roughly 2-3 hours of video on YouTube.

And that’s why we need to be selective when we ask LLMs to search the web for information. When Claude goes off to search the web, it may retrieve far more data than its context window can hold!

And That’s Why We Need Markdown

The good news is that my blog posts are written in markdown — a lightweight markup language created by John Gruber. If you’re reading this, you’ve likely used markdown to bold or italicize text by adding _ or ** around words or sentences.

Markdown is very lightweight compared to HTML because it’s plain-text without any markup. (Hence the name markdown — which I only just realized as I was writing this sentence. 😆) Sharing the markdown version of a blog post will save precious tokens — which lets LLMs store and access more information in their context window.

In the next version of Claude Code, Claude’s WebFetch tool automatically adds Accept: “text/markdown, *” to requests which helps docs sites provide token-efficient docs https://t.co/CZWdH0OZsO pic.twitter.com/uYthd1m9RP
— Boris Cherny (@bcherny) November 13, 2025

This approach has become standard practice — Claude Code now automatically searches for markdown versions of websites, and other tools like Codex have followed suit. Yet despite its importance, few websites have implemented this technique. Here’s how to be one of them.

So What Are We Doing?

We’re going to do two things.

Add support for serving markdown versions of our blog posts.
Direct LLMs to browse the markdown version instead of our HTML-rendered blog posts.

Or more technically:

When someone adds .md to a blog post URL, we’ll serve the markdown version of that post. (Try it yourself with this post: build.ms/2026/2/2/supporting-markdown-search-for-llms.md)
We’ll build a small middleware layer that redirects LLMs to the markdown version when they request a page with an Accept header of text/markdown.

Adding Markdown Support To Your Website

Build.ms uses the Astro static site generator, but this technique works for any static site generator. To give you an idea of what we want to do, here’s the prompt I gave to Codex to build this feature:

Is it possible for us to expose the original markdown of our posts whenever the user adds a .md extension to a URL? This has become a common pattern for letting AI tools crawl websites, providing a more direct format that they can consume easily.

The result was a file called [slug].md.ts. This file convention creates a route that serves the markdown version of your blog post. Now when a person (or LLM) adds .md to any blog post URL on build.ms, they see the markdown version of our post.

Expand to see the code for [slug].md.ts

import type { APIRoute } from 'astro';
import { type CollectionEntry, getCollection } from 'astro:content';
import { readFile } from 'node:fs/promises';
import path from 'node:path';

interface MarkdownProps {
	filePath: string;
	slug: string;
	pubDate: string;
}

function hasFilePath(post: CollectionEntry<'blog'>): post is CollectionEntry<'blog'> & { filePath: string } {
	return typeof post.filePath === 'string';
}

function buildParams(post: CollectionEntry<'blog'>) {
	const date = new Date(post.data.pubDate);

	return {
		year: date.getFullYear().toString(),
		month: (date.getMonth() + 1).toString(),
		day: date.getDate().toString(),
		slug: post.id,
	};
}

export async function getStaticPaths() {
	const posts = await getCollection('blog');

	return posts
		.filter(hasFilePath)
		.map((post) => ({
			params: buildParams(post),
			props: {
				filePath: post.filePath,
				slug: post.id,
				pubDate: new Date(post.data.pubDate).toISOString(),
			},
		}));
}

export const GET: APIRoute = async ({ params, props }) => {
	const { filePath, slug, pubDate } = props as MarkdownProps;

	if (!filePath || !slug || !pubDate) {
		return new Response('Not found', { status: 404 });
	}

	const parsedDate = new Date(pubDate);
	const year = Number(params.year);
	const month = Number(params.month);
	const day = Number(params.day);

	if (Number.isNaN(year) || Number.isNaN(month) || Number.isNaN(day)) {
		return new Response('Not found', { status: 404 });
	}

	if (
		parsedDate.getFullYear() !== year ||
		parsedDate.getMonth() + 1 !== month ||
		parsedDate.getDate() !== day ||
		slug !== params.slug
	) {
		return new Response('Not found', { status: 404 });
	}

	try {
		const absolutePath = path.resolve(process.cwd(), filePath);
		const markdown = await readFile(absolutePath, 'utf-8');

		return new Response(markdown, {
			status: 200,
			headers: {
				'Content-Type': 'text/markdown; charset=utf-8',
				'Cache-Control': 'public, max-age=3600',
			},
		});
	} catch (error) {
		console.error('Failed to load markdown for', filePath, error);
		return new Response('Not found', { status: 404 });
	}
};

We can now start dropping links with .md extensions in our prompts and watch our token count drop. But it would be better if this process was automatic. To do that, I wrote another prompt that explains our goals, so Codex can solve our problem.

I just want to check something. The reason we built this was because I saw this post from the Claude Code team.

> In the next version of Claude Code, Claude’s WebFetch tool automatically adds Accept: “text/markdown, *” to requests which helps docs sites provide token-efficient docs

The reason we recently added support for .md extensions rendering markdown docs was to support this feature, but are we handling that? If not, can we add that somehow?

Expand to see the code for our middleware

import type { MiddlewareHandler } from 'astro';

const blogPathPattern = /^\/\d{4}\/\d{1,2}\/\d{1,2}\/[^/]+\/?$/;

// Redirect markdown-preferring clients to the raw .md blog route (e.g. Claude WebFetch).
export const onRequest: MiddlewareHandler = async ({ request }, next) => {
  const acceptHeader = request.headers.get('accept') ?? '';

  if (!acceptHeader.toLowerCase().includes('text/markdown')) {
    return next();
  }

  const url = new URL(request.url);

  if (!blogPathPattern.test(url.pathname) || url.pathname.endsWith('.md')) {
    return next();
  }

  const segments = url.pathname.replace(/\/$/, '').split('/').filter(Boolean);
  const [year, month, day, slug] = segments;

  if (!year || !month || !day || !slug) {
    return next();
  }

  const markdownPath = `/${Number(year)}/${Number(month)}/${Number(day)}/${slug}.md${url.search}`;
  const location = new URL(markdownPath, url);

  return new Response(null, {
    status: 307,
    headers: {
      Location: location.toString(),
      Vary: 'Accept',
    },
  });
};

And just like that, Codex added a middleware layer that redirects any request with an Accept header of text/markdown to the .md version of our blog post. Now the two-step process is complete, and our token usage will automatically be optimized.

And That’s It?

As you can see adding support for the text/markdown Accept header is straightforward and easy! And it’s beneficial: LLMs get more accurate information, they use fewer tokens, and your website saves on bandwidth costs.

You can implement this feature yourself, but rather than writing the code, let’s use the technique I shared in Building Software From Blog Posts. Point Codex or Claude Code to this blog post and let it handle the implementation.

Here’s a prompt you can use — with all the context you’ll need.

Please read this blog post (https://build.ms/2026/2/2/supporting-markdown-search-for-llms) that describes a process for adding support for the text/markdown Accept header — allowing LLMs to more easily and efficiently parse the contents of a statically generated blog. We want to implement the same technique for our static site generator — regardless of whether it’s Astro or not. If there are any concerns please raise them before we begin building this feature. If there are no concerns, please implement a solution that solves this problem for us in our static site.

Updating Your Website For Generative Engine Optimization

Joe Fabisevich — Thu, 29 Jan 2026 12:00:00 GMT

Generative Engine Optimization — also called AI SEO, AEO, GEO, or LLMO — is the equivalent of SEO for AI search. Regardless of what acronym you prefer, it’s becoming increasingly important for agentic tools like ChatGPT, Claude, and Gemini to know about you and your website — whether you’re a developer, marketer, content creator, or business owner. I’ve never been particularly good at SEO, so I was very excited when I stumbled upon this post by Cassidy Williams.

To quote Cassidy Williams (a brilliant developer, writer, and content creator), the most important things you can do are:

Creating an /llms.txt file

Adding “LLM-readable” structured pages (often called /for-llms)

Adding Schema.org data to the pages of my website

Being consistent with naming, phrases, and taglines

Naturally, instead of doing all of this myself, I wrote this prompt in Codex and had it generate all of these files for me!

I want to update my blog to be more generative AI search-friendly.

Can you read this blog post to understand how we can do this: https://cassidoo.co/post/ai-llm-discoverability

I want you to then read through my src/pages/about.astro page, knowing that a lot has changed about me since I wrote it. I want you to read all of the blog posts we have on this website and search the web and to find everything you can about Joe Fabisevich, then lightly update the page accordingly based on my goals and mission for the website. Keep the writing style the same though so we don’t lose my voice.

As per the blog post then I want you to write a great llms.txt, for-llms page, and anything else that’s missing for AI tools to know about build.ms.

I noticed we’re missing a robots.txt which helps AI crawlers know how to browse my site, so make sure to add one.

Before we start, do you have any clarifying questions I can answer to make this process work better?

I answered a few clarifying questions Codex had about my website and did some light editing to keep my voice intact — and that was it. Codex did 98-99% of the work, and while it was generating those files, I’d already started writing this blog post.

It’s more important than ever to be discoverable on the internet, and GEO is the next generation of discoverability. If you have a website and want to be found, you’ll need to make your website GEO-friendly. The good news is that agentic tools are great at generating GEO-friendly pages. All you need to do is copy the prompt above — change a few words — and let Codex do the rest. Can’t wait to find you on the internet!

AI Agents Are Starting To Eat SaaS (Really)

Joe Fabisevich — Mon, 26 Jan 2026 12:00:00 GMT

A few weeks ago I read an essay titled AI Agents Are Starting To Eat SaaS. SaaS businesses have thrived by solving specific problems — outsourcing domain-specific knowledge so companies don’t have to build it themselves. A software company buys Workday instead of building HR software. A healthcare company uses Salesforce instead of maintaining a custom CRM. A piano teacher pays $9.99/month for Calendly instead of building their own booking system.

The responses to that essay were full of skepticism — people saying they haven’t noticed any real decline in SaaS adoption. That may be true for them, but the most important word in the title is Starting. It’s too early to see a trend, but I’ve already heard dozens of stories where people are building internal solutions through prompting rather than turning to a SaaS tool. I’ve done this myself quite a few times since I’d rather spend 30 minutes building something personalized to my needs than pay $4.99 every month for a generic solution.

I was wondering how long exactly it's been since I first articulated this exact scenario, and it turns out the answer is 33 months.

[image or embed]
— Joe Fabisevich (@mergesort.me) January 10, 2026 at 11:49 AM

I’ve been called the boy who cries wolf for three years, predicting that soon enough building your own app would become cheaper and easier than buying SaaS — and that custom solutions would be better because they’re tailored to your needs. The main pushback has always been that it requires skill to prompt effectively, and most people lack that know-how. But LLMs keep improving while AI tools keep getting easier to use. This is really important because these improvements compound, lowering the barrier to entry for millions of people.

As a software developer who spends his days building a link-saving app and his nights telling everyone that in the very near future people will be able to easily build their own software to solve their personal problems — this is my existential crisis coming to life.

[image or embed]
— Joe Fabisevich (@mergesort.me) January 10, 2026 at 10:55 AM

As the boy who cried wolf, I feel confident that a wolf has finally walked into a town full of software developers building SaaS products. The person who wrote the thread I’m quoting isn’t a software developer — it’s Kevin Roose, a reporter for The NY Times. He missed Pocket after it shut down, so he tried every link-saving app available. None met his needs, so over the Christmas break he built his own replacement in 12 prompts. It worked perfectly for him — so well that people begged him to open-source it. As the developer of Plinky — another link-saving app — I’m watching this moment like a dinosaur looking up at the sky wondering about the impending meteor.

View on Threads

Now I know that not everyone will build their own app. My mother-in-law certainly won’t build her own Plinky-replacement and will happily keep supporting her son-in-law’s work. But for companies like Squarespace, reporters vibe-coding their own websites in just a few hours rather than paying $200/year ought to be a red-alert moment. This won’t affect every SaaS product — enterprises rely on SaaS tools for stability and dependability that you may not want to in-source — but AI will drastically chip away at many businesses.

I’ve written several posts about how on-demand software is already here and that people are already capable of building their own solutions even if not everyone knows it yet. More and more people are catching on, and tools like Claude Code are evolving into new modalities like Claude Cowork that let any knowledge worker access the power developers have had for most of 2025.

The changes from this shift will be drastic and will disrupt many professions and industries. How this plays out deserves deeper exploration, but one thing is clear: it will upend many SaaS businesses. It’s no longer a question of if, but when. Especially for companies that don’t adapt to this new reality.

The One Skill Siri Needs

Joe Fabisevich — Fri, 23 Jan 2026 12:00:00 GMT

There are once again rumors of another Siri revamp — something I’m strongly in favor of. In a world of ChatGPT, Claude, and Gemini, the current Siri experience feels like a fourth grader trying to defend a PhD dissertation.

I use AI for many things — as this blog is witness to. I write code with AI, research vacation plans, and automate menial tasks. Siri can’t do any of these — and I desperately want it to be a better tool for automation.

If you double tap your iPhone’s home bar, you’ll see a few quick actions that are dynamically displayed based on — waves hands — whatever Siri thinks you want to do. (For the record, I have never played a podcast in Apple’s Podcast app.) Sometimes there aren’t even three options because Siri can’t think of three ways to help you.

All I want is control over this experience. Let me write Skills that solve real problems I have. I want a Fix Spelling and Grammar skill that quickly cleans up my emails. I want a skill that answers questions about what I see on screen. I want a skill that summarizes podcasts to decide if they’re worth listening to. I want to do a lot of things — and many of them are hyper-specific to me. Since Apple loves AppIntents, maybe we can even throw these Skills into the framework and let developers expose them as Shortcuts.

Everyone will have a different set of skills they want to use — and that’s great! People should have flexibility and autonomy in how they interact with AI systems. It frustrates me that the only way to interact with AI at a system level on iOS and macOS is so tied to Siri — and Apple’s current lackluster vision for AI. It shouldn’t be so hard to automate a menial task on the most important computing device in my life.

The Democratization of AI

Joe Fabisevich — Wed, 21 Jan 2026 12:00:00 GMT

I feel like we don’t talk enough about how five years ago the only people doing interesting things with “AI” were researchers and big tech employees optimizing algorithms, and now everybody has powerful AI systems available to them on demand via an API or in practically every tool.
— Joe Fabisevich (@mergesort.me) January 15, 2026 at 4:17 PM

When I worked at Twitter, I worked across many teams and was involved in features across the platform. There was one thing I could never wrap my head around though — the AI¹ that powered the Home timeline. I could feel when the quality of my feed dropped or things felt worse, but it was all qualitative and I couldn’t explain why. I simply didn’t have the expertise to explain why, nor the skills to do anything about it.

Today you don’t have to understand neural nets and tensors to build something with AI. With just an API key, everyone has access to OpenAI and Anthropic’s models and can do amazing things with AI in a way that simply wasn’t possible five years ago. Heck, the barrier to entry is even lower if you consider more no-code interfaces like n8n, Make, and Zapier. Now you have to understand how to work with AI, but previously AI was this mystical domain that was accessible to practically nobody.

As I discussed in The Claude Code Moment, you don’t have to be an AI researcher anymore — you can play, experiment, and prompt your way to making something interesting. It no longer takes weeks of training a model to try something new, all you need is curiosity. You don’t have to tweak parameters or understand neural networks — you just update to the latest version of Claude or GPT-5 and see your results improve. Judging by how many people are building things with AI today versus a few years ago, the barrier to entry has dropped thousands-fold.

This shift from AI being accessible to a few people in labs to anyone on the planet is extraordinary. You no longer need a PhD or a job at Meta or Google to use powerful AI systems to build something valuable, unique, and meaningful. All you need is an internet connection, plus some curiosity, creativity, and critical thinking skills.

I have a core belief that people are ingenious. Given the tools to implement their ideas, there’s no telling what they’ll create. Democratizing access to AI isn’t just about lowering the barriers — it’s about unleashing human creativity at scale — and I find that beautiful and exciting.

We’re living through a historical moment, but we may not even recognize it as such because we’re in the middle of it. Five years ago, practically nobody would have predicted how exponentially AI would penetrate every corner of our lives — and it’s just as hard to predict what the landscape will look like five years from now. People talk about the ChatGPT moment or the more recent Claude Code moment as turning points — but only in hindsight because you must live through a moment to truly understand its impact. Right now, we’re living through a moment where AI has become accessible to everyone, and we’re only beginning to see what becomes possible.

Footnotes

Admittedly back then we called it machine learning or deep learning, but it was the bleeding edge of AI. ↩

The Claude Code Moment

Joe Fabisevich — Mon, 19 Jan 2026 12:00:00 GMT

For the last year I’ve been teaching people in Pursuit’s AI-Native. As I described in Build.ms: Making Technology Accessible To Everyone

I’ve been volunteering at Pursuit for 12 years — helping people from below the poverty line, with no prior background in tech, become software developers. 80% of them land jobs in tech making an average salary of $85,000/year. Former Uber drivers, janitors, and kindergarten teachers have learned technology skills to completely reshape their lives. I’ve had the great pleasure of watching hundreds of lives change right in front of my eyes, and it’s truly moving.

Given the poor job market for junior developers, the program shifted to an AI-focused approach last year. People who’ve never heard of AI are building real software and learning how to build real products in just 9 months. They put in hundreds of hours learning to build with AI, develop products, market them, and everything else you’d need to build a small business. They do this with guidance from dedicated teachers and volunteers who transform people into builders incredibly quickly.

These are incredibly dedicated people learning everything they need to thrive in an AI-centric world. They saw the opportunity a year ago and decided to jump in before most people had even heard of Claude Code.

As I wrote in Claude Cowork

Since the release of Claude Code, software developers have been living in the future. As Simon Willison puts it, developers have had access to general purpose agents for the last 11 months.

But Claude Code is finally having its moment with non-technical people who are realizing they don’t need to be technical to use it to write code. Many had assumed it would be intimidating or require a coding background, but are now discovering that AI can guide them through the parts where they’d normally get stuck.

The Hard Fork podcast asked listeners to share how they’re using Claude Code — specifically regular people, not developers. (It starts at 36:07 in the episode if you want to listen.)

There were stories like:

A woman who loves to read built a service where people can sign up for personal book recommendations — just for fun!
A person whose business is selling wallpaper to interior decorators built her own wallpaper calculator. Decorators can now submit their wall sizes and get exactly how much wallpaper they need to purchase, plus a layout diagram. In her words: this was always a job I used to do by hand in Adobe Photoshop or InDesign, but now clients can do it themselves and save time for us both.
A man who runs a CNC milling business built agents that generate leads for jobs in his local area, and even created his own MCP server to interface with his CAD software.

He also wrote a personal message to the podcast hosts:

I really want people in my demographic to understand that this isn’t “I asked ChatGPT to write an email or to generate an image that has the correct spelling.” This is different to me, I built my own business infrastructure from scratch with an AI pair programmer, despite having zero formal training and a high school education.

This is exactly what I’ve been seeing at Pursuit for the last year. People who learn to use agentic tools like Claude Code become more empowered, self-sufficient, and gain newfound autonomy to make what they need — without the technical background that was previously required.

The skill of commanding an agentic system to build something meaningful has little to do with writing code — all it requires is clarity of thought, creativity, and critical thinking skills.

This is wonderful for non-technical people — the power to create software has become dramatically more accessible. And for developers, this is worth paying attention to. People are crossing into technical domains without waiting for permission or credentials now that they can build solutions to their own problems. If you’ve considered writing code your moat, it’s worth reconsidering how quickly that’s going to change across a wide swath of domains.

When I was starting my career, it was common to see people list Microsoft Word, Excel, and PowerPoint on their resume. Today, everyone assumes you can use those (or their Google equivalents) if you’re applying for a knowledge work job.

The ability to use AI well will become the same — something your employer assumes you know how to do. Not everyone will be equally skilled at it, the same way some people are wizards with a spreadsheet while others use it as a glorified table.

That’s why I teach AI workshops — because I genuinely believe this is a key skill for the future of work — and I’ve helped unlock something in hundreds of people. And that’s why if you haven’t tried Claude Code yet — or its less technical sibling Claude Cowork — this is your moment.

Gemini × Foundation Models

Joe Fabisevich — Mon, 12 Jan 2026 12:00:00 GMT

After careful evaluation, we determined that Google’s technology provides the most capable foundation for Apple Foundation Models and we’re excited about the innovative new experiences it will unlock for our users.

— Apple picks Google’s Gemini to run AI-powered Siri coming this year

If this reported news is true, it seems like an unambiguous upgrade for Siri users on iOS, macOS, and anywhere else Siri runs. I have a BigMe HiBreak Pro Android e-ink tablet, and even on relatively constrained hardware the experience of using Gemini and Gemini Live is drastically better than Siri.

This announcement provides more questions than answers though — questions that matter a lot to me.

If this model runs purely on device, then that’s great news. Gemini’s local models are terrific, and better than whatever Apple is doing today with Qwen models in their FoundationModels framework today.

If this runs in the cloud, then I have more questions. I care deeply about my privacy, so I abstain from using Gemini for anything private. By that I mean I won’t ask Gemini any health questions, discuss anything personally identifiable, and if I do use it for code it’s only for my open source projects.

I’ve drawn the line there because Google unlike OpenAI and Anthropic provides no way for consumers to opt out of having their data used for model training purposes. I simply do not want that, and will not use a Gemini-powered Siri if those promises are not there.

Also, will Apple continue to train their own models in the cloud? If so, does this give them time to catch up? Or is it just a wasteful effort because as their current capital expenditure shows they put very little effort into that effort.

Either way I’m curious to see how this affects Apple’s FoundationModels frameworks. The framework provides a level of abstraction so developers have to care very little about the underlying models. The results obviously matter, and there are particulars that matter like whether a model is local or remote — but ultimately this is a generic set of APIs that you could easily slot a new model into.

These are just the first questions I had, and it all depends on the details. My real hope is that Apple respects their stated values in a world of AI, and I expect to have more answers soon — and more questions stemming from those answers.

Claude Cowork

Joe Fabisevich — Mon, 12 Jan 2026 12:00:00 GMT

Since the release of Claude Code, software developers have been living in the future. As Simon Willison puts it, developers have had access to general purpose agents for the last 11 months.

Claude Code is, with hindsight, poorly named. It’s not purely a coding tool: it’s a tool for general computer automation. Anything you can achieve by typing commands into a computer is something that can now be automated by Claude Code. It’s best described as a general agent.

— Simon Willison

That brings us to today, with Anthropic announcing a new product called Claude Cowork.

When we released Claude Code, we expected developers to use it for coding. They did—and then quickly began using it for almost everything else. This prompted us to build Cowork: a simpler way for anyone—not just developers—to work with Claude in the very same way. Cowork is available today as a research preview for Claude Max subscribers on our macOS app, and we will improve it rapidly from here.

— Claude Cowork Research Preview

To me this is so clearly the immediate¹ future of how knowledge work will be done. I live close to the bleeding edge of AI, and it becomes apparent every time I talk to someone who isn’t immersed in the latest AI developments. As Arvind Narayanan and Sayash Kapoor explain “AI has not yet diffused through society”.

Thus, the speed of diffusion is inherently limited by the speed at which not only individuals, but also organizations and institutions, can adapt to technology. This is a trend that we have also seen for past general-purpose technologies: Diffusion occurs over decades, not years.

— AI As A Normal Technology

Developers like myself are fretting about how our entire way of working is shifting from right under us — as we type less code and do more. But fields like product management, design, and marketing are not far behind.

Claude Cowork is Claude Code for everything else — and for everyone else. And it’s far from the last tool to shake the ground beneath us.

Footnotes

I say immediate because things are changing so fast that who knows what work looks like in 10 years. ↩

The Economics of AI (Part I)

Joe Fabisevich — Wed, 07 Jan 2026 12:00:00 GMT

I’ve mostly been in the camp of AI is cool and great for big companies but we’re a way’s away from people losing jobs because of AI. I’m a lot less confident about that after playing with ChatGPT for two days. The most insane part is the pace of innovation over the last year.
— ✨ Joe Fabisevich ✨ (@mergesort) December 4, 2022

This is a tweet of mine from five days after ChatGPT was released. It’s now been three years, and I remain confident that AI will touch and reshape everything about our digital world. But in 2026, our digital world is tightly bound to our reality — it’s not some separate space we can cordon off.

While economists debate the impact of AI on labor today, we can see cracks in the foundation forming. People cannot (or don’t want to) fathom the social contract of labor and capital changing, but it’s already starting. There’s no promise it will follow the same rules of capitalism we’re used to — the fundamentals will change over the next few years. I don’t know how much, but I know the system will not make the same promises.

I have many thoughts on this, so I’ve titled this “The Economics of AI (Part I)”. Consider it an introductory post for a subject I’ll be revisiting often as this change transforms around us.

Today, I want to show you an example of how AI is beginning to divorce value from capital.

This is a comment from the maintainer of Tailwind CSS, one of the most popular libraries in web development. Tailwind is what makes websites look good — and what AI systems like Claude and ChatGPT almost always turn to Tailwind by default. Until recently, more popularity translated to more value, and more value meant more opportunity to acquire capital. But people creating value are screaming out to say that this is no longer true.

But the reality is that 75% of the people on our engineering team lost their jobs here yesterday because of the brutal impact AI has had on our business. And every second I spend trying to do fun free things for the community like this is a second I’m not spending trying to turn the business around and make sure the people who are still here are getting their paychecks every month.

Traffic to our docs is down about 40% from early 2023 despite Tailwind being more popular than ever. The docs are the only way people find out about our commercial products, and without customers we can’t afford to maintain the framework. I really want to figure out a way to offer LLM-optimized docs that don’t make that situation even worse (again we literally had to lay off 75% of the team yesterday), but I can’t prioritize it right now unfortunately, and I’m nervous to offer them without solving that problem first.

…

This feature is so that people can build MORE things with Tailwind in a FASTER and more EFFICIENT capacity. @mtsears4 Tailwind is growing faster than it ever has and is bigger than it ever has been, and our revenue is down close to 80%. Right now there’s just no correlation between making Tailwind easier to use and making development of the framework more sustainable. I need to fix that before making Tailwind easier to use benefits anyone, because if I can’t fix that this project is going to become unmaintained abandonware when there is no one left employed to work on it. I appreciate the sentiment and agree in spirit, it’s just more complicated than that in reality right now.

— Adam Wathan on GitHub

To pull out the most important part.

Right now there’s just no correlation between making Tailwind easier to use and making development of the framework more sustainable.

This is the contract breaking. We don’t yet know what shape it will take, but we can see it happening in real time. Not just in software development, but across many industries.

Build.ms: Making Technology Accessible To Everyone

Joe Fabisevich — Tue, 06 Jan 2026 12:00:00 GMT

Build.ms exists to make technology accessible to everyone.

The technological landscape is moving faster than ever. Even professional developers, designers, and product managers are struggling to keep up with every new advancement. (And I’m not just talking about AI.) All the noise makes it hard to filter out what’s important, and what you can ignore.

And people have busy lives. There’s work to do, families to raise, friends to see, and hobbies to pursue. You shouldn’t have to spend all your time keeping up with the daily flood of news to understand how technology is reshaping the world around you.

Build.ms has always been a space for technical writing to share lessons about engineering, product development, design, marketing, AI, and anything you need to build a modern business. But I’m reshaping it around a clearer purpose: making technology accessible to everyone.

This isn’t a new passion — I’ve been living this mission for over a decade, but I now have the clarity to make it my primary goal.

I’ve broken complicated subjects down into simple step-by-step processes so you can learn by doing. I’ve demonstrated new ways of working that are emerging. I’ve given talks that teach new ways to think about technology. Each of these is designed to bridge the gap: to give beginners a way in while offering experts new clarity.

That’s what you’ll find here going forward: more frequent posts that break down complex subjects into something you can understand and use immediately.

I’ve been volunteering at Pursuit for 12 years — helping people from below the poverty line, with no prior background in tech, become software developers. 80% of them land jobs in tech making an average salary of $85,000/year. Former Uber drivers, janitors, and kindergarten teachers have learned technology skills to completely reshape their lives. I’ve had the great pleasure of watching hundreds of lives change right in front of my eyes, and it’s truly moving.

Given the poor job market for junior developers, the program shifted to an AI-focused approach last year. People who’ve never heard of AI are building real software and learning how to build real products in just 9 months. They put in hundreds of hours learning to build with AI, develop products, market them, and everything else you’d need to build a small business. They do this with guidance from dedicated teachers and volunteers who transform people into builders incredibly quickly.

Volunteers like me spend hours every week filling in the gaps, and we hear how valuable it is. But right now, those lessons are only available when I share an insight on Bluesky, answer a question in the communities I’m a part of, or teach a hands-on workshop. The knowledge is there, but it’s not accessible to everyone who needs it.

That’s not enough. This information needs to be free and accessible — to everyone.

Here’s what I’ve learned from a decade of teaching: The people who thrive aren’t the ones who know the most. The people who thrive are the ones who know how and what to learn, how to adapt to new information, and how to think critically and creatively. There are a million places to learn about a specific tool or technology, but without the right mental models — taught in an accessible way — most people never figure out how to use those tools effectively.

That’s my mission for Build.ms 2.0. It’s a subtle shift from giving you everything you need to build a modern business, to sharing what matters most in a fast-moving technical world.

I want people to have the knowledge they need, and to do something good with it. Whether that’s making your life a little easier, helping the people around you, or paying it forward — it all starts with information. I hope I can help you with that, and I’d love for you to follow along with me.

Email Newsletter: build.ms/newsletter

Bluesky: bsky.app/profile/mergesort.me

Mastodon: macaw.social/@mergesort

Threads: threads.com/mergesort

LinkedIn: linkedin.com/in/devjoe

RSS: build.ms/feed.xml

AI (Without the Hype)

Joe Fabisevich — Wed, 24 Dec 2025 12:00:00 GMT

It’s a Christmas surprise! My AI (Without the Hype) talk from NSSpain is now available for everyone to watch.

This talk is wide-ranging and covers a lot of ground. I start by showing you a day in the life of using AI, discuss the fundamentals of how AI systems work, and then share ways to shape the way you work with AI to get great results. Whether you’re a beginner or an expert, a developer or a designer, or just someone who wants to learn more advanced ways of thinking about AI — there’s something for everyone.

I’m not saying you should ignore your family on Christmas Eve, but if you’re looking to learn about a lot about AI once the mice are no longer stirring about — I think you’ll really enjoy my talk.

Here’s a direct link
Better yet, you can save it to my app Plinky, and watch it later.
And here’s the full transcript below. It was pulled from YouTube and cleaned up with Claude Code, but I did skim it over to make a few minor edits and didn’t notice anything that misquoted me.

Introduction

Daniel Steinberg: I know I talk about how old I am a lot, but one of the reasons is people ask me why I don’t retire. And the reason I don’t retire is because of this. I mean, most of my friends are elsewhere.

Daniel Steinberg: So, I know I don’t remember names, but I really appreciate talking to people. And on the bus ride up from Madrid to Logroño, which is quite a bus ride, Joe said, “Hey, mind if I sit up here? We chat?” And it’s a great way to meet somebody that you only kind of know online. And people online, he’s much nicer in person. And I’ll tell you that he’s an indie iOS developer. You might know him from his app Plinky. He also teaches an AI workshop because that’s what everyone does these days. He’s going to talk to you about AI without the hype. Please welcome Joe.

Who Am I?

Thank you so much for having me here at NSSpain. It’s truly an honor to be here at this wonderful conference with so many of my favorite iOS developers. As you can guess, I’m here to talk to you about AI. But first, I’d like to tell you a little bit about who I am.

I’m an indie developer and I spend my days working on an app called Plinky. It’s the easiest way to save links for later, available on the App Store, and people really seem to like it. I’ve worked at every size company from a startup of two to internet success stories like Time Hop and Bitly. Most recently, I spent four years helping build the health client team at Twitter when it was Twitter, with a focus on improving misinformation and abuse at a global scale. I’m an open source maintainer and a writer, and these days I’m also a teacher.

I help people of all backgrounds, technical and non-technical, learn all about AI, as we’ll be doing here today. I love teaching people about this technology that’s emerging in real time. So, I work with individuals and teams alike to develop highly personalized hands-on workshops.

What I Love About Code

A simple and reusable abstraction tickles my brain, as does the personal fulfillment of solving a really difficult challenge. Code on its own is interesting, but I also love using code to build products that people love.

Don’t get me wrong, as an indie, I have to do design, marketing, sales, customer support, and of course, build my product. I love doing each of these things a little less than I love to code. Some, a lot less, actually.

But what I love most is making a real connection with another person through the software that I build. I feel so lucky that I get to build personal, playful productivity apps that make people happy. I’m always moved when a person reaches out to tell me, and that’s what drives me to do all the things that I don’t necessarily want to do. These are the roles that I take on to enable me to keep doing what I love most.

And that’s why I’m going to be talking to you today about how to use AI for your job as a software developer to do more of the things that you love most and less of the things that you don’t.

What We’ll Cover

We’ll start by talking about where AI is today and how I use AI in my day-to-day life.

Then we’ll talk about the technology behind AI and why AI tools work the way that they do. This will help explain why AI will continue to improve and diffuse across the industry, reshaping the way that we all work. Most importantly though, we’ll discuss the techniques that are required for successfully working with AI to accomplish your goals. There’s a lot that AI can do today and plenty that it can’t. I’m not here to convince you that it’s a magical tool that can do anything and everything. And that’s why I have this disclaimer.

A Disclaimer

As I mentioned, this talk is about AI, and people have a lot of feelings about AI — understandably so. Because I help people learn about AI, I hear all of these feelings all of the time. Some people think that AI can’t do very much and that it’s just a lying hallucination machine. Others worship at the altar of Sam Altman and think that we’re building a digital god.

Much like everything in life, I believe the answer is somewhere in the middle. There are many moral, societal, and security concerns to be had about AI — there are so many of them — and I genuinely wish that we were thinking deeply when having those discussions. The field is changing very quickly, so a few of the things that I present won’t be the only approach or the only solution.

I personally use AI a lot, and I’ll walk you through how it’s been a multiplier for my productivity. While I get a lot of utility out of AI, I definitely do not delegate all of my thinking to it. What remains most important as a software developer and as a person is your ability to think critically and to adapt to new technologies. That’s why I want to ask that for the next 30 minutes, you put aside your preconceived notions about AI, regardless of what they might be. And then I’d love for you to keep an open mind to the ideas that I present. In 31 minutes, you can believe whatever you like. I promise.

A Day in My Life with AI

I want to start by walking you through a regular day in my life, specifically the ways that I use AI. I start most mornings with a 15-minute bike ride up and down a quiet street where I live in New York City.

Sometimes I listen to a podcast. Sometimes I enjoy the sounds of the city. But lately, I’ve been opening ChatGPT’s voice mode and simply saying, “Teach me something new.”

Learning with AI

It’s like having an encyclopedia on demand. If I don’t know something, I just ask. If I find something interesting, I dive deeper down the rabbit hole. And of course, if I’m skeptical about something, I follow through and get more clarity. LLMs are like lossy encyclopedias. The more factual information there is about something in the training data, the more accurate you can expect an LLM to be. There’s a lot of highly sourced information about bioluminescence. So, I feel pretty good about the validity of what I’ve learned.

You can learn about almost anything. If it’s available on the internet, you can probably learn about it. It could be science, it could be history, or it can even be code. Lately, my bike rides have been filled with question after question about recent Swift evolution proposals. I’m not looking for an easy substitute for learning. Building a deep understanding requires practice and hard work. Instead, I’m using a new approach to break down a dense subject by asking the questions that I need answers to.

Building Tools on Demand

As I’m walking home from my bike ride, I have an idea. I get back to working on my NSSpain talk and I use AI to build this slide. Every slide in this talk with a chat bubble was made with a little tool that I built in a Claude artifact. The chat bubbles were created to be an exact replica of ChatGPT but with my talk’s color scheme. It was so simple that I built it with the prompts that you see on screen in less than 5 minutes. I didn’t have to write any code. I just had to describe my problem and give that to Claude.

Artifacts are accessible via the web, so you can go play with mine or even create your own based on it.

Now, is this chat bubble generator my life’s work? Of course not. It’s just a simple tool. But humans are tool builders. Being able to build tools on demand with AI is what makes AI so empowering to a software developer.

This XKCD comic about automation used to be a joke, but now it’s our reality. Rather than sitting in Keynote all day manipulating shapes until they look just right, I can now automate the process of creating a piece of software. Three prompts and five minutes later, I had exactly what I needed. No code and no thinking required to create a usable and reusable piece of software. Many problems are harder to describe than this, but sometimes it’s actually this easy to describe and build something that you need. The cost of making throwaway software that helps you accomplish a specific task is now almost zero.

Natural Language API Testing

Take a look at these two APIs and tell me which one you like more. In the spirit of automation, halfway through a curl request to test Plinky’s API, I realized I’m sick and tired of writing curl requests. I could use a GUI tool designed for API requests like Paw or Postman. But it would be even better to have a personalized tool. What if I could simply type “create tag NSSpain” and AI would create the correct curl request for me?

I think about how I can do this and I have a brilliant idea. I open up Codex, which is OpenAI’s CLI tool similar to Claude Code. First I ask Codex to read through the code for Plinky’s API layer to understand all of the endpoints that I have. Codex generates an OpenAPI spec from my code. So now we have a formal document that describes all of our endpoints and all of our parameters. Then Codex builds a Python script called plinky-api which also uses Codex to translate my natural language request into the correct API call. The script works by using GPT to analyze my command line input and reads through the OpenAPI spec to determine which routes I’m most likely trying to call.

Then we get this: now when I run this command, it chooses the right endpoint and constructs a curl request to add a new tag with the name NSSpain. I can now test my server much faster without having to keep all of the API routes in my head.

If you have a ChatGPT subscription, Codex is included for free. This means that right now you can build any tool that transforms natural language into something meaningful. I came up with and built this idea in 15 minutes. Most of that time I was off doing something else while Codex was writing the code.

It did take me a couple of iterations to perfect, but that’s nothing compared to the time that I’ve saved since, let alone making my life a little less annoying.

Lunch Break

That was hard work. So, I pause to have lunch with my lovely, supportive wife. I tell her about my brilliant new invention, and she says, “That sounds nice.”

She’s not a developer, so she doesn’t get how insanely cool this was. But it’s also proof that I don’t spend all day talking to AI.

Design Assistance

It’s time to get back to work. So, I start on my iOS 26 redesign for Plinky. I’ve been adjusting Plinky’s color palette to feel more modern and to stand out in a world of stock system apps. I realized early on that liquid glass would look better on a creamy white or espresso brown background rather than a pure white, black, or gray like many apps use. The colors that I choose will be used everywhere across my brand. So, I need to be thoughtful with these color choices.

I know the look that I’m going for and I’ll know it when I see it, but I don’t want to spend all day endlessly trying out hex codes to get there.

So, once again, I turn to ChatGPT to act as a design assistant.

ChatGPT isn’t a designer and it’s not replacing my design process, but it’s a great way to try a lot of options quickly. So, I asked ChatGPT to generate five color choices. I try out all of these colors on my device and settle on a slightly different shade.

I consider ChatGPT’s suggestions a great head start. They are advice. They’re not requirements. But those suggestions help me not spend all day aimlessly trying to pick just the right color.

I asked it to generate the P3 variants of our new colors to really pop on an iPhone. This is the perfect task for a computer. It’s an algorithmic problem. So why should I spend my time trying to generate the right transformations manually?

Lastly, I realized that the purple that I use for reminders is a bit stale on this new cream background. I don’t even have to tell ChatGPT the colors in my palette. I just drop in my entire color palette as a file and ask ChatGPT to find some alternate shades of purple that won’t clash.

Web Development Made Easy

Now that I have these new colors, I have to go apply them to Plinky’s landing page. I open Cursor and I tell it to update the website’s background color. It does so asynchronously while I’m working on something else.

Every app needs a landing page. And it used to be that not being an expert in web technology would stand in your way. But now, building a web page as an iOS developer is no longer a challenge.

Previously, I would spend weeks overcoming my mediocre CSS skills to build the perfect landing page, which would never come out quite right. Now, the answer is three simple steps:

If you don’t know what technology to use, describe your problem to your favorite AI and talk through the trade-offs.
Pick the web development stack that seems best for you from that conversation. Share a bunch of website designs that you like.
Continue iterating with AI. Describe what you like about the design and what you don’t like and what it got wrong. Keep nudging it in the right direction. All in plain English or Spanish. Almost no HTML or CSS necessary.

And I’ll let you in on a secret step four: when it’s all done, a stupid trick that I absolutely cannot believe works is to have an LLM clean up after itself. We all know that Cursor probably wrote some subpar code and didn’t realize, but it can read its own code after the fact and identify what’s subpar. Simply say, “Go through the codebase to refactor, clean up, and improve the code that you just wrote.” And it does.

Git Recovery

If there’s one thing I believe about AI, it’s that AI lowers the barrier to entry for solving a problem. Few things have a higher barrier to entry than Git. I’ve been using Git for 15 years now, and I can use Git pretty well, but I still struggle with complex multi-stage problems like this.

In my redesign, I’ve accidentally overridden my previous theme with our new theme. I wanted the old theme to be accessible to users as a setting. Restoring this theme is very doable, but it’s tedious. It’s error-prone, and it’ll probably take me about 15 to 20 minutes to get right. Once again, I can simply describe the problem, the context, and have Claude Code fix my screw-up.

There’s a big shift that occurs in how you work when you only need to explain the problems rather than type out the solutions. Instead of memorizing or looking up arcane git incantations, I can work at a higher level of abstraction and get better results.

Scaling Challenges

While Claude Code is saving me from my git mistakes in one tab, I open up another instance of Claude Code. I need to think through the last phases of a feature that I’ve been working on for a few months. Plinky is going to start letting users import their links from other apps like Pocket or Instapaper.

Building an indie app means I store data in Postgres well, but scaling is a new challenge to me. I do know the things that I need to know, but that doesn’t mean I have a lot of experience doing them. I’ll probably make a bunch of mistakes along the way, and I find when that’s the case, often what I need is another set of eyes and someone to talk to.

Rather than asking Claude to write my code, I describe the concern that I have. I worry that Plinky won’t be able to scale to meet the needs of users who have tens or hundreds of thousands of links. This is an example where as a developer, I know the problems that can arise, but I may not know how to prevent those problems. I have Claude read over the code for my feature and provide an assessment. It makes recommendations and I understand almost all of them. I’m not afraid to ask questions and get recommendations about what I don’t understand because I want to learn how to build scalable systems.

These are good suggestions. So, I learn more about monitoring to make sure that I can catch and fix errors as quickly as possible. Agentic tools like Claude Code are great for helping get me up to speed on new APIs, new libraries, and new subjects entirely. This is how I spend the remainder of my day, learning the tools and technologies that will make me a better developer and help me build a better product.

That was a lot of work. So I wind down by playing with my ridiculous cat who is also not artificial intelligence.

Understanding AI Fundamentals

Good news, we’re finally done talking about me. I’ve just shown you some of the ways that I use AI on a day-to-day basis, but I barely mentioned writing code. What I did mention were plenty of important parts about being a professional software developer. I can assure you that in the hands of a skilled developer, writing code is what AI does best. To understand why, we need to break AI down into its fundamental parts. We want to build production software beyond vibe coding. And to do so, we need to understand the fundamentals of AI.

Where AI Lives Today

AI is everywhere these days. Some of those are places where people look for AI, like in ChatGPT. But you can also find AI in places where people don’t necessarily want it, like at the top of Google search results.

There are three main modalities for how software developers interact with AI: chat (like the aptly named ChatGPT), IDEs (like Cursor or VS Code), and agentic coding tools such as Claude Code, Gemini CLI, or Codex. As you’ve seen, all these can play a meaningful role in a developer’s workflow.

ChatGPT Is Not a Chatbot

So I’m going to make a bold claim. From the first time that you use ChatGPT, you’re being lied to.

What’s confusing about the name ChatGPT is that it wasn’t made for chatting. Instead, I like to think of ChatGPT as the world’s best report generator. ChatGPT synthesizes the inputs that people provide it and transforms that into tangible outputs.

This is where large language models shine. They are language transformers, whether that language is English, Spanish, or Swift. Being a skilled communicator places you ahead of most other people using ChatGPT.

Well-articulated inputs lead to higher quality outputs. Otherwise, it’s a lot like the expression “garbage in, garbage out.” I use the term “outputs” rather than “text” because you don’t always want text back. As you’ve seen, we can have ChatGPT generate text, files, or most valuably, software.

I have a simple rule: don’t talk to ChatGPT the way you talk to your bestie. Talk to ChatGPT the way you talk to a coworker who you want to get help from. That approach will more easily tap into an LLM’s ability to reason about text and transform it into something valuable.

Can You Write Code Better Than AI?

The state-of-the-art in AI coding changes seemingly every month. So, I want to ask you about your experiences. Raise your hand if you think that you can write code better than AI.

Okay, good challenge. That seems to be about 70% of the audience. Correct me if I’m wrong, but the problem is you’re all wrong.

On the one hand, none of you should be raising your hands, but on the other hand, all of you should be raising your hands. The question is incomplete. What does it mean to write better software than someone else? Is it following patterns and best practices? Is it writing performant code? Is it inventing novel approaches? Or is it solving the problems that users have? Of course, the answer is all of the above depending on the context.

A claim I’m willing to make is that I bet on a greenfield project, AI can generate high-quality production code faster than you. And I bet it can do it in any language — ones you’ve probably never even tried, some you may not have even heard of. And you may say, “Well, I’m not working on a greenfield project.” And you’d be right. That’s not how developers spend most of their time, but it does happen sometimes. As I demonstrated earlier with my natural language curl tool, I think we’re going to be building a lot more software on demand in the future. But I also use LLMs in a large codebase all the time. I know they can deliver positive results that make me more productive. And yet I still will assert that sometimes an LLM will do the stupidest possible thing imaginable.

A Poll on Agentic Tools

So let’s take another poll. Right now Claude Code is the coding tool that people love most, but it won’t necessarily be forever. Feel free to substitute OpenAI Codex or Google’s Gemini whenever I mention Claude Code. I’m going to ask a series of questions. So this time raise your hand and keep it up until the answer is no.

Have you used Claude Code, Gemini, or Codex?

Okay, remember keep it up. Seems to be almost 100% of the audience. I’m pretty sure of that.

Have you used Claude Code for your main way of working for at least one week?

Hands go down.

Have you sat and worked on a prompt for at least 30 minutes?

More hands down.

How about an hour?

Have you set up any advanced features like slash commands, sub-agents, or custom output styles?

Have you used an LLM in concert with Claude to guide and review Claude’s work? I’m looking at one person who had his hand up still.

Okay, so that’s almost none of you. And the number of hands keeps going down, which makes me think that many of you are not using a tool like Claude Code to its fullest. And that’s not a judgment. It’s actually a positive. It tells me that there’s still a lot of untapped potential to improve your agentic coding workflows.

If I came on stage and showed you some new exciting feature in the latest version of Swift, you’d probably start ignoring my talk and go try that feature out immediately. I’m not saying to go ignore my talk, but do adopt the same mindset when it comes to trying out new AI features early and often.

Why LLMs Do Dumb Things

I’m going to make one more bold claim. Large language models are stupid.

Why do LLMs do dumb things? The answer is simple. LLMs have no mental model. They have no sense of coherence. They’re just a computer program trained to provide the next word in a sequence based on the previous word in that sequence. The word that they provide is based on what they’ve seen in their training process, which itself is imperfect.

This is not thinking. This is a smarter form of guessing. But if LLMs are so dumb, then why am I up here telling you that they can write production-ready code?

LLMs Are Just One Piece

LLMs are just one piece of a complete AI system like Claude Code or Cursor or ChatGPT. They’re the part that we talk about most because they’re truly innovative and they’re very new and shiny. But any meaningful AI system that you interact with is more than an LLM. LLMs generate text, but AI systems add memory, planning, reasoning, and guardrails to give that text context, structure, direction, and purpose. These additional layers provide the foundations for mental models that are missing from an LLM alone.

These more complete AI systems have a name that you’ve probably heard everywhere. They’re called agents. The term “agent” is a bit of a buzzword, but it’s not just a buzzword. It’s a design pattern.

The Agent Pattern

Think about what you do when approaching a problem: you ask for context. Too little and you can’t form a clear mental model. Too much and you drown in details, pushing out what actually matters. Striking the right balance is just as important for us as it is for agentic systems.

Then we have tools. You write your code in an IDE. This is your tool. But that IDE is built upon fundamental primitives. Your IDE is made with a UI framework, AppKit, the Swift compiler, the C compiler under that, all the way down to the operating system, the kernel, and the hardware input pipeline that turns your key presses into code.

Coding agents use Unix tools like ls to list files, grep to search through code, cat to read files, and echo to write them. And then at a higher level, they also call on abstract tools like web search, a code interpreter, or even specialized systems like another large language model to generate and refactor code. This tool usage is what separates an LLM from an agent. The same way that advanced tool usage separates humans from animals.

Setting the Right Goal

Setting the right goal for an agent is the single most important thing that you can do. The better that you define the goal, the better your results will be. The more explicit you are about what an agent should or shouldn’t do, the higher the odds that an agent will succeed at the task in the way that you envision success.

Think about when you’ve been handed a design that left out key details. You only discover the gaps while coding, which means rework, frustration, and wasted time. But if those gaps are caught early, the wrong thing doesn’t get built at all. Vague or incomplete requirements always means more work later on. Whether you’re delegating work to a teammate or to an agent, clarity upfront saves you from surprises down the road.

Putting this all together: given a success criteria to achieve, the right context, and a bunch of tools, agents will run in a loop until they solve the problem that they’ve been told to solve. Agents don’t work like us and we shouldn’t expect them to. They don’t reason with a real mental model. They brute force their way to answers. But surprisingly, brute force works remarkably well.

Why Everyone Is Building Agents

With clear goals and the right tools, an agent can tackle problems that once required bespoke and hard-to-build algorithms — all without just typing out a solution.

Thinking even bigger: this is why everyone is rushing to build agents and why you as a developer have an edge. You can think systematically and wire apps together in ways that others simply cannot.

The Anatomy of a Plan

Now that we have an understanding of the fundamentals of agentic systems, we’re ready to finally start coding. Well, not writing code — working with an agentic system that will write code for us.

Working with an agent is all about planning. In my experience, this is the hardest part to teach. People think and work so differently. So rather than a singular prescriptive solution, I want to share a framework for thinking: the anatomy of a plan.

Let’s build a hypothetical plan for a hypothetical weather app. The app already shows people the weather based on their location. And now we want to add a new feature that alerts users when a rain shower is expected.

Working with AI every day for almost 3 years has helped me define a successful plan by these four principles: context, description, success criteria, and additional considerations.

Context Is Everything

As you can see from this tweet, context is everything. Context is a story of how you got here and where you want to go. Imagine you’re telling a coworker that you need help building this alert feature. What do they need to know before we even begin crafting a solution?

To provide good context, we want to share everything that’s relevant to the problem that we’re solving. To do so, we need to answer these four questions:

What does our app already do?
Why are we building this feature?
Who is the user?
What are future considerations we should know ahead of time?

Breaking Down the Problem

As we start to gather context for our new alert feature, I realize the scope is too big. What we actually need to do is break down the problem into a subset of smaller problems. Building rain alerts actually requires multiple work streams, not just a single linear path:

We’ll need to register for push notifications in the app.
To do that, the server needs to build infrastructure for sending push notifications.
We’ll need server-side business logic to generate dynamic copy for push notifications based on the actual weather.

We can continue going deeper. Previously, the user would simply open the app and the server would make an API call to retrieve the latest weather as needed. Now, we’ll have to rebuild parts of our server to always poll for new data so we can send timely push notifications.

Countless more considerations will come up. This is our context. The context we share will continue to grow as we better define the feature.

Assembling Context

Our job is to assemble as much context as we can to solve our problems today and in the future. Nothing is ever going to be as simple as telling an agentic system, “Build a new feature.” We’re going to have to work hard to communicate the complexity. This is true of agentic systems as it is for people.

If you’re talking to a coworker with a lot of background knowledge, they’ll understand nuance and subtleties by filling in details from their experience. But if you’re trying to explain the problem to someone new at your company, you often have to provide additional context and be very explicit.

That’s exactly what working with an LLM is like. They’re very smart, but they have a fresh perspective. So, you need to fill the gaps in for them. And that is why we build up context for an agentic system. Otherwise, AI systems will make a bunch of assumptions that we then have to fix later after it’s made plenty of mistakes.

Sources of Context

We should pull in context from every source we have. Your codebase is an obvious starting point. If you want an agent to write good code, the number one factor that determines success is the existing quality of your codebase. This is the opposite of how most people approach starting off experimentation with LLMs. They try to vibe code something and are blown away by how much progress they’ve made so quickly. We’re here trying to build production-grade software. So that’s not going to work for us.

Your results will be much better if your codebase is well modularized with small files, readable functions, and consistent patterns. All of the things that we’ve been saying are important for years. But no codebase is perfect. So if you don’t have that yet, use an agent to help get you there one task at a time.

Besides your code, there are many other sources for context:

Jira tickets help break down the work that needs to be done, which is helpful to AI systems.
Notion and Google Docs should be added as well to provide meaningful product documentation.
Designs from Figma provide visual direction.
Sharing API docs is the best way to have an agent build a feature to spec.
You can even include screenshots of other apps that you want to emulate and guide an agent to build something similar as a starting point.

As we continue, we’ll generate markdown docs that contain more valuable information: context about our system’s architecture, how features work, specific design choices that we’ve made, and anything that explains an important decision.

We don’t even have to write this documentation. We can tell an agent to read through our working sessions and write helpful documentation for us. Then all we have to do is review and edit the results afterwards.

Writing Your Description

Context and description go hand in hand. Your description is ostensibly your prompt plus context. And our description will be a plain English articulation of your problem statement, while context is everything that leads to the problem statement.

Most people prompt like this: “Build a rain alert feature.”

But you need to continue being detailed, describing your problem from every perspective involved. Very detailed.

I actually have a lot more to say, but it’s very hard to fit an hour’s worth of prompt writing on a slide. Now that we have a bunch of context, the problem we describe will make a lot more sense to an agent. If we say that we’re building a rain alert feature that notifies a user 15 minutes before rain starts in their location, the agent will understand why we’re building this feature and how we should approach the problem.

Over time, you get used to writing long introductory prompts and going back and forth with your agent to develop a plan. But if you have trouble with that, just ask ChatGPT to help you develop a better prompt. Don’t just ask your agent for what to do. Give it a starting point and have it ask you interrogative questions to get you there.

Parallel Workflows

As you develop more advanced workflows, you can even start building multiple features at once. For our app, I can build the server’s notification architecture in one instance of Claude Code while building the client-side code in another tab. And in a third tab, I’m asking Cursor to provide step-by-step instructions for generating APNS certificates so I can finally start sending those push notifications.

This is why planning is so powerful. It’s worth the trade-off of spending an hour to document all this when that means an agentic system can do a whole day’s worth of work or even a week’s worth of coding with only minimal involvement from me.

Defining Success

We’ve described the problem that we want to solve, but what does “done” look like? You have to be specific with your goals. Otherwise, you’ll end up with unexpected results.

We’ve established that we want a user to receive a notification 15 minutes before it starts to rain with location-appropriate accuracy. Success is not just sending the notification. Success has multiple criteria:

Timeliness: It’s important that a user receives this notification 15 minutes before it starts to rain. Not 5 minutes, not 2 hours. Our success metric is properly alerting users 15 minutes before it starts to rain.

Accuracy: If it’s going to rain for 15 minutes, we have to tell the user. If we don’t tell the user and they get rained on, then we haven’t succeeded.

Annoyance: A sufficiently smart AI would think, “Well, if I just send a user a push notification every 15 minutes, the user will never get rained on.” And that’s why it’s important to tell an agent what’s right and what is wrong.

Once we set a success criteria, the agent will do whatever it can to succeed. It’s crucial to ensure that an agent knows what success looks like. That’s how we make non-deterministic systems more deterministic.

Edge Cases

And lastly, we have edge cases — because edge cases are always the last thing a developer thinks about.

I’m on stage right now. So, this is my location, but people move around. I could be on a bike. I could be on a train. I could be in a car. Or I could be walking at different speeds. Maybe I haven’t opened the app since yesterday and I’m in a completely different city.

Now, we can mitigate this edge case by making the server always send a silent push notification to synchronize a user’s location before deciding to send a rain alert notification.

This is exactly the kind of detail that we need to mention in our plan if we want an agent to build production-grade software. There are going to be countless other edge cases like this, which is true in our usual product development process as well.

Planning Is Thinking

The process that I’ve described isn’t just writing and documentation. It’s thinking.

If you began building a large production system without thinking ahead, I wouldn’t expect you to see good results. And if you don’t think ahead before asking an agentic system to complete a task, you shouldn’t expect good results either.

There are unending techniques, styles, and preferences for the process of constructing your plan. Lately, I’ve been working with Claude in a GitHub issue, so it has access to my code and the ability to generate draft pull requests while we’re planning. This is a nice trick that helps make sure that we’re similarly aligned about how the code should work since ultimately the code is what matters. But these practices change all the time, so you should experiment and find what works for you.

One Last Tip

One last tip for planning is to add a phrase like this to the end of your initial planning prompt:

“Before we begin, ask me any clarifying questions you need to understand the problem fully.”

This will actually help you work with AI to catch a lot of assumptions that you’ve made. This will help make sure that you don’t miss any important context that an agent needs. You’ll find that there’s at least one thing you didn’t consider every time.

One More Thing

Speaking of one more thing, I have just one more thing to share.

I want to go back to earlier in the talk where I told you that agents don’t solve problems like we do.

Hummingbirds can see colors that humans aren’t even able to imagine.
Elephants communicate through the ground by producing and detecting seismic rumbles.
Orb weaver spiders capture sound with their silk, using their webs to hear.
Sharks can feel electric fields, and sea turtles cross oceans using the Earth’s magnetic field for navigation.

Why am I up here rattling off a bunch of animal facts after talking about AI for 30 minutes? Because the way that we perceive the world is grounded in our experiences. Humans have five senses, and it’s impossible for us to imagine what others would feel like. A shark probably doesn’t know that other animals don’t sense electric fields because it’s all the shark has ever known.

What if we begin to question our assumptions for how software should be built? Maybe it doesn’t have to be the way it is just because it’s the only way that we’ve ever known.

Final Thoughts

I can’t teach you everything about AI. I don’t know everything about AI. Instead, I came here for two reasons:

I wanted to share the foundations of how AI systems work.
I wanted to ask you to imagine that maybe your experience building software with AI isn’t complete. Neither is mine.

Behaviors of AI systems are so emergent that we’re all kind of figuring things out as we go. And while I don’t want you to abandon everything you know about software, I think it’s important to have epistemic humility — humility about a technology that’s constantly changing and that none of us had ever used three years ago.

Thank you all so much for listening.

Q&A

Q: If I had to choose an animal, I’m a dinosaur. And every once in a while when I’m stuck writing something, I’ll pull out paper and a pencil. I’m not afraid of AI, but I like writing code. What do you say to someone like me that maybe my code isn’t as pretty as I can get Claude to write, but I like what I do?

A: Yeah. I mean, I think you should write software how you want to write software. I’m not actually here to force anyone into this. I just want to show that there is definitely more possibility in the world than we imagine. And there’s this quote — telling someone that a love song already exists doesn’t stop them from writing another love song. Same thing for programming.

Q: Telling someone that a to-do list exists doesn’t mean they won’t build another one.

A: Exactly.

Q: Someone wants to know how do you judge if the context that you give an agent is working for or against the task? Is it just vibes or how do you know?

A: It’s all vibes, man. No. I think that it’s just like any skill. Someone asked me a couple days ago, how am I supposed to teach a junior developer how to code when they have AI? And it’s the same thing. They didn’t know how to code. They went through the same mistakes that a senior developer probably has already forgotten that they too at one point didn’t know everything. And so you learn by iterating and trial and error and practicing and then you see what techniques work and what don’t work — in the same way that when you were starting to program, you had to try things out. Go to Stack Overflow, posts on Google, then YouTube came around. There’s infinite ways to learn. There’s infinite ways to continue getting better at this skill.

Q: How does someone become a senior developer without doing the things that we used to do as junior developers?

A: Yeah, I actually think that you still need to do them. That’s kind of the reason that I said in this talk this is a process of learning. This is not a substitute for learning. This is a different modality for learning. It’s a new way to learn. It’s a new way to build things. And it’s true that there are some people who use AI and they start to forget things. But if you want to be the best version of yourself that you can be, then it’s an imperative for you to continue to learn. And I use AI in that way to help me continue learning. But there are definitely people who use AI to stop thinking. And I don’t think that’s a good thing.

Codex vs. Claude Code (Today)

Joe Fabisevich — Mon, 22 Dec 2025 12:00:00 GMT

Every programmer has their favorite language. Some prefer Python, while others swear by TypeScript¹. Many teams build their apps on Postgres, while others use MySQL. These choices are often flame-war bait for programmers with strong opinions, but most of these decisions are centered around pragmatism, priorities, and tradeoffs. They’re reflections of different working styles, rather than moral statements.

All of this applies to the choices people make when they decide whether to use Claude Code or Codex.

Before we continue, I need to make a disclaimer: This post is about the Claude Code and Codex, on December 22, 2025. Everything in AI changes so fast that I have almost no expectations about the validity of these statements in a year, or probably even 3-6 months from now.

I also must emphasize that both Codex and Claude Code are already superhuman developers. I don’t say that solely based on the quality of outputs from Opus 4.5 and codex-5.2-high, but in how they work. Codex and Claude Code sometimes arrive at a solution in ways that almost feel alien to how we think about coding, much like AlphaGo’s Move 37.

I keep up with every AI tool I can so I can teach AI to anyone and everyone, but it’s becoming more of a necessity for all software developers. When it comes to coding I’ve mostly settled into using Codex for “coding”, and I put coding in quotes because the process is very different than writing code by hand. I spend anywhere from 30 minutes to two hours writing prompts and generating context for Codex, then the task runs for 15-20 minutes while I context-switch to something else entirely. When I come back, I’ve got somewhere between a day and a week’s worth of code waiting for me.

But I still use Claude Code a lot. The coding environment they’ve built is exceptional. Much like Peter Steinberger describes Claude Code as his computer, I delegate all sorts of tasks to Claude Code. I’ll use Skills to transcribe videos to mp3s, generate a dark mode color palette for my website, or quickly prototype an idea from a blog post.

Why People Love Codex

When I need something done and done right, I call on Codex. The reason is simple: the results are unbelievably good for me. And that’s because of how I work. By investing time into context engineering and context plumbing, I’m able to stay hands-off-keyboard for much longer.

Having long-running tasks might sound like a drawback, but it’s just a different way to work. When I send Codex off to do a task that takes 20 minutes, I switch my focus entirely. I’ll open Figma to do some design work, write my newsletter, or open another terminal and prompt Codex with some server work while the first terminal is chugging along on some client work.

I’d rather have everything take longer and generate results that I don’t have to fix than be involved in the process steering AI to success. That’s the working style that suits me best. OpenAI’s latest models deliver better results than the latest Claude models with less need to be in the loop. So while that remains true, I’ll mostly stick with Codex.

Why People Love Claude Code

And that brings me to my theory of why many engineers prefer Claude Code. Claude makes you feel more like you’re doing engineering work — and surprise — engineers love engineering work. Source: I’m an engineer.

Claude has a lot of knobs to turn. You’ve got your CLAUDE.md, Skills, Agents, MCP, slash commands, and so much more. Codex has similar features, but it tends to produce high-quality results out of the box. Claude on the other hand works best when you finely tune those knobs, and Anthropic really encourages you to do so in their developer relations and marketing.

This is a perfect match for engineers who love configuring their environments. I can’t tell you how many full days of my life I’ve lost trying out new Xcode features or researching VS Code extensions that in practice make me 0.05% more productive.

Personally — and I do emphasize this is a personal decision — I‘d rather write a well-spec’d plan and go do something else for 15 minutes. Claude’s Plan Mode is exceptional, and that‘s why so many people fall in love with Claude once they try it.²

Many engineers would rather be hands-on and guide the software development process step by step — which is very understandable when you consider what flow state looks like. Claude will ask you a ton of questions and interrupt itself more frequently to make sure it’s not heading in the wrong direction. That really makes you feel like you’re doing heads-down engineering work.

So Should I Use Codex or Claude?

I think back to coworkers I’ve had over the years, and their varying preferences. Some people couldn’t start coding until they had a checklist of everything they needed to do to solve a problem. Others would dive right in and prototype to learn about the space they would be operating in.

The tools we use to build are moving fast and can be hard to keep up with, but we’ve been blessed with a plethora of choices. The good news is that there is no wrong choice when it comes to AI. That’s why I don’t dismiss people who live in Claude Code, even though I personally prefer Codex.

The tool you choose should match how you work, not the other way around. If you use Claude, I’d suggest trying Codex for a week to see if maybe you’re a Codex person and didn’t know it. And if you use Codex, I’d recommend trying Claude Code for a week to see if maybe you’re more of a Claude person than you thought.

Maybe you’ll discover your current approach isn’t the best fit for you. Maybe you won’t. But I’m confident you’ll find that every AI tool has its strengths and weaknesses, and the only way to discover what they are is by using them.

Footnotes

As you may know I’m a Swift guy, with a sprinkling of TypeScript for anything that touches the web. ↩
I will argue that Claude’s Plan Mode is basically what working with Codex is like all the time, and one of the main reasons I prefer using Codex. ↩

Building Software From Blog Posts

Joe Fabisevich — Mon, 15 Dec 2025 12:00:00 GMT

Did you know Claude Code has a completely customizable status line?

I was browsing Anthropic’s documentation when I stumbled on a genuinely useful feature. At first I thought the status line would just display some preconfigured information, but it turns out the status line is fully customizable — you can make it show whatever you want.

When I discovered that, I knew exactly what I wanted to build. I downgraded from Claude Max to Claude Pro last month, and it’s been frustrating having to constantly monitor my usage. I’ve developed a tic — typing /usage as often as I used to press Ctrl + S in Microsoft Word. What if I could just see my usage stats at a glance?

Building Your Status Line In One Prompt

Well, that’s exactly what I built. Or more accurately, what Claude built for me. It only took about 10 minutes, and here’s the prompt you can use to build it even faster:

I would like to build a status line that shows the usage quotas for my current and weekly session limits. This blog post (build.ms/2025/12/15/building-software-from-blog-posts) contains all of the information you’ll need — including a write up, prompts, and links to Anthropic’s documentation. More importantly, it contains a script you can use as your foundation.

And that’s it. One prompt, and you’re done. Want to customize it further? Just tell Claude how. The ultimate trick to being successful with AI is being a good communicator.

There’s an even bigger lesson in this prompt: If there’s something you want Claude, Codex, or Gemini to do — you can point them to blog posts or documentation and let them do the research. Have AI do the research for you, and then it will know how to do the work for you.

Want to see how I built this from scratch? Keep reading. (And if you’re a hands-on learner who wants to level up your AI skills by building your own ideas, this is exactly the kind of technique I teach in my AI workshops.)

Building This From Scratch

I’ll be honest — I didn’t write any of this code myself. I just asked Claude to do it. Here’s the prompt I started with:

Can you update our status line to display the total context used and how much of our session/weekly quota we’ve used? Here is some documentation for configuring your status line. https://code.claude.com/docs/en/statusline

And it worked! Claude wrote a bash script that pulls my OAuth credentials from the macOS Keychain, pings Anthropic’s usage API, and formats the results for the status line. I looked over the code and could immediately see that it was solid.

Then I asked Claude to document everything — the script, how it works, installation steps, troubleshooting tips, and anything else that was relevant. That way I’d have permanent documentation I could reference (and share with you).

That was as simple as asking Claude:

Let’s assume I’m sharing how to do this with a coworker. Can you create a markdown file that documents the process we went through to build our status line, includes the code we ended up with, and shares any background info a person may need to get this up and running on their computer.

Expand to see Claude's technical writeup

# Customizing Claude Code's Statusline For Usage Quotas

A custom statusline script for Claude Code that displays real-time session and weekly usage quotas by fetching data from Anthropic's OAuth API.

## statusline-command.sh

```bash
#!/bin/bash

# Status line script for Claude Code
# Displays: Session quota, Weekly quota
# With comprehensive error handling for authentication issues

# Read JSON input from stdin
input=$(cat)

# Initialize variables
session_pct=""
weekly_pct=""

# Fetch credentials from macOS Keychain
CREDS=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null)

# Validate credentials exist
if [ -z "$CREDS" ] || [ "$CREDS" = "null" ]; then
    echo "OAuth token not found — run /login to authenticate"
    exit 0
fi

# Extract access token from JSON
ACCESS_TOKEN=$(echo "$CREDS" | jq -r '.claudeAiOauth.accessToken' 2>/dev/null)

# Validate token extraction succeeded
if [ -z "$ACCESS_TOKEN" ] || [ "$ACCESS_TOKEN" = "null" ]; then
    echo "Invalid token format — run /login to re-authenticate"
    exit 0
fi

# Pre-check: Verify token has required OAuth scope
SCOPES=$(echo "$CREDS" | jq -r '.claudeAiOauth.scopes[]' 2>/dev/null)
if [[ ! "$SCOPES" =~ "user:profile" ]]; then
    echo "Token missing required user:profile scope — run /login to update permissions"
    exit 0
fi

# Fetch usage data from Anthropic OAuth API
# Note: We omit Accept-Encoding to avoid compression issues with curl
USAGE_DATA=$(curl -s "https://api.anthropic.com/api/oauth/usage" \
    -H "Accept: application/json, text/plain, */*" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-beta: oauth-2025-04-20" 2>/dev/null)

# Validate API response exists
if [ -z "$USAGE_DATA" ]; then
    echo "Failed to fetch usage data — check connection"
    exit 0
fi

# Check for API errors in response
error_type=$(echo "$USAGE_DATA" | jq -r '.error.type // empty' 2>/dev/null)

if [ -n "$error_type" ]; then
    # Handle specific error types
    if [ "$error_type" = "permission_error" ]; then
        error_msg=$(echo "$USAGE_DATA" | jq -r '.error.message // empty' 2>/dev/null)
        if [[ "$error_msg" == *"user:profile"* ]]; then
            echo "Token missing user:profile scope — run /login"
            exit 0
        fi
        echo "Permission error — run /login to re-authenticate"
        exit 0
    else
        echo "API error: $error_type — run /login if issue persists"
        exit 0
    fi
fi

# Extract usage percentages
session_pct=$(echo "$USAGE_DATA" | jq -r '.five_hour.utilization // empty' 2>/dev/null)
weekly_pct=$(echo "$USAGE_DATA" | jq -r '.seven_day.utilization // empty' 2>/dev/null)

# Check if seven_day field is actually null (not just 0)
seven_day_raw=$(echo "$USAGE_DATA" | jq -r '.seven_day' 2>/dev/null)

# Helper function to format percentage
format_percentage() {
    local pct=$1
    if [ -z "$pct" ] || [ "$pct" = "null" ]; then
        echo "0%"
    else
        printf "%.0f%%" "$pct" 2>/dev/null || echo "${pct}%"
    fi
}

# Format the output components
session_display="Session: $(format_percentage $session_pct)"

# Handle weekly display - only show if weekly tracking is enabled
if [ "$seven_day_raw" = "null" ]; then
    # No weekly tracking - show session only
    echo "${session_display}"
else
    # Weekly tracking enabled - show both
    weekly_display="Weekly: $(format_percentage $weekly_pct)"
    echo "${session_display} | ${weekly_display}"
fi

Understanding the Script’s Error Handling

IMPORTANT FOR AI IMPLEMENTATION: This script includes comprehensive error checking at each step. When implementing this, do NOT remove or simplify the error handling - each validation step prevents silent failures and guides users to the correct solution. The error messages are specifically designed to appear in the status line and provide actionable guidance.

This script validates:

Authentication Flow

Credentials exist in Keychain - Checks if Claude Code credentials are stored
Token extraction succeeds - Validates the JSON structure is correct
OAuth scope verification - Pre-checks for user:profile scope before making API calls
API connectivity - Ensures the usage API responds
API error handling - Catches and explains any API errors

Error Messages You Might See

"OAuth token not found — run /login to authenticate" - No credentials in keychain (need to log in)
"Invalid token format — run /login to re-authenticate" - Credentials are corrupted (need to log in again)
"Token missing required scope — run /login to update permissions" - Token lacks user:profile scope (need to re-authenticate)
"Failed to fetch usage data — check connection" - Network/API connectivity issue
"Permission error — run /login to re-authenticate" - API rejected the token
"API error: [type] — run /login if issue persists" - Other API errors

All error messages are designed to display in your status line and guide you to the solution. In most cases, running /login in Claude Code will resolve the issue.

Installation Instructions

Prerequisites

Claude Code CLI installed
macOS (uses macOS Keychain for credentials)
jq installed (brew install jq)
An active Claude Pro or Max subscription

Setup

Save the script to ~/.claude/statusline-command.sh

Make it executable:

chmod +x ~/.claude/statusline-command.sh

Add this configuration to your ~/.claude/settings.json:
```
{
  "statusLine": {
    "type": "command",
    "command": "/Users/YOUR_USERNAME/.claude/statusline-command.sh"
  }
}
```
Replace YOUR_USERNAME with your actual username, or use the full path to the script.
Test the script immediately to catch any issues:
```
echo '{}' | ~/.claude/statusline-command.sh
```
Expected outputs:
- ✅ Success with weekly limits: Session: X% | Weekly: Y% (with real percentages)
- ✅ Success without weekly limits: Session: X% (weekly metrics not enabled for your account)
- ⚠️ Need login: OAuth token not found — run /login to authenticate
- ⚠️ Need scope: Token missing required scope — run /login to update permissions
Note: If you only see Session: X% without weekly metrics, this is normal—your account doesn’t have weekly limits enabled. The script automatically adapts to show only the metrics available for your account.

If you see any error message, follow the instructions in the message before proceeding.
Verify your OAuth token has the required permissions (see next section).

Verifying OAuth Token Permissions

IMPORTANT: The usage API requires the user:profile OAuth scope. This scope was added recently, so if you’ve been using Claude Code for a while, your token probably doesn’t have it yet. You’ll need to re-authenticate once to get it.

Here’s how to check and fix this:

Check if your token has the right scope

Run this command in your terminal:

CREDS=$(security find-generic-password -s "Claude Code-credentials" -w)
echo "$CREDS" | jq -r '.claudeAiOauth.scopes'

You should see output like:

["user:inference", "user:profile"]

If you only see ["user:inference"] (missing user:profile), you need to re-authenticate.

Re-authenticate to get the required scope

If your token is missing the user:profile scope, run these commands in Claude Code:

/logout
/login

This only needs to be done once. After re-authenticating, your token will have both scopes and the status line will work automatically.

Why this happens

OAuth tokens cannot gain new scopes through refresh — this is by design in the OAuth 2.0 specification. When Anthropic added the user:profile scope, existing tokens didn’t automatically receive it. Re-authenticating creates a fresh token with all current scopes.

What It Displays

The statusline shows:

Session: 5-hour rolling window usage percentage
Weekly: 7-day usage percentage

Example output:

Session: 39% | Weekly: 27%

How It Works

The script:

Reads Claude Code’s JSON input via stdin (required by statusline API)
Fetches your OAuth credentials from macOS Keychain
Calls Anthropic’s OAuth usage API (https://api.anthropic.com/api/oauth/usage)
Extracts and displays the quota percentages

The usage data matches exactly what Claude Code’s /usage command shows.

API Details

The script calls:

https://api.anthropic.com/api/oauth/usage

With headers:

Authorization: Bearer <access_token>
anthropic-beta: oauth-2025-04-20

Response includes:

{
  "five_hour": {
    "utilization": 39.0,
    "resets_at": "2025-12-12T20:59:59.707736+00:00"
  },
  "seven_day": {
    "utilization": 27.0,
    "resets_at": "2025-12-16T03:59:59.707754+00:00"
  }
}

Troubleshooting

Status Line Shows an Error Message

The script now provides specific error messages to help diagnose issues. Here’s what each means and how to fix it:

“OAuth token not found — run /login to authenticate”

Cause: Claude Code credentials aren’t in your keychain. Fix: Run /login in Claude Code to authenticate.

”Invalid token format — run /login to re-authenticate”

Cause: Keychain credentials are corrupted or in an unexpected format. Fix: Run /logout then /login in Claude Code to create fresh credentials.

”Token missing required scope — run /login to update permissions”

Cause: Your OAuth token lacks the user:profile scope (likely an older token). Fix: Run /logout then /login in Claude Code to get a token with all required scopes.

”Failed to fetch usage data — check connection”

Cause: Network connectivity issue or API is temporarily unavailable. Fix: Check your internet connection. If the problem persists, try /logout and /login.

”Permission error — run /login to re-authenticate”

Cause: The API rejected your token (might be expired or revoked). Fix: Run /logout then /login in Claude Code.

”API error: [type] — run /login if issue persists”

Cause: An unexpected API error occurred. Fix: Note the error type and try /logout then /login. If it continues, this might indicate an API issue.

Script Works But Shows “Session: 0% | Weekly: 0%”

This shouldn’t happen with the updated script (it now shows error messages instead), but if you see this:

Verify you ran the test command: echo '{}' | ~/.claude/statusline-command.sh
Check that you’re using the complete script from this blog post
Ensure jq is installed: which jq should return a path

Status Line Only Shows Session Usage (No Weekly Percentage)

If your status line shows only Session: X% without a weekly percentage, it means the API is returning null for the seven_day field. This is expected behavior for some accounts, not a bug in the script.

Why This Happens

The https://api.anthropic.com/api/oauth/usage endpoint is an undocumented internal API used by Claude Code. When the seven_day field returns null, it means weekly limits are not enabled for your account.

Not all Claude Code users have weekly usage limits. Anthropic introduced these limits in August 2025 for specific usage patterns, but they are not universally applied to all subscription tiers or users. If your account doesn’t have weekly limits, the API will return null for the seven_day field, and the script will only display your session (five-hour) usage.

What You Can Do

Verify your account status:

CREDS=$(security find-generic-password -s "Claude Code-credentials" -w)
ACCESS_TOKEN=$(echo "$CREDS" | jq -r '.claudeAiOauth.accessToken')
curl -s "https://api.anthropic.com/api/oauth/usage" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-beta: oauth-2025-04-20" | jq '.seven_day'

If this returns null, weekly limits are not enabled for your account. The script will automatically show only session usage.

Use the /usage command for official limits:

Claude Code’s built-in /usage command provides comprehensive usage information for your account, including any limits that apply.

Important Notes

The script automatically adapts: it shows Session: X% | Weekly: Y% when weekly tracking is available, or just Session: X% when it’s not
Session (five-hour) tracking works for all accounts
If you only see session usage, it means your account doesn’t have weekly limits enabled—this is normal for many users
There’s an open GitHub issue requesting that Claude Code expose usage quota information directly through the statusLine JSON input, which would eliminate the need for external API calls

Check Keychain credentials

security find-generic-password -s "Claude Code-credentials" -w

This should return a JSON object with OAuth credentials.

Test the API call manually

CREDS=$(security find-generic-password -s "Claude Code-credentials" -w)
ACCESS_TOKEN=$(echo "$CREDS" | jq -r '.claudeAiOauth.accessToken')
curl -s "https://api.anthropic.com/api/oauth/usage" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-beta: oauth-2025-04-20" | jq .

Resources

Claude Code Status Line Documentation
GitHub - levz0r/claude-code-statusline - Similar implementation
GitHub - ryoppippi/ccusage - Usage analysis tool

Platform-Specific Notes

macOS

This script uses the security command to access credentials from the macOS Keychain. The script provided above works out of the box on macOS.

Linux

On Linux, Claude Code stores credentials in ~/.claude/.credentials.json. To adapt this script for Linux, replace the credential retrieval section:

# Replace this macOS-specific line:
CREDS=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null)

# With this Linux-compatible line:
CREDS=$(cat ~/.claude/.credentials.json 2>/dev/null)

Windows

On Windows, credentials are stored in the Windows Credential Manager. You’ll need to adapt the credential retrieval using PowerShell or a Windows-compatible method. The exact implementation depends on your shell environment (PowerShell, WSL, Git Bash, etc.).

For WSL (Windows Subsystem for Linux), credentials may be in ~/.claude/.credentials.json similar to Linux.

</div>
</details>

---

Let's take a minute to talk through what happened here: I had a problem, I asked Claude to solve it, and then I asked Claude to document the solution so others could solve it too. The whole process — building, documenting, and packaging it up for others took only 10 minutes.

That's the power of AI-assisted development. Using tools this way is the future of knowledge work, which is why I [teach this](https://build.ms/ai) every chance I get. As I've [talked about many times](https://build.ms/2025/12/1/scribblenauts-for-software/), [you don't need to be a programmer](https://build.ms/2025/10/17/your-first-claude-skill/) to build useful tools anymore. All you have to do is be a good communicator — and just ask.

Scribblenauts For Software

Joe Fabisevich — Mon, 01 Dec 2025 12:00:00 GMT

I once had a girlfriend who loved the game Scribblenauts, and I loved watching her play it on her Nintendo DS. The premise seems simple: the main character Maxwell navigates through levels by solving puzzles. But there’s a twist.

Need to fly? Type “jetpack” and a jetpack appears. Need to write something? Ask for a pencil. The game has an extensive vocabulary and rewards creativity, so rather than typing “fire”, you might as well type “dragon” or “Cthulhu” to summon a fully formed monster with all its physical properties at your disposal.

I’ve mentioned the concept of on-demand software a handful of times, and expanded on it in my recent talk at NSSpain. For that talk, I wanted slides that looked identical to ChatGPT’s interface but with my talk’s color scheme.

I built exactly that in a Claude Artifact, and it took less than five minutes using these prompts. I didn’t write any code — I just described my problem and told Claude what I needed. That’s what I mean when I say Scribblenauts for Software.

Building Your First On-Demand Software

Is this chat bubble generator my life’s work? Of course not. It’s just a simple tool — but humans are tool builders. For a motivated developer, building the tools you need on-demand with the help of AI is empowering. Rather than sitting in Keynote all day manipulating shapes until they look just right, I automated the process by creating a piece of software.

Three prompts and five minutes later, I had exactly what I needed. No code, no thinking required — just a usable and reusable piece of software. Don’t like how it came out? Ask for something different. Don’t like it at all? Start over with a completely different direction, this time telling the AI exactly what you don’t want.

This XKCD comic about automation used to be funny because it was true. Spending hours to automate a five-minute task was absurd, but the timetable has changed. Now you can spend five minutes building something that would have previously taken a day, or an hour building something that would have taken a week.

Not every problem is this simple to describe, but sometimes it really is this easy. Today the cost of making throwaway software that helps you accomplish a specific task is practically zero.

Building More Complex On-Demand Software

I’ve spent the last few years bouncing between curl and tools like Paw or Postman to test Plinky’s API. I use curl when I need something quick and dirty, and a GUI tool when I want to save and reuse an endpoint.

But what if I had a personalized tool made just for Plinky? What if I could simply type Create tag build.ms and have AI create and execute the correct curl request for me? This is Scribblenauts for Software thinking.

I open up OpenAI’s Codex and ask it to read through my code for Plinky’s API layer to understand all of the endpoints I have.
I ask Codex to generate an OpenAPI spec from my code, so now I have a formal document that describes all my endpoints and parameters.
Codex builds a Python script called plinky-api, using GPT-5 to analyze my command line input and read through the OpenAPI spec to determine which route I’m most likely trying to call.

Now when I run plinky-api "create tag build.ms", Codex:

Chooses the right endpoint
Constructs a curl request to add a new tag named build.ms
Executes the curl request for me

I now have a personalized tool that tests my API. No fiddling with curl requests, finicky GUI tools, or keeping all of Plinky’s API routes in my head. I came up with and built this in 15 minutes, and most of that time I was off doing something else while Codex wrote the code. It took a couple of iterations to perfect, but that’s nothing compared to the time I’ve saved since — let alone making my life a little less annoying.

Scribblenauts for Software

We truly are at the beginning of an era of personalized on-demand software. Today, you can solve practically any problem by creating your own bespoke software. If you have a ChatGPT subscription, Codex is included for free, and Claude Code is included in Claude subscriptions. This means that right now, you can build any tool you want. This is Scribblenauts for Software, and it’s a big deal.

Today I’m using AI to build my own tools. Tomorrow developers will use AI to build games with interactions that feel dynamic and realtime.¹ Give it a decade and many entertainment experiences will be intermediated with AI to feel alive, even when they’re artificial in nature. When you can infuse everything with AI, suddenly everything becomes a canvas drawn from unlimited objects — much like Scribblenauts.

P.S. Want to learn how to build tools like this? I teach hands-on workshops that guide you through every step of the way.

Footnotes

I recommend this read about how a brilliant hacker used AI to replace the dialogue in Animal Crossing for GameCube with current events. ↩

The Past, Present, and Future of AI Workshops with @mergesort

Joe Fabisevich — Thu, 30 Oct 2025 12:00:00 GMT

The short version of this post is that:

I’m publicly launching the AI Workshops I’ve been running since April.
I’ve taught dozens of people (technical and non-technical) who swear by the results.
It would mean a lot if you’d check them out — and even better, sign up! (P.S. They’re a fantastic use of your company’s Learning & Development budget.)

But I also want to tell you how this all started, and why I believe I can help you learn something life-changing.

My First Workshop

On a crisp spring evening last April, my friend Jeremy came by my house after I’d made him a promise. He’d been telling me how AI was changing his life. He’d gotten deep into organizing everything he cared about across a myriad of Claude Projects. He had projects for his health, his finances, and so much more. Each one had complex instructions, contained contextually-relevant documents, and thoughtful prompts. He was clearly motivated to get useful results from AI.

So I asked him what I thought was a simple question: “Are you using Claude to code — even a little bit?”

He hadn’t. Jeremy is a PM who didn’t know how to code. But having worked closely with Jeremy at Twitter, I knew he was deeply technical. He understood the product and software development process better than most people, many software developers included.

I told him we could treat code as just a detail, and that I’d teach him how to use AI for coding. I wanted Jeremy to feel how powerful it is to build your own ideas, and I’m happy to say it worked.

To quote Jeremy a few months later:

Meant to mention that coding (via AI) has become my default activity apart from family time. My now wife has to tell me “don’t code today”. I’m so grateful I’ve found this new hobby.

That night turned out to be my first AI workshop.

It Starts With An Idea

I told Jeremy to bring an idea — one that he wanted to exist — and the two of us would build it together. I knew diving in was the best way forward. I could spend hours answering Jeremy’s questions, but most of the answers would materialize in real time if we just made something he cared about.

Jeremy described a meticulous process he has when eating out. He’s trying to eat as healthy as possible, so he:

Opens a Claude Project with his health goals, dietary restrictions, most recent bloodwork, and other relevant tests.
Drops in a PDF of the restaurant’s menu (or takes photos if there’s no PDF) and adds it to a new chat.
Asks which menu items he can eat and which ones to avoid for his health needs.

Jeremy wanted to automate this process. I thought the idea was interesting, and figured it would lend itself well to the two of us building a prototype.

But he wanted to take it a step further than his current workflow. Instead of dropping a menu into a Claude Project, Jeremy wanted to look up a restaurant like he would with Google Maps and have this health check happen automatically. Now this is thinking like a developer.

From Idea to App in 10 Steps

We started by setting up the Google Places API, so Jeremy could find restaurants by name.
I asked Jeremy to describe his idea in a Google Doc.
He wrote a couple of paragraphs with varying levels of detail — basically riffing.
I asked him, “if you handed this to a software developer, do you think they’d be able to build this app?”
He said no, and I agreed.
I showed him how to improve our prompt, and shared examples of great prompts that could serve as inspiration.
We began adding detail after detail after detail, until it was a full-blown PRD. Good thing Jeremy is a terrific product manager!
Once we had a spec, we let AI loose on the problem.
I still remember Jeremy’s face as AI began building his app. He was awestruck, watching his idea come to life right in front of him.
Jeremy spent the next couple of hours asking me whatever questions came to mind as we made progress. I answered them so I could help him learn — and keep him excited about this mind-opening experience.

Trust the Process (And Why It Works)

That’s still how I teach my workshops. I’ve since run dozens of them, which has allowed me to refine my technique. I love seeing a person’s face light up when they have a lightbulb moment, and my real goal is to have three or four of those moments every session. That’s when a person realizes they were this close to productively building software with AI this whole time.

All you need to know is what you don’t know — and that’s where I help best. There’s some technique involved, and some technical know-how, but I’ve found that what people need most is to learn the mental models for working with AI.

I fundamentally believe people are not as far from using AI effectively as they think. You may only be a few questions away from learning a life-changing skill, but figuring out what those questions are is the hard part.

If you ask Jeremy though, the reward is even higher than you can imagine when you don’t know what you’re missing out on. That may be true for you too.

AI Workshops with @mergesort

You’ll learn how to write prompts that actually work, turn ideas into apps, and most importantly — build the confidence to work effectively with AI on your own.

What I care most about in this world is helping people become the best version of themselves — however they envision that to be. That’s why I personalize every workshop to the attendee or team.

I know that real learning only happens when you meet someone where they are, rather than giving them slides to read or videos to watch and hoping they figure out what matters. I’ve always been a good teacher, but what I’ve discovered is that I’m quite good at doing this — teaching people a lot and inspiring them to do more in a short period of time.

If you don’t believe me, you can believe the people who have taken my workshops so far.

I’ve managed to run all of these workshops before launching publicly because word of mouth spread me so thin that I haven’t had time to launch publicly! I spend all my time teaching AI now — whether that’s running these workshops, helping non-technical people at a local non-profit (who are building real products despite no previous software experience), or on stage at conferences like NSSpain. My life for the last six months has been teaching AI (and building Plinky with the help of AI), and I’m only getting better at it.

Six Months of Teaching (And Building)

I’m not the only one building with AI.

Jeremy is building apps for himself, his family, and friends. He recently sent me one of his new apps, and I continue to be proud of what he’s done and how far he’s progressed.
My workshop attendees often write back within 24-48 hours to tell me they’ve built something they’ve been wanting for years — something they would never have made without AI doing the heavy work. (One attendee built an app his wife had wanted for four years in just a few hours — so I’m available for marriage counseling too.)
A team of three that I mentored at the non-profit have started a small B2B business despite having zero prior coding experience. They’ve built a real product that solves a real business pain point, and just made their first sale to an enterprise customer.

Whether you’re a designer, product manager, founder, or just someone with ideas — if you can describe what you want, you can build it. And the workshops work great for developers too; I love going deep and technical on how to work better with AI.

Now Let’s Talk About You

AI has the potential to be the most life-changing invention of our lifetime. The question I want you to ask yourself is: “How will it change your life?”

AI is becoming a foundational skill that everyone will need — like literacy or math. But we’re only at the beginning of this transition, and many people still struggle to get good results. They often believe AI simply can’t do certain things that I know it can, and I can show you how.

This is what I teach best: helping curious and creative people solve real problems with AI. I go beyond techniques to teach fundamentals and build your confidence to use AI every day in ways that matter. These skills scale from small tasks to large projects and work across every tool — from Cursor to Claude to ChatGPT — and they’ll work for whatever comes next too.

To be real for a moment — look, I know this reads like a sales pitch. But bring an idea and see for yourself how much you can learn in a short time by building it. I’m just a person who wants to see you be the best version of yourself, and I bet one conversation is all it takes to get you there.

Your First Claude (and ChatGPT) Skill

Joe Fabisevich — Fri, 17 Oct 2025 12:00:00 GMT

Note: Since I wrote this blog post ChatGPT has also adopted the Skills paradigm. This is further proof that Skills are becoming a standard way to create powerful and accessible automations, as you’ll see below.

Anthropic released a new feature yesterday called Skills. Skills are a simple way to build powerful automations without writing a single line of code. What makes Skills so interesting is that you don’t create software with programming and syntax, instead you describe your intent and a repeatable process you want to automate and Claude figures out how to make it happen.

Skills may sound similar to Claude’s Artifacts (and a few of Anthropic’s other offerings…), but they serve a different purpose. Artifacts help you build a tangible piece of software, but Skills help you do something. Skills turn a repetitive task into an on-demand utility that you can run anytime.

This provides two meaningful advantages:

Accessibility: Skills aren’t just for programmers, anyone can create or use a Skill. While Skills can be run in Claude Code, they stand out from more technical alternatives by working equally well in Claude on your phone or your computer.
Flexibility: Skills can include scripts, images, datasets, or any other supporting files you may need to solve a difficult problem.

This opens up a world of possibilities:

A project manager can build a Skill that aggregates updates from every project tracker across the company — automatically generating a personalized status report for their next meeting.
A marketer can create a Skill that applies brand guidelines to any public marketing document by injecting approved logos, fonts, and official assets.
A designer can build a Skill to lint a design, checking that it meets both the current WCAG accessibility standards and the upcoming APCA contrast standards.
A data analyst can build a Skill that cleans, normalizes, and reformats messy spreadsheets using real Python and Pandas code — transforming raw CSVs into polished summaries with a single prompt.
A software developer can build anything from an API schema validator that checks JSON payloads against stored schemas, to a benchmark profiler that visualizes performance regressions over time.
And a nerd like me can automate practically anything I want — without writing any code.

Your First Skill

The first Skill I created was a YouTube Audio Downloader. This came to mind immediately because it’s a task I automate often. I like to listen to talks from YouTube in my favorite podcast player, instead of having YouTube interrupt me with ads every ten minutes.

It was also a simple proof of concept that I could try before building something more powerful. It’s a problem I understand well, and this approach has the added benefit of working on my iPhone. The lack of a terminal on iOS means I can’t run tools like yt-dlp, but now I can use Claude to do it from anywhere.

A Naive Implementation

My first attempt was as straightforward as possible: I described exactly what I wanted in plain English.

---
name: youtube-audio-downloader
description: This skill downloads YouTube videos and transforms them into mp3s in one step.
---

# YouTube Audio Downloader

## Instructions

This package should use the yt-dlp Python package to download a YouTube video from a given URL, and then uses post-processing options to convert that video to an mp3. The end goal is for a user to have an mp3 file that they can drop into their favorite audio player.

## Examples

When the user asks for the audio from an mp3, you will invoke a command like this.

import yt_dlp
video_url = 'https://www.youtube.com/watch?v=example_video_id'

# Set options for downloading and converting to MP3
ydl_opts = {
    'format': 'bestaudio/best',  # Download the best audio quality available
    'extractaudio': True,         # Extract audio only
    'audioformat': 'mp3',         # Convert to mp3
    'outtmpl': '%(title)s.%(ext)s',  # Save the file with the video title
    'postprocessors': [{           # Define post-processing options
        'key': 'FFmpegExtractAudio',  # Use FFmpeg to extract audio
        'preferredcodec': 'mp3',       # Set the preferred codec to mp3
        'preferredquality': '192',      # Set the preferred quality (192 kbps)
    }],
}

# Create a YDL object and download the video
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download([video_url])

This code is one example, you should explore the other formats and prompt the user for their preferences if their intent is not obvious.

My first try worked surprisingly well. I didn’t go in with much strategy beyond trying things and seeing what happened. That’s something I love about AI — there’s no penalty for an experiment gone wrong, so you can try infinite approaches and throw away whatever doesn’t work.

Creating a Skill only takes a few steps:

Provide a name and description.
Add instructions that describe the problem you’re solving.
Share examples. I didn’t want to write much code, so I asked Claude to generate a short sample yt-dlp script someone might run.

This Skill worked well, but why stop at good when I knew it could be better?

A Better Approach

In Anthropic’s help docs for Skills, they mention the ability to add resources. A resource can be an image, a file, or a script.

Your Skill should live in a file called SKILL.md. If you create a resources directory, you can add any assets that your Skill might need to reference. And if you create a scripts folder, Claude gains the ability to invoke a Python or JavaScript interpreter with any package from NPM or PyPI. This is incredibly powerful! This means your skill can run and execute real code, transforming a simple text description into a full app.

Rather than writing this code myself, I pointed Claude at the documentation for Skills and at my SKILL.md, asking it to rewrite my Skill into a Skill with a script.

Based on this blog post (https://docs.claude.com/en/docs/agents-and-tools/agent-skills) and this skill Users/mergesort/.claude/skills/youtube-audio-downloader-skill SKILL.md, can you transform our plain-text instructions into a utility script?

Claude followed my request perfectly. It created a new download_audio.py in my scripts folder, and simplified my SKILL.md. Instead of embedding code directly in my SKILL.md, Claude referenced the new script and even added better usage examples than the ones I had provided.

---
name: youtube-audio-downloader
description: This skill downloads YouTube videos and transforms them into mp3s in one step.
---

# YouTube Audio Downloader

This skill downloads audio from YouTube videos (or other supported sites) and converts them to MP3 files.

## Instructions

Use the `scripts/download_audio.py` utility script to download and convert videos to MP3 format. The script uses yt-dlp to extract the best quality audio and convert it to MP3.

**Note:** yt-dlp supports many video platforms beyond YouTube, so this skill works with most video URLs the user provides.

## Usage

Execute the utility script with the video URL:

bash
python3 scripts/download_audio.py "VIDEO_URL"

### Options

- `-q, --quality KBPS`: Set audio quality in kbps (default: 192)
- `-o, --output TEMPLATE`: Set output filename template (default: `%(title)s.%(ext)s`)

### Examples

**Basic usage (192 kbps, video title as filename):**
bash
python3 scripts/download_audio.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

**Custom quality (320 kbps):**
bash
python3 scripts/download_audio.py -q 320 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"


**Custom output filename:**
bash
python3 scripts/download_audio.py -o "my_audio.%(ext)s" "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

## Behavior

- The script downloads the best available audio quality from the source
- Converts audio to MP3 format using FFmpeg
- Saves the file in the current working directory with the video title as the filename (by default)
- Provides clear success/error messages
- Exits with error code 1 if download fails

If the user's preferences are unclear (quality, output location, filename format), ask before downloading.

Going above and beyond what it was asked to do, Claude even listed the benefits of this approach for me:

Following the documentation’s approach, this transformation provides:

Token efficiency: Only the script’s output consumes tokens, not the code itself

Consistency: The same deterministic script runs every time

Maintainability: Script logic is in one place, not scattered across examples

Reusability: The script can be tested and improved independently

All of these benefits are useful, but what I appreciated most was that I didn’t have to write any code to get here. Pointing an AI at well-written documentation and having it update my existing work is a powerful technique that I turn to often, and expect will become even more common as these systems improve.

Publishing Your Skill

If you want to use a Skill on your computer, you can drop it into the .claude folder in your home directory or into your project’s .claude directory. But the real magic is making a Skill available in the Claude app on your phone or computer.

To make a Skill available everywhere, follow these steps:

Create a zip file that contains your SKILL.md, your resources folder, and your scripts folder.
Open Claude and go to Settings -> Capabilities.
Upload the zip file where it says Upload Skill.

Once you do that, your custom piece of software will be available anywhere and everywhere.

Skills vs. MCP

So what about MCPs?

MCPs are complex and mostly aimed at programmers. They connect an AI system to external APIs and resources in an agentic way — going beyond what REST can offer. Skills, on the other hand, are less of a contract and more of a task for the model to execute autonomously.

MCPs also tend to be token-inefficient, to the point where I often recommend avoiding them. That’s especially true when you’re working in an agentic coding environment like Claude Code, where it’s usually better to make Claude aware of an equivalent CLI tool in your CLAUDE.md so you don’t waste valuable space in your context window.

I don’t think MCPs are going away because they still play an important role — but they’re quickly falling out of favor because of their complexity, latency, and growing security concerns. Skills can’t fully replace an MCP (yet… I say because the AI space moves fast), but they’re already filling many of the same needs by formalizing a simpler way to run automated code within an agentic system.

Developing Your Skills

I’ve been saying for a while now that we’re at the beginning of an era of on-demand software.

Skills aren’t the first manifestation of that. There have been plenty of ideas like this before, even from Anthropic with MCPs, Artifacts, Subagents, and god knows what else. What’s novel about Skills is that they lower the barrier for people to create and run small pieces of software that do exactly what you need, when you need it.

We’re starting to see these ideas converge into more cohesive visions — ones that go beyond developers and software development. When anyone can create a Skill, anyone can improve one, share one, or build on top of one. Their simplicity makes them more accessible, and when technology becomes more accessible, we begin to see creativity flourish.

And so, there’s never been a better time to learn a new skill.

How I Used ChatGPT Over A Long Weekend

Joe Fabisevich — Wed, 01 Jan 2025 12:00:00 GMT

When I tell people how great ChatGPT is (or substitute your favorite AI tool like Claude), the question I hear most often is: “But how do you actually use it?” It’s a great question because, as I explained in this blog post, working with large language models (LLMs) isn’t always intuitive and takes some practice to master.

Rather than scrambling to come up with examples on the spot, I decided to document how I used ChatGPT over a four day weekend. While this list isn’t exhaustive or representative of every weekend, it’s a great starting point for anyone curious about what ChatGPT can do.

You don’t have to read through every single use case, you may want to skim the post and dive into the ones that strike your fancy. If you aren’t a developer, by all means, skip the coding section. If you don’t need health advice, then scroll past how I’ve used ChatGPT to diagnose my medical issues. There is a wide array of use cases discussed, and I’m sure at least one of these AI-assisted workflows can improve your life.

Coding

Solving multiple complex coding challenges

You’ll see the full results in Boutique 3.0, but I was thrilled with how ChatGPT’s o1 model helped me brainstorm, prototype, and build a feature inspired by Swift Data’s Relationships. This feature has been on my wish list for over a year, but I kept putting it off because of the complexity.

Using ChatGPT as a pairing partner, I developed about 10 potential APIs for this feature in under an hour, and ultimately found one that I loved. ChatGPT then built a first version of the implementation, which got me 90% of the way there, requiring only minimal tweaks to fully align with my goals and preferences.

I also turned to ChatGPT as a teaching aid to review and understand this pull request. This was a fix for a long-standing bug in Boutique, but I had a bit of a mental block when trying to understand how it resolved the issue. I asked ChatGPT to double-check my assumptions and explain what I was missing. Being a software developer is as much about understanding code as writing it, and having a tool to improve my comprehension has been invaluable.

Building a simple app

I’ve been dealing with a prolonged bout of tinnitus, and the only thing that seems to help is listening to specific nature sounds — like a mix of fire crackling and light rain. Unfortunately, the app I was using for this was buggy and frustrating to navigate. I realized I could build a better app in just 20-30 minutes with ChatGPT. So, I extracted the sounds from the app’s IPA file and let ChatGPT help me create a new, more functional app with a better interface. Did I absolutely need to build this? No. But it’s made my life a little easier during a tough time.

Sidenote: This is a perfect example of how software development is changing. The marginal cost of creating software has always been high, but with LLMs and the tools being built around them, it’s only getting lower. Developers should take note. Making bespoke apps on demand is already possible — and this kind of capability will continue to shape the future of the industry.

Writing SQL queries for me

I often need to analyze how people are using my app, Plinky, to better understand how I can build a product that truly helps them. To make informed, data-driven decisions, I needed to determine the ideal number of links users can save before encountering a paywall.

To find the right number, I decided to look at the average and median number of links users save in their first day, first week, and first month. Writing queries for this type of analysis can be tedious, especially with complex database schemas.

By providing ChatGPT with my database’s DDL (Data Definition Language), I gave it an accurate understanding of my database’s structure — without sharing any actual data. With that context, ChatGPT generated a useful SQL query in seconds, providing the insights I needed. What normally involves googling SQL syntax and some trial and error was effortless with ChatGPT.

Automating tedious tasks

Fixing annoyances with one-off Python scripts

There are small tasks that annoy the heck out of me, but these days, I often ask ChatGPT to write a script to do them for me. The last script I generated was a command line tool that allows me to pass in a list of simulators I would like to keep available in Xcode, and then have simctl delete all the other simulators for me.

This saved me time and hassle. Instead of scrolling through an endless list of unused simulators in Xcode (which get re-added after every update), I was able to quickly fix the problem without spending much time figuring out how to write the script myself. ChatGPT’s ability to generate functional code to solve tedious problems is something I’ll never get enough of.

Transforming colors in a color palette

While considering new color schemes for Plinky, I wanted to quickly prototype colors without having to spend too much time building out a full color palette. Below is the prompt I used to make this work.

I have four different shades of purple colors.

Light Mode Normal Contrast: #8E44AD

Dark Mode Normal Contrast: #9B59B6

Light Mode High Contrast: #AD68C9

Dark Mode High Contrast: #783A91

I’m trying to replace this color in my color palette with a new shade of blue. The color is #8ECAE6, and I would like to use that for the Light Mode Normal Contrast option. Can you create the other three colors applying the same transformations that we used for our shades of purple?

ChatGPT delivered exactly what I needed: four perfectly tinted shades of blue — #8ECAE6, #9BDFEF, #ADEEFF, #78C0CA — each with slight offsets applied for the respective color modes. It was much faster than if I had attempted to create a whole palette myself, which is important because now I was able to try out a bunch of color schemes and see if any of them fit my needs.

Double-checking my work

Verifying work I’ve done

As a small business owner, I file quarterly taxes, well, every quarter. It’s a tedious task, and the cost of making a mistake is high. Nowadays, after copying data between spreadsheets as I usually do, I paste both the original and updated spreadsheets into ChatGPT and ask it to compare them.

While I can’t guarantee ChatGPT catches everything, this highlights any differences or potential errors I might have missed. It has found mistakes before, and while I can’t guarantee it will always help, it’s still better than nothing. This quick check has become an important part of my workflow, giving me a little boost of confidence that I’m getting things right.

Writing better copy

I like to think I’m a pretty good writer, but I often struggle with microcopy. My penchant for illustrative language doesn’t translate very well to the concise, clear text needed in my apps — especially when it’s crucial to communicate information to users quickly.

This is where ChatGPT has been a huge help. I’ll upload a screenshot of a screen I’ve built with my best attempt at writing good copy, and ask how I can make the copy more concise and direct. It was particularly useful during my recent redesign of Plinky’s onboarding messages. With ChatGPT’s suggestions, I’ve been able to fine-tune the language across my app and deliver a better experience for users.

Research

Music Discovery

I have a pretty eclectic musical palate, and I’m always looking for new music to listen to. Apple Music and Spotify give you access to every artist, album, and song imaginable, but when I find something I like, what I want is more of that. Unfortunately, their discovery features aren’t great — you either browse endlessly or let an algorithm recommend music until something catches your ear.

This weekend, I was listening to Chad Hugo, and all I could think was, “Damn, this slaps.” I ended up having a whole conversation with ChatGPT about him, asking about who he’s worked with, his musical influences, and for more interesting things I should know about him. Then I asked: “Name five other artists I should check out if I like Chad Hugo.”

ChatGPT suggested Pharrell, Daft Punk, Timbaland, The Chemical Brothers, and Mark Ronson. I’ve listened to a bunch of music by three of those artists, and agreed they were spot-on for my taste. That gave me confidence to check out the other two, and led me to discover a bunch of new music I’m now excited to listen to.

Identifying a bird on my fire escape

My lil cat loves watching birds, and while she’s not the most successful hunter (the window hurts), she remains fascinated and convinced she’ll get them one day. I noticed a bird on my fire escape that definitely wasn’t a pigeon, and was curious about what bird had such a beautiful speckled chest. With just one photo ChatGPT was able to correctly identify the bird as a European Starling, which it turns out is a lot more common in New York City than I expected.

Note: I did a Google Image search to confirm that the bird was indeed a European Starling, but wouldn’t have known where to start if I hadn’t asked ChatGPT in the first place.

Answering menu questions

I was out at a restaurant, and the menu contained a handful of items I was unfamiliar with. I wanted to find out what they were and if they sounded good, so while I could have googled each item individually, instead I took a picture of the menu and asked ChatGPT about three dishes at once.

Asking about the causes of poor coordination

I was walking down the street when I had a random thought: what causes some people to have poor coordination? I decided to ask ChatGPT:

What causes a person to have poor coordination? Is it usually neurological, biomechanical, or something else entirely?”

The response was very insightful and sparked even more questions. ChatGPT explained various causes, including neurological issues, muscle imbalances, and even inner-ear problems. Each answer led to new questions, and before I knew it, I’d spent 10 minutes learning how about coordination works. ChatGPT turned a stray thought into an impromptu lesson — one of the things I truly love about using it.

Planning a few days in Colombia for an upcoming vacation

This is probably the most relatable item on the list. My wife and I are planning a vacation to Cartagena, and we didn’t know that much about the city. We wanted a trip that matched our vibe — something we’d enjoy by mixing together some highlights, beach time, and some off-the-beaten-path recommendations.

Using ChatGPT’s suggestions as a starting point, we put together a great itinerary in half the time it would normally take us. While I wouldn’t suggest planning an entire trip around ChatGPT’s recommendations, it’s an excellent tool for gathering ideas and must-see attractions quickly. Being able to combine popular spots with hidden gems made vacation planning much easier and more enjoyable.

Learning about Thomas Hardy

I started listening to an episode of Conversations with Tyler featuring Paula Byrne, a biographer who recently wrote a book about Thomas Hardy. While the conversation seemed fascinating, I realized I didn’t know nearly enough about Thomas Hardy to follow along well.

Rather than giving up on the episode, I provided ChatGPT a transcript of the episode and asked:

Can you read the transcript of this podcast, and teach me everything I would need to know about Thomas Hardy to understand what is being discussed?

ChatGPT gave me a comprehensive overview of Hardy’s life, works, and themes, which provided the context I needed to enjoy the rest of the episode. This was the first time I’d tried an idea like this, and it’s a technique I’ll definitely use again to learn about unfamiliar subjects.

Understanding the home loan process

My wife and I are looking into buying our first home, and to be honest, we don’t know much about where to start. There are so many steps and possible optimizations — it’s the kind of problem I’d normally love to develop expertise in, but I don’t have the time to explore right now. ChatGPT is great at breaking down big problems into simpler ones, so we decided to start there.

ChatGPT gave us a concise list that explained what financing options might be available to us, what paperwork we’d need, and a myriad of other steps involved. The best part was ChatGPT’s ability to answer follow-up questions when we didn’t fully understand certain steps, or advice we’d been given. By the end of the weekend, we felt much more confident and even scheduled a call with our bank. We’re still far from experts, but being able to ask questions and get thorough answers made the process far less intimidating.

Re-thinking my investment portfolio

With the end of the year approaching, I’ve had taxes and finances on my mind. I had a little money to invest, and while I’ve historically been pretty conservative, I wanted to explore other options. I knew I wanted to stick with index funds, but instead of defaulting to the same ones I usually choose, I asked ChatGPT for suggestions.

After sharing my goals for a slightly more aggressive portfolio, ChatGPT provided a list of potential mutual funds and ETFs to consider. From there, I did my own research, narrowed it down to three, and then asked ChatGPT to compare their performance over the last 1, 5, and 10 years. This helped me make a more informed decision in less time than it would have taken to manually search and analyze the data. ChatGPT didn’t replace my judgment, especially for something this important — it just made the process faster and more efficient.

Holiday shopping inspiration

I put a lot of thought and care into the gifts I give, especially for the closest people in my life. But sometimes, you need to find a gift for someone you don’t know well enough to find that perfect present. In one instance, I gave ChatGPT the details I knew about this kind of person and asked it to generate 25 gift ideas they might like.

Ethan Mollick wrote a great post about how ChatGPT is infinitely patient, so you might as well ask it to generate a whole bunch of ideas at once, knowing that some will inevitably be misses. Out of the 25 suggestions, I found five solid options and chose one that would make most people happy — which is really the goal when you’re buying a gift for someone you don’t know well, like at a company holiday party.

Health

Finding a temporary solution for my tinnitus

After six flights in 10 days this past September, I began struggling with tinnitus. None of the doctors I consulted could offer a clear explanation, and some even suggested it was hearing loss despite my perfect audiograms. I suspected Eustachian Tube Dysfunction (ETD), though all but one dismissed the idea. Using ChatGPT, I was able to narrow the issue down to ETD, likely exacerbated by dry nasal passages.

By bouncing ideas off ChatGPT and asking targeted questions, I found a temporary solution: using a saline mist spray to keep my nose hydrated. This has helped alleviate the symptoms while I waited to see a specialist. Without ChatGPT, I likely wouldn’t have connected the dots and found the relief I needed for now.

Medical research and differential diagnosis

I’ve been dealing with severe nerve pain for over three years, and while I could write pages about the struggle, I’ll save that for another time. What’s important is that I’ve seen more than 50 doctors, and only two have truly helped me make progress. Frustrated with the lack of answers, about six months ago I started turning to ChatGPT and Claude as a diagnostic partner — and it has made a meaningful difference.

By asking ChatGPT targeted questions about my symptoms and experiences, I’ve been able to better understand the biology of my body, and developed more informed ideas to discuss with my doctors. Thanks to this approach, I’ve identified and treated two nerve issues (one rare and one uncommon) that were causing my pain. I now have a theory for the one remaining problem (🤞🏻), and all that’s left is an MRI of my thoracic spine to confirm. (That, and because I live in America, convincing my insurance company to approve the scan…)

ChatGPT hasn’t replaced my doctors, nor do I expect it to anytime soon. What it has done is give me more knowledge and allowed me to test theories that I can bring to my doctors. This is critically important in a medical system where a doctor may only spend 5-10 minutes with you, now I’m able to make the most of that limited time. While the process is far from perfect (and endlessly exhausting if I’m being honest), I’m working with my doctors and within the system’s rules. AI has been a powerful ally throughout this journey.

Modifying my Pilates routine to accommodate for pain

This was probably the hardest item on the list to google. I have a Pilates routine that I do 5-7 times a week to keep my core stable and take strain off the nerves in my torso. While the routine has worked well for years, I needed to temporarily adjust it to accommodate a new pain in my shoulder blade.

To make this change, I shared a screenshot of my pilates routine from the Peloton app with ChatGPT, explained my specific pain points, and asked it to modify the exercises to include bands while keeping me off my back more. The result was an updated routine that fit my needs perfectly — a task I’m not sure how I could have done without without ChatGPT.

Editing this blog post

As someone who takes a lot of pride in my writing and deeply cares about word choice, I will always be transparent about how I use AI to edit my work. I rely on a detailed prompt, part of which reads: “I want the edits to be focused on making the post more concise and to the point, but I do not wish to change the writing style in a way that will make it sound like another person wrote it. The writing should always maintain my tone, sense, and sensibilities.”

I wrote the first draft of this post and refined it myself. ChatGPT’s value in this process was primarily in formatting and structure — I originally wrote this as a series of bullet points. After that I used ChatGPT to discuss ideas about how to clarify my points, which helped me shape the second draft.

This is a collaborative process, thanks to another part of my prompt, which states: “We will edit this post together paragraph by paragraph, rather than all at once.” This interactive approach allows me to go back and forth with ChatGPT, rather than relying on it to do the work for me. Not only does this improve my writing, but it also helps me grow as a writer as I reflect on the many implicit and explicit suggestions ChatGPT offers.

That said, I don’t always use AI for my writing. For example, I write about 1,000 words a day in my journal without any AI assistance because I want every letter of those words to be completely my own. But I have to admit, having a partner to proofread and refine my blog posts has made it easier to publish more frequently. Posts like this would likely take too much effort to share without AI, which makes me think despite people using ChatGPT to create AI slop, there’s significant value to be derived from AI editing in the future.

I actually used ChatGPT much more this weekend, but I left out simple Google-style queries and redundant use cases, such as a swath of additional health questions I’ve explored. If you asked me how I used ChatGPT on another weekend, the list would be different but would likely have a lot of overlap in style and purpose.

What I wanted to illustrate was that with AI, we’ve been given the gift of the world’s smartest and most patient collaborator. AI is such an empowering tool, and how you choose to use it is entirely up to you — but I would urge you not to pass up this golden opportunity.

The Rule of Small and Large

Joe Fabisevich — Mon, 16 Dec 2024 12:00:00 GMT

When it comes to creative work, personal growth is rarely a straight path. Whether you’re a developer, designer, writer, or artist, the question of what to focus on can feel daunting. Over the years, I’ve developed a personal framework to help me stay on track: The Rule of Small and Large.

The Rule of Small and Large is simple: Every project I take on is either small or large — I avoid medium-sized projects at all costs. Why? Small projects let you learn quickly, experiment freely, and explore new ideas with minimal risk. Large projects, on the other hand, challenge you to go deep, tackle complex problems, and build something truly meaningful. Medium projects often fall into a frustrating trap — they demand too much effort for too little reward.

Small

Small projects allow you to experiment quickly, see results, and learn with minimal effort. They’re perfect for testing ideas in a low-risk environment. For example, if I want to explore how a programming language solves a particular problem, I might build a quick prototype. The simpler the process, the more likely I am to start. If I had to download an IDE, compile the language from scratch, and read lengthy documentation, I’d probably abandon the idea altogether.

The beauty of small projects is that they yield small but cumulative rewards. Each one builds on the last, expanding your skillset and perspective over time. Small projects also thrive on simplicity — lowering the barrier to entry makes it easier to start, which encourages creativity and experimentation. This principle doesn’t just help beginners, even experienced creators benefit from the freedom to explore without overcommitting. By keeping the stakes low, small projects let you test ideas, fail fast, and stay in a constant state of discovery.

As an indie developer, I rely on small projects to stay self-sufficient. Whether I’m testing out a new design trend, experimenting with a marketing framework, or playing around with some unfamiliar code, these low-effort experiments validate ideas and help me grow. Small projects aren’t just about learning — they’re about exploring new territory and fueling the creative process.

Large

Large projects are for those big, ambitious ideas that go far beyond a quick prototype. They start with a vision — a real problem you’re determined to solve. But large projects are rarely straightforward. They demand that you solve countless smaller problems before you even get close to your end goal. It’s this process of breaking down complexity and overcoming challenges that makes large projects so rewarding.

The deeper you go, the more you learn. Solving real problems introduces you to complexities you would never encounter in a small project. Let’s say you’re building the next big app for restaurant bookings. At a minimum, you’ll need to understand how time works. That might sound simple, but time zones aren’t so straightforward. Nor are addresses, prices, or payments. Large projects immerse you in real-world challenges that don’t fit neatly in a small project, sharpening your skills and teaching you lessons you wouldn’t gain otherwise.

That’s the magic of large projects: they push you to go deep, master complexity, and create something valuable. If you have a goal, passion, and are willing to push your boundaries, the impact of a large project can be transformative.

Medium

If small projects provide you with breadth and large projects provide you with depth, what do medium-sized projects provide you? A trap.

Medium-sized projects sit in an uncomfortable middle ground. They require more effort than small projects but don’t offer the depth or rewards of large projects. You might learn something, but it’s rarely enough to justify the energy spent. In my experience, medium-sized projects are the ones that most often leave me frustrated — or worse, burned out.

This is why passion and purpose are so important. Large projects demand intrinsic motivation to push through their challenges, and if that motivation isn’t there, it’s often a sign your project isn’t worth scaling up. Medium projects tend to feel aimless — they’re not quite big enough to inspire you, but too involved to finish quickly. When you notice a lack of passion, it’s better to keep a project small, where the stakes are lower and the lessons come faster.

Avoiding medium projects doesn’t mean abandoning ideas altogether — it means being intentional about the scope of your work. If something doesn’t excite you enough to warrant a large commitment, let it stay small. Forcing yourself to choose between small and large helps sharpen your focus and ensures that your energy will be spent where it matters most.

Small and Large

There’s little I love more than starting a new project. Each one feels like a space full of opportunity, a place for my creativity to blossom, and something I can put my heart and soul into. But as exciting as starting can be, I’ve learned that it’s important to know upfront where the project is going too.

Small projects let me experiment and explore, offering quick lessons and opening my eyes to new ideas. Large projects challenge me to commit deeply, be intricate, and build something meaningful. Both provide a clear sense of purpose, which is why I’m happy to keep building projects small and large.

The next time you start a project, pause and ask yourself: is this a small project or a large one? If the answer isn’t clear, you might be stepping into the trap of a medium project. By choosing to stay small or go big, you’ll ensure your energy is spent on work that inspires, challenges, and matters to you.

Empower Apps Podcast: Building Plinky as an Indie Developer

Joe Fabisevich — Wed, 20 Nov 2024 12:00:00 GMT

I joined Leo Dion on the Empower Apps podcast to discuss my journey building Plinky, a link-saving app that I created to solve my own organizational needs. We explored the technical stack behind Plinky, ranging from SwiftUI to Vapor to Postgres, as well as my custom offline persistence library, Boutique.

During our conversation, we dove into the design philosophy behind Plinky, focusing on making it playful, colorful, and customizable. Leo and I discussed the challenges of indie development, from agonizing over every color and icon choice to building features that work for both casual and power users. We also talked about everything coming to Plinky, like Link Reminders, and a native Mac app, as well as AI features that will elevate Plinky as a platform.

A Mental Model For Prompting Large Language Models

Joe Fabisevich — Thu, 14 Nov 2024 12:00:00 GMT

People are often disappointed when they use a Large Language Model (LLM) like ChatGPT or Claude for the first time. They’ve heard about this magical tool that helps people write code, edit blog posts, or suggest delicious recipes, but then Google Gemini tells them to add glue to their pizza, and the magic vanishes.

There are countless guides out there on how to improve your prompts or get better answers. But tips and tricks only go so far. Instead, I’d like to share an analogy that might help you come up with better prompts using your own judgment. There is no magic in computers, even when using a computer feels magical.

Using An LLM

LLMs are trained by scouring data from across the internet ¹, and “learning” that information. ² Imagine a world map where all this knowledge is stored in different places: financial advice in America, programming knowledge scattered across Asia, writing skills in Ireland, and so on.

You open ChatGPT and ask for help with your portfolio.
ChatGPT doesn’t know whether you mean a writing portfolio or a financial portfolio.
Instead of asking for clarification, it assumes you mean financial advice. It tries to remember that by muttering to itself that this is a financial question, so from now on we’re going to look for all of our information in “America”.
Next, you hand it a writing assignment about the stock market, hoping it will improve the quality of your writing.
But instead of focusing on writing quality, ChatGPT invents some information about stocks.
ChatGPT has just hallucinated.

Why LLMs Make Mistakes

To simplify, LLMs don’t actually know anything. Instead they take best guesses word by word ³ to try and predict the best next word, until it completes an answer to your question. A hallucination is a model’s best guess gone awry, when the model doesn’t have a high quality answer or has misinterpreted some context. Instead of pausing to think — because models can’t think — the model will instead continue on with its answer. To humans this reads as incorrect information, bullshitting, or even lying. But the model doesn’t really know good from bad, it just makes a statistically reasonable guess. ⁴

This is why people sometimes think LLMs are useless — and it’s hard to blame them! But I’d like to show you how to make them work better for you, so you can get more value out of them.

Polite People Are Prompt

Rule #1 of successful prompting is to be as specific as possible. The more hints you give the model about what you want to know and where to look, the better its answers will be. In our earlier example, the model struggled because it couldn’t tell if you meant a financial or a writing portfolio, so it looked in the wrong place. The frustrating part? The model had the information you needed but it didn’t know where to find it.

Let’s extend our map analogy a bit to show why hints are useful. Imagine you’re solving a programming problem. As we discussed, programming knowledge is scattered across Asia. The model knows most JavaScript expertise resides in Japan, while Swift knowledge is mostly in Korea — though there are exceptions.

When we tell the model we’re looking to solve a JavaScript programming problem, we’re helping it focus on information in Japan, not South Korea. This avoids the earlier mistake of the model searching for writing advice in America, which is good because America ranks 36th in the world for literacy. We can narrow it down further by specifying we want to use d3.js, guiding the model to look in Tokyo — specifically, Shibuya, where d3.js information “lives.”

Using An LLM (Better)

Let’s say I have another programming problem I want to solve. I give ChatGPT a code snippet that draws a simple multi-colored square on the screen. Then I tell ChatGPT:

I want to make this darker

First of all, what is this? The model has no idea.
What color do you want to make darker?
What does “darker” even mean? Do you want the multi-colored box to be one solid color, like black? Because that’s as dark as anything can be.
Follow-up questions: How much darker? Do you have a specific percentage in mind? Which method should it use — adjust hue, saturation, RGB, luminance, etc?

If a human would have follow-up questions for you, a model probably will too. You can answer those questions in advance or even instruct the LLM to ask you questions if anything is too ambiguous or needs clarification.

Now that we’ve anticipated some potential issues, we can compose a clearer prompt to describe the problem we’re trying to solve.

I have a JavaScript code snippet that draws a simple multi-colored square on the screen. The colors are currently red, blue, green, and orange. I want a new color palette that’s slightly darker, but still vibrant so the colors pop.

Please rewrite the code without using third-party dependencies or frameworks.

Generate 10 color palette options that I can try in my project.

Once I review them, I’ll let you know which one I like best, and I’d like 10 more options based on that.

If anything is unclear or if you have any follow up questions that may help resolve ambiguities, please ask them before writing any code.

See how much clearer this prompt is? It’s more likely to get a good answer because we were very specific about the problem we’re trying to solve. Even as I wrote it, I realized there were multiple ways to approach this problem and details I hadn’t initially considered. The process is a bit like teaching someone who’s never seen the problem before — talking it through helps clarify what needs to be done, both for them and for you.

Writing good prompts is like any skill — the more you do it the better you’ll get. While this analogy is just a starting point, I hope it demonstrates why good prompting is important and how it can help you make the most of this new, almost magical technology. With this technique we’ve brought a little more determinism into a non-deterministic system.

If you’re interested in understanding how LLMs interpret your prompts, you might enjoy this article by Ethan Mollick. For a deeper dive, Stephen Wolfram’s fascinating article provides an in-depth explanation of how LLMs function. Finally, for advanced prompting techniques, this paper is an excellent resource to elevate your skills with LLMs.

Footnotes

For the purposes of this explanation, let’s not get hung up on the fact that this is a legal and ethical gray area. ↩
For the purposes of this explanation, let’s not get hung up on the fact that LLMs are statistical models, and aren’t learning anything. ↩
This in itself is an oversimplification. LLMs actually use tokens, which are a way to chunk letters together, and usually amount to 3-4 characters per token. ↩
There are a lot of techniques to minimize hallucinations, and to provide better information. This is partially why AI has advanced so much, so quickly, as we’ve done a great job of preventing LLMs from going off the rails. ↩

Monarch: Minimal, Manageable, Migrations 🦋

Joe Fabisevich — Wed, 23 Oct 2024 12:00:00 GMT

Note: When I left Twitter to become an indie developer I committed to helping others with my work as much as I could. My goal has always been to make the lives of developers a little easier, so they can turn their ideas into, apps, products, and businesses. Every week this month I will be open sourcing something I’ve built for Plinky, my very own personal Open Source October. My career rests on the foundation that others have created, and I want to continue paying it forward by lowering the barrier for others to make what matters to them. Now, onto the post.

You don’t always get it right the first time. That’s why pencils have erasers — and why apps have migrations. In over two years of building Plinky, I’ve made a lot of mistakes changes. I’ve fixed bugs, rebuilt features completely, and overhauled the app’s data architecture with Boutique.

All these changes required migrating user data to prevent a broken experience. Initially, I used a straightforward solution, running a handful of functions on app launch. But to simplify things over time, Monarch — a simple yet flexible migrations library.

Fun fact alert!

Monarch is named after the Monarch butterfly, the only butterfly that makes a bird-like, bidirectional migration to escape the cold. In that way, the Monarch butterfly and I are similar. As I get older I too dread surviving another New York City winter.

Migrations (of the programmatic variety)

Migrations need to be minimal, manageable, and mistake-free. The more frequently they need to be run, the more true this is. People trust me with their links in Plinky, so I’m very serious about data loss and data corruption. Monarch eliminates the patchwork and complexity, allowing you to focus on writing clean, simple Swift code. Let’s dive into why Monarch is a good choice for your running migrations in your app.

Simple Migrations: Define independent migrations without worrying about state management, making it easy to evolve your app over time.
Built for Swift and SwiftUI: Monarch’s migrations feel right at home in any Swift app, with a clean SwiftUI API.
Dependency Injection: Whether your migration is simple or complex, Monarch’s easy-to-use dependency injection provides structure to prevent data-related issues.

Instead of just telling you how simple Monarch is, let me show you.

Imagine this scenario: You’ve been storing user data for your app in UserDefaults. Your app is doing well, and now you’re ready to build a new feature which requires a share extension. It would be helpful to have this user data available to you in the share extension, which means migrating the data from UserDefaults to an AppGroup shared between your app and share extension.

First, let’s define a migration.

struct MigrateUserDataToAppGroup: Migration {
    @MigrationDependency private var userDefaultsAppState
    @MigrationDependency private var sharedAppState

    static let id: MigrationID = "MigrateUserDataToAppGroup"

    func run() async throws {
        // Migrate the user data from UserDefaults to an AppGroup, so you can share data across targets
        sharedAppState.userData = userDefaultsAppState.userData

        userDefaultsAppState.userData = nil
    }
}

Next, we’ll create a MigrationGroup. This group lets us inject any necessary dependencies from our app, making them accessible to each Migration within the group.

let migrations = MigrationGroup {
    MigrateUserDataToAppGroup()
    // Add more migrations here
}
.migrationDependency(self.userDefaultsAppState)
.migrationDependency(self.sharedAppState)

Finally, we run our migrations!

struct ContentView: View {
    var body: some View {
        Text("Hello, Monarch! 🦋")
            .runMigrations {
                migrations
            }
    }
}

How easy was that? In just a few lines of code, we’ve moved our user data from UserDefaults to an AppGroup. While you could write this code and all of the boilerplate necessary yourself, Monarch makes it seamless to focus on what matters. As your migrations grow, this structure helps prevent bugs and race conditions.

Advanced Usage

While migrations often solve problems, occasionally they may introduce new ones. In such cases, developers need more control. Monarch offers a MigrationRunner, which lets you build custom and complex migration pipelines. In the small app below, we’ll explore how MigrationRunner can manage multiple migration tasks.

struct ButterflyTrackerApp: App {
    @State var appState = AppState()
    @State var preferences = Preferences()
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .task { 
						try await self.runMigrations()
                }
        }
    }
    
	func runMigrations() async throws {
		// 1. Remove all the migrations
		MigrationRunner.removeAllMigrations()
		
		// 2. Mark the ResetButterflyListMigration as completed
		MigrationRunner.markMigrationAsCompleted(withID: ResetButterflyListMigration.id)

		// 3. Create a MigrationGroup, with two dependencies and two migrations to run.
		let migrationGroup = MigrationGroup {
		    ProvideButterlyFansPremiumAccountAccessMigration()
		    RemoveAccidentallyAddedMothMigration()
		}
		.migrationDependency(self.appState)
		.migrationDependency(self.preferences)
		
		// 4. We run our migrations
		try await MigrationRunner.runMigrations({ migrationGroup })
    }
}

In the example above we:

Removed all previous migrations, giving us a clean slate. (Note: You can also remove individual migrations without clearing all of them.)
Marked the ResetButterflyListMigration as completed without running it. This allows us to skip a migration, which can be useful on a per-user basis or when transitioning from another migration system.
Created a MigrationGroup with two migrations, which will run in the specified order. We also added two dependencies, to ensure access to the necessary state in our migrations.
Ran our migrations! After all, that’s the goal.

When I open source a project, I’m usually excited to share what’s coming next. Monarch is a handy tool, but as the Brits say, it “does exactly what it says on the tin.” It’s been a go-to solution for me over the last few years across multiple apps, and I hope it helps solve similar problems in your apps too.

I’m always open to feedback, so I’d love to hear any thoughts or suggestions you may have. You can find me on Threads, where I welcome any and all polite discussions.

Building A Customizable Framer Component

Joe Fabisevich — Mon, 14 Oct 2024 12:00:00 GMT

Note: When I left Twitter to become an indie developer I committed to helping others with my work as much as I could. My goal has always been to make the lives of developers a little easier, so they can turn their ideas into, apps, products, and businesses. Every week this month I will be open sourcing something I’ve built for Plinky, my very own personal Open Source October. My career rests on the foundation that others have created, and I want to continue paying it forward by lowering the barrier for others to make what matters to them. Now, onto the post.

If you came here for the Buttondown Framer Component I’ve open sourced, you can skip the post below and grab the code on Buttondown’s official repo. But if you happen to be interested in the technical details of how to build a customizable Framer Component, keep reading for a walkthrough.

When I launched Plinky’s Links You’ll Love newsletter, I knew I needed a beautiful landing page to set the right expectation for quality. The problem? I’m sick and tired of writing HTML, CSS, and JavaScript, with zero interest in building a landing page from scratch.

I’d heard a lot about Framer from my designer friends, and how easy Framer made it to build beautiful websites. The canvas felt familiar, like a more interactive version of Figma. Within half an hour of playing with Framer, I had a slick landing page with fancy animations that took only minutes to create. Despite a few missing features and minor quirks, I fell in love immediately.

Code Components

What really sold me on Framer wasn’t just the features it has, but how it handles what it doesn’t have. Framer provides common elements for website layouts, like Stacks, Images, and Text, but sometimes you need something custom. That’s where Code Components come in.

At its simplest, a Code Component is a React component, which means you can create just about anything with a bit of JavaScript.¹ There are also many pre-made components available, and best of all, they’re fully customizable.

The magic of Framer’s Code Components lies in Property Controls, which are essentially React props. By adding Property Controls, Code Components become as customizable as any other Framer element. I’ll explain how this works in just a moment.

Framer x Buttondown

I use Buttondown, a popular indie email service, to deliver my newsletter. Buttondown is run by Justin Duke, a prolific writer who’s very helpful and shares a lot of valuable lessons — really an all-around great guy. While the default look of Buttondown’s email form is basic, I wanted something more polished for my website. This meant writing a lot of CSS, or… I could create a Code Component. 🤔

I dove into the Framer docs, and once I had an understanding for how they worked, I fed that documentation to Claude to outsource the work of writing a template for my Code Component. The real fun began when I realized I could open source this component for other Framer users, and leaned into my love for building reusable abstractions.

Building A Code Component

The structure of a Framer Code Component is similar to any other React component. You import React, write functions, and use features like State and Effects. Most of the time you’re just writing standard React so I’ll skip over some details, but you can view the complete code for this component here.

import React, { useState, useEffect } from "react"
import { addPropertyControls, ControlType } from "framer"

export default function ButtondownForm(props) {
  const {
    newsletterConfiguration,
    text,
    style,
    textFieldFont,
    buttonFont,
    backgroundColor,
    submitButtonColors,
    margin,
    cornerRadius,
    borderColor,
    borderWidth,
    ...rest
  } = props
  
  const [email, setEmail] = useState("")
  const [formState, setFormState] = useState("idle") // idle, invalid, submitting, success

  // A *lot* more code here...

  useEffect(() => {
      if (formState === "success") {
          const timer = setTimeout(() => {
              setFormState("idle")
              setEmail("")
          }, 2000)
          return () => clearTimeout(timer)
      }
  }, [formState])

  const handleSubmit = (e) => {
    // It's me, I'm handling submit!
  }

  const getButtonContent = () => {
    // It's me, I'm getting the button content!
  }

  const getButtonStyle = () => {
    // It's me, I'm getting the button style!
  }

  return (
    <>
      <style>{`
        // Your neat CSS bits
      `}</style>
      <form
          className="buttondown-form"
          action={newsletterConfiguration.embedURL}
          method="post"
          target={
              newsletterConfiguration.onSubmit &&
              newsletterConfiguration.onSubmit.trim() !== ""
                  ? "popupwindow"
                  : undefined
          }
          onSubmit={handleSubmit}
          style={{
              ...newsletterConfiguration,
              ...formStyle,
              ...style,
              backgroundColor,
              borderRadius: cornerRadius.form,
              borderColor,
              borderWidth,
              borderStyle: borderWidth > 0 ? "solid" : "none",
          }}
      >
        <input
            type="email"
            name="email"
            id="bd-email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            placeholder={text.placeholder}
            style={{
                ...inputStyle,
                ...textFieldFont,
                borderRadius: cornerRadius.input,
            }}
            required
        />
        <button
            type="submit"
            style={getButtonStyle()}
            onMouseEnter={() => setIsHovered(true)}
            onMouseLeave={() => setIsHovered(false)}
            disabled={formState === "submitting"}
        >
            {getButtonContent()}
        </button>
        <label htmlFor="bd-email" style={srOnlyStyle}>
            Enter your email
        </label>
      </form>
    </>
  )
}

This component has various customizable properties, like newsletterConfiguration, formStyle, text, making it adaptable to different design needs. But the real power of a Framer Code Component comes from the addPropertyControls function.

By adding Property Controls, we can make this form as customizable as any other standard Framer element. This is what allows us to transform the Buttondown form I built for my website, and turn it into a form that anyone can personalize for their website.

addPropertyControls(ButtondownForm, {
    newsletterConfiguration: {
        type: ControlType.Object,
        title: "Newsletter",
        controls: {
            embedURL: {
                type: ControlType.String,
                title: "Embed URL",
            },
            onSubmit: {
                type: ControlType.String,
                title: "onSubmit",
                displayTextArea: true,
            },
        },
    },
    textFieldFont: {
        type: ControlType.Object,
        title: "Input Font",
        controls: {
            fontFamily: { type: ControlType.String, title: "Family" },
            fontSize: { type: ControlType.String, title: "Size" },
            fontWeight: {
                type: ControlType.Enum,
                title: "Weight",
                options: [
                    "Normal",
                    "Bold",
                    "100",
                    "200",
                    "300",
                    "400",
                    "500",
                    "600",
                    "700",
                    "800",
                    "900",
                ],
            },
        },
    },
    backgroundColor: { type: ControlType.Color, title: "Background Color" },
    text: {
        type: ControlType.Object,
        title: "Text",
        controls: {
            placeholder: {
                type: ControlType.String,
                title: "Placeholder",
            },
            submitButton: {
                type: ControlType.String,
                title: "Button Text",
            },
        },
    },
    borderWidth: {
        type: ControlType.Number,
        title: "Border Width",
        min: 0,
        max: 10,
        step: 1,
    },
})

The addPropertyControls function allows us to define these customization options using Framer primitives like ControlType.String, ControlType.Number, ControlType.Color, and ControlType.Object. These controls turn into beautiful configuration panels in Framer, where users can tweak settings to match their design preferences.

Now, we have a fully customizable Framer Component, ready for any Buttondown newsletter, whether your favorite color is red, blue, green, or even my favorite color in Plinky, pink.

Speaking of newsletters, if you enjoy thought-provoking and enjoyable articles delivered straight to your inbox, I’d love for you to see the form I made for my Buttondown newsletter, and perhaps even sign up..

And if you have any thoughts or suggestions, I’m always available on Threads. I welcome any and all polite discussions.

Footnotes

Although I started off this post by saying I didn’t want to write JavaScript (or TypeScript), I find writing this kind of code is a lot more enjoyable than laying out a responsive website that works across half a dozen browsers. ↩

Introducing Recap: What's Old Is What's New Again

Joe Fabisevich — Wed, 09 Oct 2024 12:00:00 GMT

Note: When I left Twitter to become an indie developer I committed to helping others with my work as much as I could. My goal has always been to make the lives of developers a little easier, so they can turn their ideas into, apps, products, and businesses. Every week this month I will be open sourcing something I’ve built for Plinky, my very own personal Open Source October. My career rests on the foundation that others have created, and I want to continue paying it forward by lowering the barrier for others to make what matters to them. Now, onto the post.

What’s New? Nm, what’s new witchu?

We’ve all experienced launching one of our favorite apps, and seeing it’s had a big update. When that happens you’ll be greeted by screen that says “What’s New”, even Apple’s apps do this. The What’s New Screen is a great way to use one of the few moments an app has a user’s attention, to let them know about the new value you’ve delivered.

Since launching Plinky I’ve released an update every month. With so many new features, I wanted to ensure that people know I’m adding a lot of value to Plinky. This led me to build my own version of a What’s New Screen, in a library I call Recap.

I had a few key priorities in mind when building my version of a What’s New screen:

Comprehensive version history: I wanted to showcase all the value I’ve added over time, so the What’s New Screen can scroll back through every major update. This is especially useful for new users, who can easily discover Plinky’s full feature set with each update.
Effortless updates: With monthly app releases, adding new features to the What’s New screen needed to be quick and straightforward. The release process is stressful enough, so I wanted to avoid adding more hurdles to it.
On-brand design: Plinky is known for being colorful, playful, and customizable. I wanted my What’s New screen to embody these qualities, while building Recap to fit in with any app’s design language.

I built a prototype of a What’s New Screen in a few hours, and quickly decided to open source the project. My goal is to help developers focus on what they do best — creating value for their users. By open sourcing code that solves common problems, I hope to contribute to that mission.

Recap

Recap is a What’s New Screen that requires just two lines of code to implement, but it offers much more. It delivers on all the priorities I mentioned earlier: it’s easy to integrate, highly customizable, and handles several common implementation challenges.

No Code Updates

Recap’s standout feature is its markdown-powered release list. Here’s how simple it is to implement:

// Initialize releases from a markdown file in your app's bundle
let releases = ReleasesParser(fileName: "Releases").releases

// Create and display the RecapScreen
RecapScreen(releases: releases)

Updating your What’s New Screen is as easy as editing a markdown file — no code changes required. The simple markdown spec lets you create new versions in minutes:

# Version Number
## Release Title
### Change Type

- title
- description
- symbol
- color

And here’s a concrete example of what a 1.0 release for Recap might look like:

# 1.0
## Introducing Recap 🥳
### Major

- title: Welcome to Recap
- description: It's live! 🥰
- symbol: party.popper
- color: `#F72585`

Customization

Now, let’s explore a more advanced example from Plinky. This version has icons, colors, gradients, and markdown support (including links). With just a bit of SwiftUI and markdown, we have a beautiful What’s New Screen. Each feature is defined by four elements: title, description, symbol, and color.

# 3.0
## New in Plinky 3.0
### Major

- title: Widgets, Widgets, Widgets  
- description: Customize your Home Screen, Lock Screen, and Control Center with 27 new widgets to easily access your links.
- symbol: rectangle.on.rectangle.angled
- color: `#F72585`

- title: Smarter Search  
- description: Now, find all of your saved links from anywhere on your iPhone or iPad with our Spotlight integration.
- symbol: text.magnifyingglass
- color: `#4895EF`

- title: Apple Intelligence Ready 🤖  
- description: Starting in iOS 18.1 the new and improved Siri will know about your saved links, making them available to apps like Calendar, Mail, Notes, and more.
- symbol: sparkles
- color: `#8E44AD`

- title: Shiny New App Icons  
- description: 33 new icon styles, including a special icon to match iOS 18’s dark and tinted modes. [Pick your favorite](https://plinky.app/open/appIcons).
- symbol: app.badge
- color: `#FFC933`

Looking closely you’ll notice a subtle gradient on each icon. This is achieved using one of the many recapScreen modifiers, allowing you to fully align the What’s New Screen with your app’s design language. Here are a few examples to customize the icon fill mode, dismiss button style, and page indicators:

RecapScreen(releases: releases)
    .recapScreenIconFillMode(.gradient)
    .recapScreenDismissButtonStyle(Color.pink, Color.white)
    .recapScreenPageIndicatorColors(selected: Color.pink, deselected: Color.gray)

Recap offers numerous customization options. You can adjust title colors, screen padding, backgrounds, and more. For a complete list of supported modifiers, I recommend checking out the documentation.

Version History

You may have noticed that there are multiple pages of releases — a core feature that inspired Recap. This allows users to browse all your app’s features, simply by adding multiple releases to your markdown file.

Recap also supports a leadingView and trailingView. In Plinky, I use these to showcase my roadmap on the first page and a support screen at the end. This is a nice way to keep users informed about upcoming features, and encourage their input.

RecapScreen(
    releases: releases
    leadingView: {
        UpcomingRoadmapView()
    }, trailingView: {
        SupportView()
    }
)

Semantic Versioning

Determining when to show your What’s New Screen can be tricky, and worst of all, you only know if it worked after an app update. To address this, I’ve integrated a flexible semantic versioning helper into Recap.

The SemanticVersion type converts string version numbers (like Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString")) into the familiar semver format. The parser is forgiving, handling versions like 1.0.0, 2.0, or 3 with ease.

Here’s an example of how to use semantic versioning to show the What’s New Screen only for major or minor version increases:

var shouldDisplayRecapScreen: Bool {
    let currentVersionNumberString = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
    let previousVersionNumberString = "1.0.0" // You should decide the best way to store the user's last launched version number, UserDefaults is a useful option.
	
	guard let currentVersionString, previousVersionString else { return false }

	let currentVersion = SemanticVersion(version: currentVersionString)
	let previousVersion = SemanticVersion(version: previousVersionString)

	return currentVersion.major > previousVersion.major || currentVersion.minor > previousVersion.minor
}

This will display the screen when updating from 1.0.0 to 1.1.0 or 2.0.0, but not for patch updates like 1.0.0 to 1.0.1.

What’s Next

We’ve covered the key features of Recap, but there’s more to explore. For a deeper dive, check out the code on Github. I believe Recap offers a simple yet powerful solution for What’s New Screens, adaptable to any app’s needs.

I have plenty of new features in mind for Recap, and I’d love your input. If you have any thoughts or suggestions, I’m always available on Threads. I welcome any and all polite discussions.

Indie App Spotlight - Plinky Feature

Joe Fabisevich — Tue, 10 Sep 2024 12:00:00 GMT

I was honored to have Plinky featured in Indie App Spotlight Issue 20. In this in-depth interview, I shared the complete story behind Plinky - from its origins as a simple solution for sharing links with my wife to becoming a powerful, customizable link-saving app used by thousands.

This is an interview that I did with Indie App Spotlight, originally posted on their blog.

Issue 20 - Plinky

Hey everyone, In this issue we’re taking a look at Plinky created by Joe Fabisevich. Plinky is more than just a link-saving app; it also includes browser extensions and a lightweight macOS app. Its user interface (UI) stands out because it doesn’t rely on standard iOS UI elements. I particularly appreciate the ability to set up folders for various needs. Joe is certainly not taking it easy; just two months after launch, he released version 2.0, which offers even more customization options.

App Spotlight

App Name : Plinky

Developer : Joe Fabisevich - Threads

What Is Plinky?

Plinky is an app that makes it really easy to save links to enjoy later. With Plinky’s share extensions oniPhone and iPad, browser extensions forChrome,Safari, andFirefox, a little menu bar app calledPlinky Mini, and an open API, you can save links from anywhere with just one tap or click. When you’re ready to come back to your links, they’re all there in Plinky, complete with organizational tools like folders, tags, search, and more. There are plenty of apps that help you save links, but Plinky really shines in three ways. 1 - It’s quick and delightful to save a link in Plinky. I save a dozen links a day, and all of that time adds up. I made speed a priority in Plinky to save your links and get you back to what you were doing quickly. 2 - Plinky is incredibly customizable. After years of trying out every link-saving product, I was never able to find one that felt just right for me. I’ve gone to great lengths to make every aspect of Plinky customizable, so you can make it a home for your links. 3 - Plinky is highly extensible. There are some great read-it-later apps, but they’re not particularly good for the cute animal videos or funny tweets you want to show your partner. Some apps are great for archiving, but they’re not flexible enough to use as a todo list for your links. I focused on making Plinky work for all kinds of links, all kinds of workflows, and all kinds of people who want to save links for later.

Where did the idea for Plinky come from?

When I first started dating my now wife Colleen, I would send her links I saw throughout the day. I have to emphasize, it was a lot of links. Working at Twitter meant I came across so many interesting articles, recipes, and funny videos. While she loved that I was thinking of her, she also found it pretty distracting when her phone buzzed with all the links I’d send.

She suggested saving the links for later so we could look at them together, at night once she was done working. I tried filling up the Notes app with links, but that quickly became a disorganized mess. I left dozens of browser tabs open, but I’d forget about them, only for more links to pile up. I tried adding links as todos in the Reminders app, but then I couldn’t actually use Reminders with the jumble of saved links. I just wanted one place that made it easy to find all my saved links, so one morning I woke up, told Colleen I had an idea for an app, and started working on Plinky.

Within two weeks, I had a working app for the two of us. Then I started showing it to people, and they said they really wanted an app to help them organize their links. As an avid fan of read-it-later and archiving apps, I knew that solutions existed, but those apps didn’t really resonate with the people I showed Plinky to, at least not in the same way my little app did.

I like to think of Plinky as my love letter to links, and to Colleen. Now that we have a place to save the links we come across throughout the day, and we set aside time every night to share them, what we call plink time.

What’s one stand out feature you’d like everyone to know about?

Plinky has always made it quick and easy to save a link, a value that I don’t want to compromise on. It’s also important for me to allow Plinky to grow more powerful, to match the workflows that people need from their link saving app.

Plinky 2.0 solves this design challenge with a feature called Save Screen Actions. As more people began using Plinky, I noticed they had many different needs and ideas for what they wanted to do when saving a link. Some people wanted to add their link to a folder, many people have a more tag-oriented workflow and wanted to add tags to their link without opening the app, and others wanted lesser-used options like archive or pin to still be available when they needed them.

When you save a link using Plinky’s share extension, the link saves quickly and lets you get back to what you were doing. But if you want to edit the link in any way, you do that by pressing any of the actions, and the timer that would have dismissed Plinky’s Save Screen pauses. After that, you’re free to add your link to a folder, pin it, copy the link, or perform any of the other available actions, and dismiss whenever you want.

This is different from many other apps that treat the share extension either as a quick action or a full editing mode. I really wanted to bridge that divide and provide both. One of my favorite compliments about the feature so far was that “it’s something you have to try to get, but when you do it just makes sense”. In the spirit of showing rather than telling, I’ve got a little demo of how it works.

How do you promote Plinky?

I’m actually planning to write a blog post about this, but I’d say the #1 piece of advice I have for building a good marketing strategy is to marry an amazing product marketer. I’m incredibly grateful to Colleen for helping build a full go-to-market strategy for Plinky — I wouldn’t have had nearly as successful a launch without that. If you’re already married or aren’t romantically interested in any product marketers, then here’s what I use as my outline for launching an app:

Conduct user research. This may sound scary or buttoned-up but really it’s just taking 30 minutes to talk to a user. This will not only help you understand your product, but it will help you understand the value people are getting from it, which is crucial for crafting a great marketing message.
Do competitor analysis. Download a bunch of apps in your space, sign up for their onboarding and marketing emails, then don’t touch anything to see how they try to reactivate you as a user. This will help you understand what features people are looking for, what your competitors offer, and where you have room to make your app stand out.
Create a cohesive brand. Those first two bullet points will help you craft a message to share with the world. The hardest part for me is sticking to the main selling points, because I get really excited and love to talk about everything my app can do in the nerdiest ways.
Collect emails early and often. This is highly underrated because no one really wants more email, but an email address is the one piece of connective glue we all have. In a world of scattered social networks and new apps popping up every week, email is the one place to reach people who have shown direct interest in hearing more about your product. Don’t be a jerk and don’t spam people with every little update, but reaching out occasionally to share the value you’ve added to your app is a great way to keep people in the loop about what you’re building.
Tell Apple! Most people don’t know about appstore.com/promote, but you can literally tell Apple you want to be promoted. (This will be even easier in the fall, when Apple launches Nominations.) I can’t say for sure because when Apple chooses to feature your app can be a bit of a mystery, but I’m confident that filling out the promotional form played a part in Plinky being featured by Apple on the App Store within two months of launch.

I did quite a few more things to launch Plinky, including leveraging my social media following, blogging, and PR, but I do need to save some tips for my own blog. 😉

How did you decide on the pricing?

Before shipping, I set aside time to do competitor analysis to make sure I understood the market I was entering. I’m really familiar with the product space — I’d probably tried more read-it-later or archiving apps than 99.9% of people on the planet before deciding to dedicate 2+ years of my life to building Plinky as an indie business.

I settled on $3.99/month or $39.99/year for Plinky Pro for a few reasons:

The most expensive apps in this product category are about $60/year, and the cheapest decent quality apps are priced as low as a $10 one-time purchase. I’m building more than just an app — Plinky is a service with recurring costs, so I knew that a one-time purchase would be unsustainable and I’d have to go the subscription route. I didn’t yet feel I could match the $60/year apps feature for feature, but I knew from the beta that hundreds of people were using the app and finding it valuable.
You can always change your price! It’s really easy to get caught up in finding the perfect price, but the only way you can figure it out is by testing the supply/demand curve of different prices and seeing what resonates with consumers. I chose $39.99 as a price that sat in the middle to high end of the category’s range, while still giving me flexibility to make adjustments up or down as needed.
Speaking of price adjustments, I knew from the start that I wanted to leave room to run sales. The sale price needs to be high enough to support the costs of running the business, yet still offer a good deal. The $39.99/year price point is a sweet spot where I can afford to mark down Plinky Pro by ~50%, and still provide a high-quality product at just $1.60/month. My hope is that by the time their yearly subscription renews Plinky will have added a lot of value. I’m working on features like a Mac app, Link Reminders, Shared Folders, a dedicated reader mode, and much more, which will make the renewal price of $39.99 a great deal.

How did you launch Plinky?

As I mentioned earlier, with Colleen’s help I had a great go-to-market plan. But I actually had three launches, intentionally so.

The first launch was just me, Colleen, and my friend Soroush. Soroush helped put together Plinky’s payments backend two weeks before launch. Unfortunately, it’s pretty hard to test payments with an app that isn’t yet in the App Store, so I pushed the button to release Plinky and we tried out the payment flow. I’m glad we did this because we found two bugs and an edge case we hadn’t considered with redeeming Plinky Pro promo codes.
I fixed those bugs over the next 24 hours, then flew out to Chicago for the Deep Dish Swift conference. I soft-launched the app at the conference and offered personalized promo codes, netting me my first couple dozen subscribers. More importantly, I was at a conference with hundreds of iOS developers, people who love to share their opinions about apps. Even though I’d had hundreds of people using the app, watching completely new users go through the onboarding flow with no context was incredibly valuable. Many people were kind and diplomatic with their feedback, but I gently pressed them to tell me what worked and what didn’t. I could see where people were getting tripped up or didn’t understand what to do, so I asked them what they liked, what they didn’t get, and what they wanted the app to do, all of which helped me prioritize some quick fixes. I spent the next three days addressing everything in the app that wasn’t clear, including completely rebuilding the onboarding in a chaotic 8-hour haze of coding while conference talks happened around me.
I officially launched the app a few days later, and it went beyond my wildest expectations. Not only was the initial reception from my community overwhelmingly positive, but having people who’d never heard of me start using the app was a sign that I was onto something. When I got my first subscriptions from countries like Greece, Brazil, and Bulgaria, I knew these had to be from people I didn’t personally know, and that I’d made an app that strangers liked enough to pay for. The best thing though was how many compliments I got about Plinky’s updated onboarding, given how tough it is to teach a non-technical person how to set up a share extension — that 8-hour coding haze fuelled by panic was well worth the result.

How long did it take to get to the first version?

Way too long. I started working on Plinky while I was still working as an iOS developer at Twitter in 2021, as a small app for Colleen and myself. As I started showing Plinky to people, I kept hearing that they were looking for something like this. I left Twitter to pursue my dream of being a full-time indie developer in April 2022, and shipped a public beta in November. The beta grew to hundreds of users, which was amazing for getting feedback.

Then ChatGPT happened. The afternoon OpenAI released their API, I spent about three hours building a small prototype to see if I could create an app that would let me use ChatGPT through Siri. I shared the prototype on Mastodon, and a bunch of people said they wanted this prototype as a full app. I reached out to my friend Soroush and asked if he wanted to help build a small Swift server to proxy API calls, because I couldn’t ship my OpenAI API keys in the app for fear someone would extract and use them.

We built and shipped a complete ChatGPT app, Short Circuit, in just 19 days. We made about $1,000 in sales in the first weekend, which was more money than either of us had ever made from an indie app. A few days later, we noticed a ridiculous amount of sales coming through — our app had gotten featured on Daring Fireball. This was a life-changing experience, not only because of the burst of money, but because it validated that I could build something valuable as an indie developer.

We ended up spending about 3 months working on the app and built quite a few novel technologies and features. Despite that, I saw the writing on the wall when ChatGPT came out with their app. We debated the pros and cons of continuing to work on Short Circuit, but as much as we loved working together it made more sense for me to focus on finishing Plinky and building that into a sustainable business.

It took another 8 months of work before Plinky shipped to the App Store, but I finally launched Plinky 1.0 in May 2024. From my first commit to launch, it was 920 days, 1,624 total commits, and 37,145 lines of code across the apps, server, and browser extensions — totalling over 1,500 hours of work. It was so much effort that I get tired just thinking about it, phew.

Launching was a very emotional experience, especially because the entire time I was working on Plinky, I was dealing with an incredibly painful health matter. It drained a lot of my time and energy, but I’m really proud to have overcome all the obstacles in my way. The whole process taught me how strong I really am, that I have the ability to do pretty much anything I set my mind to.

Is there anything you’ve learnt that stands out?

While developing Plinky, I kept looking at my competitors and thinking, “If I want to compete with these apps, I need to have all their features — otherwise, who would choose my app over theirs?” But when I talked to users, I discovered that what I thought was important often differed from what they valued.

I thought Plinky needed to launch with a reader mode because apps like Pocket or Instapaper offered them. I’d always used Pocket to read articles, but one user I spoke to was saving YouTube links, and she hated that Pocket tried to open videos in a reader mode. I’d never considered that a reader mode could be a negative feature, and ironically, the fact that Plinky was missing this feature was what drew her to the app.

This insight led me to realize that I should build Plinky to be highly customizable, making it your home for links. If someone who loves to read could use Plinky for articles, while another person could customize it for watching YouTube videos, then I could expand beyond just the read-it-later market.

Many similar light bulb moments have occurred when I’ve spoken to users of Plinky. I’m really glad that I genuinely enjoy listening to people and ask lots of questions to understand their needs. My favorite moment is when I build a feature and get to delight someone with an email telling them I’ve created what they asked for — and often hear back that I’ve exceeded their expectations.

Any tools or apps you would recommend others check out?

Have you heard of this great app named Plinky? Oh, you mean besides my app.

If it wasn’t obvious already, I truly love apps. I could spend HOURS giving recommendations, so I’ll try to limit myself to just one.

I’m a really big reader. I especially love articles, blog posts, and all of the amazing writing available across the internet. I use RSS to find much of that writing, and my go-to app for RSS is Reeder. (Though I’d like to give an honorable mention to Unread, which offers a beautiful reading experience, while being utterly charming and pleasant to use.)

I’ve been using Reeder for over a decade, and it’s one of the few apps that has been great since day one. The app hasn’t changed dramatically, and yet every release is full of improvements, delight, and whimsy. It’s incredibly difficult to innovate without completely reinventing your product, but Silvio Rizzi has achieved something truly remarkable with Reeder. He’s built an app that I’ve used daily for a decade with nothing but enjoyment.

What’s one tip you would give to someone starting out?

This is a tough question to answer because I’ve been building iOS apps for 15 years, and it’s hard to put myself in the shoes of someone just starting out. However, I do mentor many new developers, and I always give them one simple, yet powerful piece of advice: you won’t learn unless you make something.

In today’s connected world, it’s never been easier to acquire knowledge. However, gaining wisdom requires experience. There are good ideas and bad ideas, and I almost don’t care what my mentees do, as long as they do something. Learning what’s good and bad takes experience, and when you look back you realize that the order you learned the lessons doesn’t really matter. To quote Steve Jobs, “You can’t connect the dots looking forward; you can only connect them looking backwards. So you have to trust that the dots will somehow connect in your future.” Many people fixate on potential failures, often overlooking the possibilities for success or growth, even from setbacks.

To illustrate this point, I often share a very short blog post with people. You can be someone who tries to solve problems purely in their head, or you can put fingers to keyboard and make tangible progress towards your goals. The former path is full of infinite paths and unrealized possibilities, but the latter validates you to test and refine assumptions. This hands-on method not only helps you realize your vision but might even lead you to invent something entirely new — something you couldn’t have imagined just by thinking about it.

Where can everyone go to find out more?

You can find out more about pretty much anything on the internet! But if you’re asking specifically:

For Plinky, visit plinky.app. Better yet, download the app and try it out — it’s something best experienced rather than explained.
To keep up with Plinky updates, follow the Plinky account on Threads. That’s where I share my work-in-progress, app updates, and (of course) pictures of red pandas.
As for me, I’m probably too online for my own good, so you can find me posting frequently on Threads.

Compile Swift Podcast: Being Featured on the App Store

Joe Fabisevich — Mon, 19 Aug 2024 12:00:00 GMT

I joined Peter Witham on the Compile Swift podcast to share the story of Plinky being featured on the App Store. It’s such a rare recognition, one that’s rarer than getting into Harvard, and provided a lot of validation early after Plinky’s release.

We also dove into the realities of indie app development, the importance of intrinsic motivation, solving genuine problems, and creating delightful user experiences. While technical excellence matters, it doesn’t outweigh setting achievable goals, the value of customer feedback, and a strong focus on marketing and product positioning. And we ended up chatting a lot about philosophy, which is not at all what I expected.

Introducing Plinky: My Love Letter To Links

Joe Fabisevich — Thu, 09 May 2024 12:00:00 GMT

The post below was written by me, originally featured on the Plinky blog.

To celebrate the launch of Plinky you can get 50% off of a yearly subscription by redeeming this offer: plinky.app/offer/REDPANDA

There are few words I’ve ever said more excitedly than these: I want to tell you about my latest app, Plinky.

Plinky makes it incredibly easy to do something we do every day, save links for later. You may already have a way to save links, I know I’ve tried every method under the sun, to the point where I decided to build my own app. That app is Plinky, and today it’s available to download on the App Store. Over the last 18 months people have been loving Plinky, because it fixes the same problems I ran into when I’ve tried to save links in the past.

I tried filling up Apple Notes with links to come back to later, but that proved to be a disorganized mess.
I tried leaving browser tabs open with links I wanted to look at later, but the links I needed later got lost amongst the dozens of tabs I had open for right now.
I even tried spending hundreds of hours using apps dedicated for reading articles later, but not all links are for reading.

All of that led me to build Plinky, a home for your links.

Why I Built An App To Save Your Links

I love links. I love reading links, I love it when people send me links to funny videos, I love collecting links, and I love sharing links. Something else I love is my fiancée Colleen. Shortly after meeting Colleen discovered how much I love links, and I’m very grateful that she found that to be an endearing trait. While she loved that I was thinking of her and sharing interesting articles, recipes to cook together, or cute animals I knew she’d like, she quickly found it distracting to have her phone buzzing with all the links I’d share while she was working.

She suggested saving the links for later, so we could look at them together at night. That’s when I started working on a small project, a home for these links, an app that would become Plinky. I started to show people the app I’d made for the two of us, and they loved it. They were all saving links they needed but were unhappy with one thing or another. They kept telling me that they wanted an app like this for themselves. A few months later when I left my job at Twitter to start my own company building personal, playful, productivity apps, I decided that the app I needed to build for all of these people was Plinky.

Plinky became more than an app to Colleen and I, it became an essential tool in our lives and a ritual. Sometimes Colleen would save a cute picture of a red panda for me, sometimes I would save an activity we could do next weekend, but every night the two of us would come together and share the links that we’d saved for each other. To this day we still have plink time, where we lay in bed and show each other the links we’ve for each other.

Links come in all forms. An article just isn’t the same as a Tweet or Instagram post you want to show a friend. A YouTube video or TikTok won’t even open in an app dedicated to reading. Many apps like LinkedIn or Facebook have their own bookmarking systems, but I’ve wasted hours bouncing from app to app trying to remember where that link I saw a month ago but need now is.

As I’ve built Plinky I’ve heard people tell me about the myriad of techniques they have for saving and storing links. There are an unending amount of organizational methods people use to reference links they might need later, but none of those perfectly fit into one app.

The experience of listening to Plinky’s beta testers led me to three realizations:

It needs to be easy to save a link, the simpler the better. Saving a link shouldn’t take work, it needs to be one tap, so you can easily save a link.
People’s workflows benefit from having a universal inbox for their links. It should be easy to organize and find links you’ve saved for later, otherwise why are you even saving them?
People aren’t always looking for an app dedicated to reading articles. The diversity of links people save means many people are looking for a tool that helps them do anything with the links they’ve saved, a Swiss army knife for their links.

This is where Plinky comes in.

Plinky: Saving Links Made Effortless

Plinky makes it easy to save a link for later. You can save links from anywhere with just one tap. Whether you’re on the iPhone, iPad, or Mac, in your favorite browser like Chrome, Firefox, and Safari, or want to build personalized workflows using integrations like Zapier, Unread, Shortcuts, or Plinky’s API, saving a link for later couldn’t be easier.

Plinky is highly customizable. You can make the app look, feel, and behave however you like. The links you save are very personal, as is what you want to do with them after they’re saved. People have all sorts of workflows, so it’s a core goal of mine to make Plinky easy enough for my mom to use (she really is a big user), yet something you can infinitely tweak to make Plinky a perfect place for your links.

Plinky has organizational features like Folders, Tags, Search, and Pinned Links. Each of these provides an opportunity to mold Plinky to your needs, and makes it very easy to find your saved links later.

What’s Next For Plinky

I’m continuing to build upon these three pillars: ease, customization, and organization.

Over the coming months Plinky will have the ability to:

Add timed reminders for your links, for the purpose of reviewing a link in a certain time or context.
Import your links from services like GoodLinks, Raindrop, Pocket, and other places you may already have your links saved.
Create Secure Folders, giving you a space for more sensitive links protected by TouchID and FaceID.
Indulge in an elegant reading experience that lets you customize fonts, sizes, and background color for the ideal read it later experience.
Enjoy a native Mac app, one that takes the beautiful design Plinky already provides on iPhone and iPad and makes it feels right at home on the Mac.
Have more ways to build personalized workflows around your links. It’s easy to tag a link, but it should always be getting easier. Pinning links helps you prioritize some links over others, but the best experience will be even quicker. Plinky’s search is powerful but it can get even more helpful by searching every word of a webpage you save.

A Favor, If I May

If you’ve made it this far I want to say thank you to you for caring so much about the app I’ve made. Plinky is the result of more than 1,500 hours of work. If that doesn’t emphasize how much of my heart, sweat, and tears are in Plinky, I’m not sure what will. I’m truly excited about the idea of spending another 1,500 hours making Plinky better for you, then 1,500 more hours after that.

If I may ask:

Please download Plinky and try the app. I would love to know what you love about Plinky, what can be improved, or what I can do to make Plinky an integral part of your life.
If you like the app, I would greatly appreciate a rating or review. Ratings decide the success or failure of apps the App Store, and as much as I hate to ask, I would like to succeed because that means I get to continue building an app that strives to make your links better.
Tell your friends. I hope it’s not too gauche to ask, but I genuinely believe that Plinky can help improve many people’s lives. Every person who tries Plinky may be a person who’s now using an app that makes their life a little better, and nothing in this world makes me happier getting a chance to help others.

Thank You

While you can say that I built this app, nothing in this world happens alone. I’ve had a lot of help along the way, and want to make sure anyone who’s helped even in the smallest way is honored in Plinky. Plinky has a Thank You section on the About Red Panda Club screen where I’ve assembled everyone who’s helped me while I’ve been building Plinky.

The rest of this post was written for me and my loved ones, but you’re free to read it as well.

I would like to first mention my wonderful fiancée and soon to be wife Colleen. Thank you for supporting me with your love, your advice, your daily feedback, and the hours of hands on help you provided over the last few months in creating and solidifying Plinky’s launch plan. I love you, and because of you my dream is now a reality.

Thank you to my family for cheering me on this whole time, without you I wouldn’t be the person I am today. Plinky is a personal expression of who I am and the way I want to help make the world a slightly easier to navigate place. If it wasn’t for you I wouldn’t have that perspective, so thank you for instilling those values in me.

Thank you to Joey Banks for being a great friend, for our weekly calls, and for your help in shaping Plinky’s App Store screenshots and website. Because of you I was able to show the world what I’ve built in the way that reflects what I wanted people to see. While I’m here bragging about my friend, if you’re looking for the world’s foremost expert in Figma, you should reach out to Joey.

Thank you to all of the beta testers who have provided endless ideas, feedback, and guidance over the last 18 months. Plinky wouldn’t look or work the way it does today without your amazing ideas, and of course your extremely helpful bug reports. If you’ve provided a suggestion during Plinky’s beta then odds are it’s already been implemented, or is on the Plinky roadmap I’ve constructed for the next year and beyond.

Thank you to anyone who’s helped me over the last few years, whether or not that involves Plinky. The last few years haven’t been easy, and while I can’t always be strong, I can’t always be brave, what I can always be is grateful and appreciative.

Now if I may leave you with a few words: Be good to others, help those in need, and save a few links.

The Reasoning Computer

Joe Fabisevich — Fri, 10 Nov 2023 12:00:00 GMT

The Turing test is dead, and we killed it. The Turing test is a test of a machine’s ability to exhibit intelligent behavior equivalent to, or indistinguishable from, that of a human. From the 1940s ¹ to the 2010s people programmed computers, and computers could only do what they were programmed to do in a rules-based deterministic manner. Sometimes a person would program the computer and it would do something unexpected, but 100 out of 100 times the computer was doing what it was programmed to do whether the person liked it or not. While there has been experimentation with what today we call AI since the 1950s, those machines were a long ways away from passing the Turing test.

Why does using ChatGPT feel more like a conversation with the smartest person you know than a computer? It’s because ChatGPT doesn’t solve problems deterministically the way a programmed computer does, it solves them probabilistically. ² ChatGPT demonstrates the ability to think about something in a logical, sensible way, the definition of reasoning. ³

We’ve created something completely new here, a reasoning computer. ⁴

Working With A Reasoning Computer

There are so many political, societal, economic, and ethical implications of Large Language Models (LLMs), 5,000 words wouldn’t be enough to cover all those thoughts. (Trust me, there’s a much longer post sitting in my drafts.) But what’s really captivated me is why a reasoning computer really is different than anything we’ve used before, a conclusion I could only arrive at through experience.

ChatGPT has been an essential tool for me over the last month, especially over the last week as I’ve been building Plinky’s browser extension. I’m a very experienced iOS developer but have little experience with web development. I know enough TypeScript and React to cobble together something with lots of help and guidance, but it will take me much longer than someone who knows what they’re doing.

A browser extension is important for Plinky to be successful though, which presents a unique challenge: I know what I want, I know how to describe it, I don’t quite know how to get it, but I will know when ChatGPT gives me the wrong answer so with some nudging I can get what I’m looking for. Here’s why the process of pairing with ChatGPT works, and how it helped me build a fully functional browser extension that lives up to my standards in less than a week. (With far less frustration than if you took away the tool and gave me a whole month.)

A simple browser extension to save links to Plinky’s database is a much smaller problem than building a whole app. The problem is self-contained, which makes it quick and easy to test ChatGPT’s results and see if the output matches my expectations. In fields like mathematics or computer science it’s generally easier to verify a solution’s correctness than come up with a solution in the first place.
I may be a novice web developer but I’m a great programmer. Even in a domain where I’m not comfortable I can describe the problem I’m trying to solve, assess whether a solution is good, do some research (on my own or with the aid of Perplexity and ChatGPT), and nudge the reasoning computer in the right direction.
This isn’t a process where I ask for something and am given exactly what I want, but I can promise you it’s much easier than becoming a good enough TypeScript developer to build the high quality browser extension I want.
Little by little the browser extension looks and works more and more how I want it to be, until it does exactly what I want it to do.
The whole process is interactive so I’m learning about how to get to the right solution. Not only do I have what I want, but this iteration made me a better web developer, I started off only knowing what the wrong output looks like but now I also know how the correct solution should look.

This is just one example of how I was able to accomplish something I previously wouldn’t have been able to do thanks to an LLM, the number of tasks I turn to LLMs for is growing every day. The same way that GPS becoming ever-present means I haven’t opened a map in almost two decades, I find myself turning to ChatGPT or Perplexity rather than opening Google and clicking a bunch of links to find answers. I used to do my own research, I used to be the reasoning machine, but now I’m offloading more and more of that work to Large Language Models.

How Can A Reasoning Computer Even Work?

People will say that ChatGPT can’t do math, and that’s true in the most literal sense. A Large Language Model may not know what addition and subtraction mean to a human, but it can use tools and synthesize the correct results to add and subtract numbers better than a person. Similarly people point out that ChatGPT can’t read, because it’s just a stochastic parrot that means it can’t provide intelligible output. It’s true that LLMs are complex statistical models, yet despite ChatGPT not knowing English from Urdu the way people do it’s still capable of translating from English to Urdu to Russian to French in a way that I never would be able to. The fact that Github Copilot ⁵ doesn’t actually know the difference between JavaScript and Swift hasn’t stopped it from making programmers 55% faster at coding.

Large Language Models use a different form of problem solving that starts with inputs and extrapolates technique. That’s the reverse of how humans believe they develop their skills, if you study hard, read a lot, and put in enough hours as a writer you too can become the next Faulkner or Shakespeare. But think about the way you first learned your native language, you listened and watched the world around you for 1-2 years, then reverse-engineered how the technique works. We’re reasoning machines too, the difference is that the entirety of the internet wasn’t preloaded into our brains the way it was into an LLM. (For the best, I don’t know if you know but there’s some bad shit on the internet.)

When we say ChatGPT can’t do this or ChatGPT can’t do that what we’re doing is anthropomorphizing flaws onto the system, derived from our own experiences of solving problems successfully. The problem solving process may be difficult for people to understand because this is the first computer that doesn’t do exactly what you tell it to do. Our intuitions may view this as a flaw, but OpenAI loading the whole internet into ChatGPT and creating a simple model for how to think rather than directly programming the machine is the reason this computer is incredibly useful in new and previously unexplored ways.

Simon Willison says that these tools make you more ambitious with what you can accomplish, and I’d like to build upon his axiom. When you have a reasoning computer you only have to know what the wrong result looks like, not how to get the right result, and that alone has the power to change how society solves problems.

Footnotes

Ada Lovelace deserves credit for writing the world’s first computer program 100 years before ENIAC, but in this context I’m using the timeframe of the 1940s to focus the post on generally programmable computers. ↩
It’s perfectly fair to debate whether this is how the inner-machinations of ChatGPT work, but I feel very strongly that at a minimum you can say this about the output ChatGPT provides. ↩
This isn’t because ChatGPT is sentient, but in all likelihood because it was trained on a corpus of human-generated data. It’s difficult to define “thinking” in this context, my personal view is that there is no thinking without sentience, but in this context what I call thinking isn’t the low-level internal machinations of ChatGPT, but one level higher — the step by step token output process that people using ChatGPT see in the process of getting their result. ↩
I’d like to co-credit Joe Ugowe with coining this term, it stemmed from a wide-reaching discussion we had last night about our experiences with ChatGPT and Large Language Models. ↩
Github Copilot is a Large Language Model product like ChatGPT, but trained with a coding-specific focus, which allows it to be integrated into a whole suite of Microsoft’s programming-related tools and platforms. ↩

Twitter Space: Making Data Storage Magical with Boutique

Joe Fabisevich — Mon, 26 Sep 2022 12:00:00 GMT

I joined Rizel Scarlett and Christina Warren of GitHub on GitHub’s Open Source Friday Twitter Space. We had a wide-ranging conversation about my journey from working at Twitter on societal health issues to becoming an indie developer, and how my story involves open source at it’s heart. I built Boutique to be a “magical” persistence library, along with its companion Bodega, which led me to discover the harsher reality of being an open source maintainer, and working full time on open source wasn’t my dream despite my love of open source.

Reflections On An Open Source Project

Joe Fabisevich — Tue, 06 Sep 2022 12:00:00 GMT

I’ve been working on Boutique and Bodega for much of the last three months, officially celebrating the launch of Boutique and Bodega v2 today. If you’d like to learn more about what’s new you can read about it in this tweet storm, or read a quick rundown below ¹. But this post isn’t about Boutique and Bodega, it’s about the process of building Boutique and Bodega.

If you’d asked me in April if I’d spend three months this year working on an open source project, I would have said no way. I left my job at Twitter to be an indie developer building apps that represent my vision of personal productivity, but life is funny sometimes. Life teaches the same lesson over and over again — you can’t predict what’ll be important to you at any point in time. I built something to answer my own question, “what does a good SwiftUI architecture would look like?” for my own apps, and that’s what came to be Boutique. But Boutique has blossomed into much more than just a new architecture, it’s become a whole new way to build persistence layers, SwiftUI apps, and for me its created a community of people who find my work valuable. Boutique has quickly become a key part of my present and future app development plans, while remaining simple and approachable through many iterations. I’ve already integrated Boutique into more than half a dozen of my own apps, notably without many issues or much work, and every day I hear from people about how they’re using it as well.

I can’t say it’s all been ups though, there have been plenty of downs as well. I’m writing this post not with the intention of convincing you to build an open source project, nor am I trying to dissuade you from participating in open source. I’m aiming to provide a balanced perspective because I would like nothing more than to see you build something that’s important to you, to leave your dent in the universe. If that dent takes the shape of open source project then it would be an honor to have provided a head start based on what I’ve learned, knowing better what to expect than I did.

"Running a successful open source project is just Good Will Hunting in reverse, where you start out as a respected genius and end up being a janitor who gets into fights."

Quote attributed to @cra, and I don't think I've ever seen anything more true posted.
— Jens Axboe (@axboe) August 12, 2022

#1. When you open source something you plan to support, double your estimates.

As Big Daddy Kane would say, open source ain’t easy. The rapper was ahead of his time, and while it’s hard to believe, he was actually talking about me and my project planning-related difficulties.

When I started building Boutique it was a library just for me, something meant to provide a solution in the nascent and ambiguous space of SwiftUI app architecture. As I started to show Boutique to people in a private beta I was greeted with great ideas and improvements. I was able to implement their suggestions rather quickly, but nothing could prepare me for the amount of work that it takes to make something that works for the myriad of use cases that a general-purpose data storage library needs to support.

Boutique’s public launch was greeted with a lot of praise, and even more ideas. Boutique is intentionally not prescriptive, but it does have a rigid and powerful API. It’s meant to be an architectural piece of the puzzle, not something you interact with all the time, but that wasn’t always clear to many people who checked it out. People are used to solutions matching their previous mental models, and so they would find clever ways to misuse an API I thought couldn’t be misused.

Boutique’s goal is to be the only persistence library your app needs, something I emphasized heavily in every piece of documentation. Everything you need should be provided out the box, but I still saw people adding additional metadata to UserDefaults or their current database rather than building a model to represent additional information and storing it in Boutique. They weren’t wrong but I definitely wouldn’t say they were right, and I came to realize that a part of this confusion emerged from people leaning on old patterns and intuitions. I knew I had to fix that.

I believe that when someone doesn’t understand something you’re trying to teach them it means you haven’t yet brought them to where they need to be. I resolved to make the v2 API even clearer, sanding down rough edges and making it easier to compose functions, that way you would have less to learn and less to misuse. On top of that I wanted to provide a lot of documentation so people could develop a good mental model, have a lot of help getting started, and even developed step by step tutorials for common problems.

The quality of v2 is much higher, the library is more thought out, but this all took a lot of time and a lot of energy. What had started off as a six week project ballooned into three months of my life. We’ll discuss why working on Boutique became emotionally overwhelming in Lesson 3, but it’s worth noting that open source adds layers of stress. When you’re trying to make something that has wide reach you have to account for answering support requests, writing documentation you don’t personally need but will lower support volume, building features you won’t use, and more. It will help you become a better developer as we discuss in Lesson 4, but it will absolutely require a lot more time than your intuition tells you it will.

I still have some open questions that I don’t have answers for, but they’re worth considering if you want to start your own open source project.

Project Planning

When starting a project without a defined endpoint how do you make good estimates?
Given the often amorphous nature of an open source project how do you measure progress?

Energy

Knowing your energy and focus are finite resources, how do you choose what to work on?
What’s an ideal pace for you, how can you sustain your energy levels, and how do disconnect and recharge?

Focus

How can you delegate tasks you don’t want to do, the ones that may lead you to become a bottleneck?
How do you get people’s help so you can delegate those tasks?
How do you lean into your strengths to stay satisfied to avoid burn out?

#2. Nail the marketing, and keep pushing

I’ve been hinting at this for weeks, but the day’s finally arrived. Today I’m announcing not one, but five things. Model View Controller Store, Boutique, Bodega, a blog post, and a demo app that help you learn about all of these. Let’s thread this up! 🧵
— ✨ Joe Fabisevich ✨ (@mergesort) June 22, 2022

I launched Boutique, Bodega, and a blog post explaining the idea of a Model View Controller Store architecture together with a tweet storm that went semi-viral. I’d expected to get in front of a few hundred people, but thanks to utility of my projects, the quality of my writing, and creating a compelling thread that showed people the value of my work, a lot of what I had created had resonated with the iOS development community. With the help of friends and community members who’d watched me working tirelessly for weeks the project ended up reaching beyond my orbit, showing up in popular community newsletters, YouTube videos, and the GitHub team even reached out to me to setup a Twitter Space interview to discuss my open source work. (Scheduled for later this week).

Many things are launched on the internet never to be seen again, but I was committed to pushing Boutique forward knowing that this idea had the potential to change the way people build iOS and Mac apps. Over the coming weeks I leveraged my moderately sized Twitter following to keep people up to date with how v2 development was going. I would tweet about what developing an open source project looks like in real time, the good and the bad. I shared novel use cases for Boutique, people’s positive testimonials about using the library, and even leveraged the opportunity to show people cool Swift features that I’d been working with that could help them in their day to day work. This is very aligned with my vision for building my business with a silly name (Red Panda Club). I want to build apps, sell products I genuinely believe will help people be better versions of themselves, and teach people along the way to show them how they too can build amazing things. This is a core belief of mine and a style of content marketing that suits and fulfills me, it’s the reason I’m writing posts like this on build.ms.

I can say that the launch was incredibly positive, and I only have one regret. I created my GitHub Sponsors account about a week after the project went live, and that delay taught me that timing is everything. Boutique created a lot of value for people as evidenced by all of the people now using it in their apps, but I only managed to generate $17/month in recurring donations for all the work I’d done. While making money wasn’t my intention (and I honestly never expected random people on the internet to give me money), I wonder if I had pitched my GitHub Sponsors account at launch could I have ridden the wave of virality to build another revenue stream?

#3. Open source can be quite lonely

Working on Boutique felt very isolating, even with friends, family, and community members following along. I spent almost all of my waking hours working on a project by myself, and even when people asked me about my project there was a level of disconnect in terms of passion. That of course makes sense, this project was everything to me in the moment, and their only connection to Boutique is that they care about me. When you work at a company it really is all about the people. There’s a shared sense of camaraderie, or at worst a shared sense of misery. While I would never want to be miserable with others, the only thing worse is being miserable by yourself.

Some personal context

I happened to be going through a lot at the time.

I was seeing doctors multiple times a week for an ongoing all-consuming neurological issue, and fighting with the insane American medical system to get the proper care I needed.

I left my job at Twitter a few months ago to work for myself as an indie developer to both focus on my health and happiness. While I’ve been very happy with the decision, there have had a lot of adjustments in my life because of that.

My girlfriend and I were looking for a place to move into together (cheers, we did it, I’m so excited. 🎉).

Life events that have made my friends less available, and it was hitting me quite hard emotionally.

To be completely transparent there were days where I was crying from the physical pain and the loneliness of not having time, energy, or emotional space for the people I care so much about. Thank you to my amazing partner for all the support, you are truly a one of a kind person, my one of a kind person.

I don’t list all of those experiences because it’s what you should expect when you work on an open source project, but you will no doubt have some amount of other responsibilities. And another personal aside, if I’m being completely honest, I’m still surprised by the fact that I was able to build a successful open source project despite all of those obstacles.

When I left my job, I expected to lean on community to fill the void of the meaningful goals and shared experience I used to get from my work. I’m lucky enough to be a member of many supportive communities, locally and online, but the reason I felt so lonely when I was working on Boutique was that community fulfills a different need than friendship, family, or a workplace where I felt very accepted. There aren’t many feedback mechanisms in open source, in fact the feedback loop you have isn’t very tight and the interactions you have can often feel impersonal in part because they have a transactional nature to them. This is true any time you work by yourself, but an open source project where you’re the only major contributor with no cross-functional counterparts seemed to amplify this feeling even more. I left my employed life so I could foster more connections with people who matter to me, and it stung over and over again to feel more disconnected from people while I worked on something those very same people were using.

Open source isn’t designed to foster connection. For example, every time I received a GitHub Issue I felt like I was letting someone down. Without fail every time I responded to someone’s questions or bug reports the interaction was incredibly positive, even complimentary of my response. But getting to a solution often required a lot of work, and there was no real tangible reward as the human brain is trained to expect. When you consider the vulnerable act of putting your work out into the world, adding a dash of anxious personality, with a hint of feeling low due to external factors, that’s a recipe for negative feelings.

The community did throw me a life preserver when I needed it though. Boutique has been a solid investment into my business, but it also feels really special to hear how my code is being used in people’s apps. Every few days someone tells me they’ve started to use Boutique, tells me about about a novel use case that was made easy thanks to Boutique, but one person left me feeling rather emotional. An iOS developer reached out to me about integrating Boutique into one of his apps. He was working with a physical therapist who’s building an app for people dealing with nerve-related issues in their neck, incredibly similar to the neurological issues I’ve been dealing with. When I told my girlfriend she reminded me that having this kind of personal impact on people is rare, and the next time I’m feeling low I should remember that my code is helping people, sometimes even people who are going through the same struggles I am.

As always she was completely right (please don’t use this against me in the future), and for every person who messages me there are others who I’ll never hear from. The next time I’m beating myself up over a bug or a deadline I’ll remember that there are people who are grateful for my work, and for me.

#4. You become a better developer by thinking open source

I believe that you shouldn’t write code for the specific purpose of being testable, but that testable code often ends up having a better API surface due to the mindset of thinking about how some code can be tested. I have the same feelings about open source, you shouldn’t write code with the intention of open sourcing it, but the practice of writing code as if it could be open sourced leads to higher quality code*** ². Even if you never intend to open source a piece of code, writing it with the possibility in mind will lead to a well thought out API and a more modular structure. You will be forced to clean up your code, handle errors, and consider use cases that someone may want to layer atop your code.

Beyond the code, there’s a lot of work that goes into maintaining a successful open source project. The project management aspect comes to mind, but there are also many technical skills to learn. I’d never used Apple’s docc documentation library, but I learned the ins and outs to provide high quality documentation for Boutique v2. I automated the documentation updates by wiring up GitHub Actions, spending a couple of days to learn how to use the tool effectively. I even solidified my understanding of semantic versioning now that I had a wide-reaching project that people depended on, as compared to the devil may care attitude I had before.

There was also a lot to learn based on what Boutique’s users were asking for. The first version of my library used files on the file system as a persistence layer, but that proved to be difficult to scale beyond storing a few thousand objects. That drove me to build a version of Boutique that was backed by SQLite, building a fully working prototype in only a few hours. I read everything I could find about SQLite over the next couple of days to optimize my solution, playing into my strength of curiosity and thirst for learning. This would have never arisen organically, and what I learned led to me building the StorageEngine abstraction that underpins all of Boutique and Bodega now. With this I was able to build a pathway for people who are using databases like Core Data or Realm to use Boutique, a cornerstone of the v2 release. The library is much stronger because of the external feedback I received, including code reviews and contributions. All of this is something that never would have happened if I hadn’t open sourced my code, code that is now essential infrastructure for my apps going forward.

I learned a lot over my three months of being an open source developer, and after going through all of that, the truth is I don’t think I want to be an open source developer. I’ll continue to open source code, but with much less of the commitment that I took upon myself for this project. Boutique and Bodega will continue to be supported, but I won’t be adding new features at the same pace. They don’t need a revolutionary amount of new work, so I’ll mostly focus on my use cases rather than the needs of others going forward. So much more than code goes into building a successful open source project, and while I enjoyed many parts of the project, I was ultimately left unfulfilled in the ways that I want to feel fulfilled as a person.

My love for solving problems and teaching is why I thought open source would be a great fit for me. I learned that there’s more to being an open source maintainer than sharing code and helping people, and unfortunately those other parts don’t motivate me. But that won’t deter me from continuing to open source code because open source is built upon the idea that putting something out in the world can help people in ways you never would have expected. If I come up with a novel idea in the process of building my apps or if I learn something new that I think will be valuable to others, you can be sure I’ll open source it.

For now I’ll go back to my true passion, building my beloved apps and products like Plinky — stay tuned for more on that.

Footnotes

The new version of Boutique brings
- UIKit and AppKit support!
- Two new property wrappers (@StoredValue and @AsyncStoredValue) to help you store individual values
- The ability to chain .add() and .remove() operations, not only providing a simpler and clearer API but notable performance improvements.
- Even more performance gains thanks to Boutique now defaulting to storing items using SQLite. Boutique now has the ability to BYOD, bring your own database. You can now use whatever persistence layer you like, simply by conforming to Bodega’s new StorageEngine protocol. Whether you’re using Core Data, Realm, or even remote storage solutions like CloudKit you can quickly build a StorageEngine that matches your schema and start using Boutique today.
↩
A GIANT asterisk here, this is a completely subjective statement. ↩

Model View Controller Store: Reinventing MVC for SwiftUI with Boutique

Joe Fabisevich — Wed, 22 Jun 2022 12:00:00 GMT

This Twitter thread offers a concise high level 13-tweet summary of this post’s announcements, but you miss out on a lot of important detail that I highly recommend reading if you plan to start using the libraries I’ve developed and introduce in this post, or if you’d like to read an interesting technical walkthrough.

This post was updated on August 22, 2022 to reflect the v2 release of Boutique and related API changes.

Apple has never provided a blessed architecture for SwiftUI, and many developers have spent thousands of hours filling the gaps with their own ideas. A familiar approach for many developers is to take the MVVM pattern many people adopted in their UIKit/AppKit apps and translate it to the needs of SwiftUI. That can work well enough, but you begin to see some cracks in the architecture when you need to manage state and data flow due to how heavily SwiftUI leans on having a single source of truth. Others have taken the path of integrating powerful libraries such as The Composable Architecture which provide you with the tools to reason about your entire application. TCA takes inspiration from redux, more specifically The Elm Architecture, two patterns that are rather incredible in how they allow you to define your entire application as a tree of state. But TCA’s great power comes with great responsibility a very high learning curve, which can make it difficult to learn personally. TCA’s goals are much more of a fit for solving problems with a very high level of complexity, which may not be necessary for every app.

When it comes to developer ergonomics and program provability MVVM and TCA live on opposite ends of the spectrum. MVVM is lenient and depends on convention while TCA apps are built with rigidity in mind to guarantee correctness. This post isn’t meant to be a tour of architectures though, I’ve mentioned those two patterns to show that there’s a spectrum of how we develop software, and I believe there’s room for something in between.

If SwiftUI shows us anything it’s that declarative programming is the future of software development, and we need an approach to software development that leans into the strengths of the paradigm without being overly constrictive. What’s needed isn’t a whole new architecture, but to bring together tried and true patterns with a new concept, the Store. The Store is a very minimal yet powerful layer, which means the rest of your application’s code can remain almost entirely unchanged. Your apps are yours, they are your expression of creativity, and you shouldn’t have to change how you write code to turn your ideas into software.

The Store will be the heart of your app’s data, and thanks to the declarative nature of SwiftUI an app’s user interface is driven by its data. You can think the Store as the storage for your model objects, in SwiftUI this would be your single source of truth. If you model your data correctly then your user interface will always do what you expect it to do. That relationship between data and user interface is why Views having a single source of truth is so important.

I’ve built a batteries-included Store that comes with everything you’ll need out of the box called Boutique to be the foundation for that data. Boutique does no behind the scenes magic and doesn’t resort to shenanigans like runtime hacking to achieve a great developer experience. Our Store is extremely simple and has no complicated abstractions, you’ll be surprised how little there is to learn. There entire API surface is only one public property, an array of items, and only three functions, add(), remove(), and removeAll(). Once you experience Boutique it becomes a must-have feature for any state-driven app you build. We’ll dive much deeper into how the Store works under the hood to make this possible later in this post, build a Model View Controller Store app to see how it all comes together.

Boutique’s Store is a dual-layered memory and disk cache which lets you build apps that update in real time with full offline storage and an incredibly simple API in only a few lines of code. That may sound a bit fancy, but all it means is that when you save an item into the Store, it also saves that item to disk. This persistence is powered under the hood by Bodega, an actor-based library I’ve developed for saving data or Codable objects to disk. In this post we’ll use Boutique to show how the Store integrates into your apps.

The pattern and concepts are familiar and straightforward whether you’ve been a programmer for a few months or have been writing code for decades. After integrating this architecture into multiple apps without a hitch over the last few months I feel confident sharing it, and open sourcing the libraries that make it easy to build realtime offline-ready apps with just a few lines of code.

Model View Controller Store

Model View Controller Store is a rethinking of an architecture familiar to iOS developers MVC, for SwiftUI. While this post discusses SwiftUI, all of these techniques are applicable for building a UIKit or AppKit app. You can build apps across many platforms using this pattern, in fact the C from MVCS is inspired by Data Controllers rather than ViewControllers, but in this post we’ll focus on SwiftUI. Your app’s Models and Views will require no changes to your mental model when you think about a Model or View in a SwiftUI app, but we’ll be adding the Store to our apps. The combination of MVC and a Store bound together by a simple API allows a developer to give their app a straightforward and well-defined data architecture to create an app that’s incredibly easy to reason about.

The best way to explain Model View Controller Store is to show you what it is. The idea is so small that you may even be an expert before this post is over, there’s actually very little to learn. Model View Controller Store doesn’t require you to change your apps, and I’m going to use Boutique for the Store in our app.

You may prefer use Boutique on its own without Controllers, Model View Store is a perfectly acceptable architecture that some people will prefer. While I prefer having a data controller to mediate data and interactions between different parts of the app, especially as apps get more complex, it’s not a prerequisite to using Boutique’s Store in your app. We’ll touch on using Boutique to create a Model View Store architecture in the Store section of the post, and discuss what the Store can bring to any app.

Let’s Build An App

To demonstrate Model View Controller Store in practice we’ll walk through a simple app that’s representative of most apps people work on. You can find the full source code available on Github, but we’ll also walk through a condensed version below.

This app will allow us to

Query an API for a red panda image.
Favorite the red panda the API sent us, saving the image and associated metadata to our Store.
See that when we save the red panda to our Store, the state changes are rendered across two separate views.
Remove a red panda, deleting the image and associated metadata from our Store.
See that when we remove the red panda to our Store the state change is rendered due to the state change.
If we relaunch the app all of our favorited red pandas will be there because the Store not only saves data in-memory but also cached on disk.

Model

You can assume our app has a RemoteImage model to represent a remote image resource, we’ll use it when we fetch and save our red panda images.

struct RemoteImage: Codable, Equatable, Identifiable {
	let createdAt: Date
	let url: URL
	let width: Float
	let height: Float
	let dataRepresentation: Data

	var id: String {
		url.absoluteString
	}
}

Store

We’ll create our Store, using the Store provided by Boutique, though if you’d like to build your own it’s possible too.¹ The Store has a readonly array of items and only three operations to add(), remove(), and removeAll(). What that means is modeling our data is easy, and our views will always render what we expect due to that data being well-modeled. The Store’s items property is a @Published property, and because of that our Views update in realtime without having to build any observable behaviors, it’s almost magical to watch.

To create a Store all you need is a storage and a cacheIdentifier.

The storage parameter is of the type StorageEngine, a data storage mechanism provided out of the box by Bodega. A StorageEngine can be a database, but it doesn’t have to be. Bodega provides two built-in StorageEngine options, DiskStorageEngine and SQLiteStorageEngine. DiskStorageEngine works by saving your data as files to the file system, and SQLiteStorageEngine creates an SQLite database as the underlying storage mechanism. If you use either of these you’ll never have to think about how the data is being stored, but Boutique v2 introduces the concept of BYOD (Bring Your Own Database), allowing you to build your own StorageEngine. You can create a CoreDataStorageEngine, a RealmStorageEngine, or even a CloudKitStorageEngine that matches your app’s backend schema, the possibilities are endless. Bodega’s documentation provides much more context, but for the purposes of our app we’ll use the suggested default, SQLiteStorageEngine.

The cacheIdentifier is a KeyPath<Model, String> that your model must provide. That may seem unconventional at first, so let’s break it down. Much like how protocols enforce a contract, the KeyPath is doing the same for our model. To be added to our Store and saved to disk our models must conform to Codable & Equatable, both of which are reasonable constraints given the data has to be serializable and searchable. But what we’re trying to avoid is making our models have to conform to a specialized caching protocol, we want to be able to save any ol’ object you already have in your app. Instead of creating a protocol like Storable, we instead ask the model to tell us how we can derive a unique string which will be used as a key when storing the item.

In this case we’ll generate the cacheIdentifier by using the absoluteString of RemoteImage.url. If you try to save an item with the same cacheIdentifier as an item that already exists in the Store the newer item will override the older saved item. Because of that it’s important that your cacheIdentifier is unique, but it also means that our Store will only need an add() method and no update(), with no checks necessary to see if an item is in the Store before adding a new item. ²

// You can create a Store anywhere but for a globally available Stores like an image cache
// I like to do it in an extension on Store so you can later reference it as `.imagesStore`.
extension Store where Item == RemoteImage {

	static let imagesStore = Store<RemoteImage>(
		storage: SQLiteStorageEngine.default(appendingPath: "Items"),
		cacheIdentifier: \.id
	)

}

For models that conform to Identifiable where the id is a String we’ve we can infer the cacheIdentifier. That leads us to a nice ergonomic improvement where we skip the Store’s cacheIdentifier parameter, instead writing:

static let imagesStore = Store<RemoteImage>(
	storage: SQLiteStorageEngine.default(appendingPath: "Items")
)

You can initialize your Store anywhere you like, but I chose to initialize the imagesStore in an extension on Store. Caching images is often a task that you want to have available globally, and by choosing to initialize it on Store the we can drop the Store. prefix when we initialize it, leaving us with this aesthetically pleasing @Stored(in: .imagesStore) syntax.

You may be asking yourself “can I put all my data in one store” and the answer is sure, but it’s not recommended. I highly recommend making many small stores, especially for a SwiftUI app. Any SwiftUI app, not just an app powered by Boutique’s Store, will often have to re-render state changes if the source of truth is too centralized. To work within the frameworks’ constraints, what I recommend is using a few smaller stores scoped to a certain model, or usage domain.

A Model View Store Interlude

Before we get to the Controller I’d like to talk about Model View Store. If you were to pursue the Model View Store approach then much of the Controller functionality would move to the View. If you’re building an app that focuses on rendering local data you can find success using the Model View Store pattern. But as your app grows in scope, especially if it’s interfacing with other data sources such as APIs or external storage services such as CloudKit then the Controller layer will become invaluable. That’s because each View will have to duplicate the related logic, and a Controller will be able to not only centralize and prevent you from duplicating that logic, but provide you a domain-specific object for handling those operations.

If you’re prototyping or building something simple Model View Store may be enough for you, but you may hit some growing pains as your app scales in complexity, and at that point I recommend incorporating a layer of abstraction for handling the business logic and interactions in your app.

Controller

That’s all the setup we needed to create the Store in Model View Controller Store, only one line of code. There are many opinions about the correct shape for a Controller to take on, and that’s why Controllers come in many flavors. If you ask 10 programmers how they would design their Controller you’ll get 12 answers. Some people prefer Thin Controllers, others lean towards Thick Controllers, and there’s also Data controllers or Model Controllers. Some people don’t even like to use the Controller nomenclature, they name these intermediate objects XYZManager, ABCFeature, or an object name specific to their app. As I said that your apps are yours and the way I shape them is your choice, and we don’t need to impose an overly specific Controller paradigm to build a Model View Controller Store app.

Below we’ll create something based on my preference of using Data Controllers. Our Controller will act as a centralized pass-through layer for operations such as hitting API to fetch images, saving those images to our Store, and handling all of the interactions related to images. We’ve included other CRUD operations such as delete or delete all, as Data Controllers often do.

/// A controller that allows you to fetch images remotely, and save or delete them from a `Store`.
final class ImagesController: ObservableObject {

	/// The `Store` that we'll be using to save images.
	@Stored(in: .imagesStore) var images

	/// Fetches `RemoteImage` from the API, providing the user with a red panda if the request succeeds.
	/// - Returns: The `RemoteImage` requested.
	func fetchImage() async throws -> RemoteImage {
		// Hit the API that provides you a random image's metadata
		let imageURL = URL(string: "https://image.redpanda.club/random/json")!
		let randomImageRequest = URLRequest(url: imageURL)
		let (imageResponse, _) = try await URLSession.shared.data(for: randomImageRequest)

		return RemoteImage(createdAt: .now, url: imageResponse.url, width: imageResponse.width, height: imageResponse.height, imageData: imageResponse.imageData)
	}

	/// Saves an image to the `Store` in memory and on disk.
	func saveImage(image: RemoteImage) async throws {
		try await self.$images.add(image)
	}

	/// Removes one image from the `Store` in memory and on disk.
	func removeImage(image: RemoteImage) async throws {
		try await self.$images.remove(image)
	}

	/// Removes all of the images from the `Store` in memory and on disk.
	func clearAllImages() async throws {
		try await self.$images.removeAll()
	}

}

Here we’ve referenced .imagesStore inside of ImagesController, but you may prefer to decouple your Store from the Controller it’s used in. I would personally recommend taking this approach, and it’s easily doable, only requiring you to change three lines of code.

final class ImagesController: ObservableObject {

	// This line of code goes away
	// @Stored(in: .imagesStore) var images

	// Instead we create an uninitialized property and a new initializer
	@Stored var images: [RemoteImage]

	init(store: Store<RemoteImage>) {
		self._images = Stored(in: store)
	}
	
	// The rest of the controller looks exactly the same
}

Injecting a Store into your Controller means that your Controller’s actions now act independently from their state, and as a result become more testable. You can even create test Stores that are injected for the purposes of unit testing.³ Testability is usually the primary selling point for using MVVM, but we’ve obviated the need for a ViewModel. Our data manipulation and business logic resides in our Controller, and our Views will interface directly with the Controller. This allows us to remove one layer of abstraction from each View, no longer needing to pair a ViewModel with every View. And speaking of the View…

View

Now we have a Store that stores our RemoteImages, and an ImagesController that can fetch images for us. All we need is to render them so our users can look at some red pandas, and that’s a job for the View. To remind you our view will look like this. This code is a little different from the code on GitHub but it’s fundamentally the same, mainly some styling modifiers and additional state related to managing the view’s user experience were removed for brevity’s sake.

We’ll build a card view that looks like this, with three interactions.

When the view appears, we call imagesController. fetchImage() to set the current displayed image.
When the user taps Fetch, we call the same function to fetch a new random red panda.
When the user taps Favorite, we call imagesController.saveImage (image: self.currentImage) to save the current image to the Store.⁴

struct RedPandaCardView: View {

	@StateObject private var imagesController = ImagesController()

	@State private var currentImage: RemoteImage

	var body: some View {
		VStack {
			RemoteImageView(image: currentImage)
				.aspectRatio(CGFloat(currentImage.height / currentImage.width), contentMode: .fit)
				.primaryBorder()
				.cornerRadius(8.0)

			Spacer()

			Button(action: {
				Task {
					try await self.setCurrentImage()
				}
			}, label: {
				Label("Fetch", systemImage: "arrow.clockwise.circle")
					.font(.title)
					.frame(height: 52.0)
					.background(Color.palette.primary)
			})

			Button(action: {
				Task {
					try await self.imagesController.saveImage(image: self.currentImage)
					try await self.setCurrentImage()
				}
			}, label: {
				Label("Favorite", systemImage: "star.circle")
					.font(.title)
					.frame(height: 52.0)
					.background(Color.palette.secondary)
			})
		}
		.task({
			try? await self.setCurrentImage()
		})
	}
	
	private func setCurrentImage() async throws {
		self.currentImage = try await self.imagesController.fetchImage()
	}

}

In the RedPandaCardView section I wrote there were three interactions.

3. When the user taps Favorite, we call imagesController. saveImage (image: self.currentImage) to save the current image to the Store.

But technically there’s a step 4.

When the user taps Favorite the changes will propagate to anyone who’s using that Store to power their view. We’re going to build a FavoritesCarouselView that has a reference to the same Store, that way we maintain one source of truth. Even though our two Views have two different instances of ImagesController, those ImagesController instances share the same underlying Store. This means that when the RedPandaCardView sends an action to save the red panda image to our Store, the FavoritesCarouselView will automatically update with the newly favorited image in real time!


struct FavoritesCarouselView: View {

	@StateObject private var imagesController = ImagesController()

	var body: some View {
		VStack {
			HStack {
				Text("Favorites")
					.bold()

				Spacer()

				Button(action: {
					Task {
						try await imagesController.clearAllImages()
					}
				}, label: {
					Image(systemName: "xmark.circle.fill")
						.foregroundColor(.red)
				})
			}

			HStack {
				CarouselView(
					items: self.imagesController.images.sorted(by: { $0.createdAt > $1.createdAt}),
					contentView: { image in
						RemoteImageView(image: image)
							.primaryBorder()
							.centerCroppedCardStyle()
					}
				)
				.transition(.move(edge: .trailing))
				.animation(.default, value: self.imagesController.images)
			}
		}
	}

}

You’re probably thinking “this looks pretty much exactly like any SwiftUI app”, and reader, you are right. That’s the point. As linguists know one word can make a big difference, and in this case that one word is @Stored.

Editor’s note: From this point on the blog post is going to get more technical and it is not required reading for using Model View Controller Store. If you’re not interested in the underpinnings of the Store and @Stored you can skip to the conclusion.

Wandering Around The Boutique

So what is that @Stored? @Stored is a property wrapper that makes interacting with the Store go from straightforward to downright magical. But before we can get to the property wrapper, let’s walk through how the Store is built, that way we can see how @Stored layers on top of it.

Let’s break down how the Store is built.

public final class Store<Item: Codable & Equatable>: ObservableObject {

	// More code here…

	private let storageEngine: StorageEngine
	private let cacheIdentifier: KeyPath<Item, String>

	@MainActor @Published public private(set) var items: [Item] = []

	public init(storage: StorageEngine, cacheIdentifier: KeyPath<Item, String>) { … }

	public func add(_ item: Item) async throws { … }
	public func add(_ items: [Item]) async throws { … }
	public func remove(_ item: Item) async throws { … }
	public func remove(_ items: [Item]) async throws { … }
	public func removeAll() async throws { … }

	// More code here…

}

This is an abridged version of the Store, removing some details to make it easier to touch on the most important parts.

Store is an ObservableObject, which means it can publish any changes that occur to the Store’s @Published properties.
Store contains one @Published property, items, the array representing the items we’re storing.
All @Published property changes must dispatch on the main actor, so we provide items with a @MainActor annotation.
The access control of items is public private(set), that’s to ensure that all mutations occur by using add(), remove(), and removeAll().
Since items is public private(set) that means we can read and access items without any additional methods. The simplest API is one that doesn’t require additional abstraction, so there’s no reason to add superfluous methods for read operations, we can treat items just like any other array.
You can even use the $items Publisher to subscribe changes, and this is what makes it possible to build SwiftUI apps that automatically update everywhere from a single source of truth.

A few additional details that are relevant, but not as important to explore.

The storageEngine property is an on-disk cache provided by Bodega. This is what’s responsible for writing items to disk, all of which happens for you automatically. Because storageEngine is private you’ll never have to directly interact with it, but you can use it separately from the Store if you only want to save files to disk.

// Don't do this
try await self.$images.removeAll()
try await self.$images.add(images)

// Do this!
try await self.$images
	.removeAll()
	.add(images)
	.run()

Boutique provides a fluent syntax for chaining functions that modify items together. This provides performance benefits as each function call will modify items, and since items is annotated with @MainActor any modification will trigger observing SwiftUI Views to re-render. By using .run() to we’re able to tell the Store to use a different variant of removeAll() and add() that will run all of the chained commands together. This ensures a seamless user experience with the View batching together the modifications of items, redrawing the contents of your View only once.

That’s all you need to know about the Store, and when you break it down there’s nothing too complicated happening here. As a consumer of this API you never even have to deal with or understand any complexity, all you have to do is use the add() and remove() operations and you get the power of Store.

To recap

A single source of truth, full offline support, and real time state updates automatically. These are not three separate libraries, they’re one library and we’re calling it Boutique.

— Steve Jobs

We’ve finally reached the point where I explain @Stored, and here’s where we encounter some real complexity. It’s very important to state that you absolutely do not need to know this to use Boutique or to understand Model View Controller Store, I just found this to be an interesting technical challenge. 98% of the credit for this code goes to @harshil and @iankeen. Harshil provided the idea and strongly guided me to the initial implementation for the @Stored property wrapper, and Ian came up with the brilliant subscript that allows the property wrapper’s enclosing object to republish the underlying Store’s changes without adding five lines of boilerplate for a developer to write whenever creating a Store. A huge and heartfelt thank you to both of you.

@propertyWrapper
public struct Stored<Item: Codable & Equatable> {

	private let box: Box

	public init(in store: Store<Item>) {
		self.box = Box(store)
	}

	@MainActor
	public var wrappedValue: [Item] {
		box.store.items
	}

	public var projectedValue: Store<Item> {
		box.store
	}

	@MainActor public static subscript<Instance: ObservableObject>(
		_enclosingInstance instance: Instance,
		wrapped wrappedKeyPath: KeyPath<Instance, [Item]>,
		storage storageKeyPath: KeyPath<Instance, Stored>
	) -> [Item] where Instance.ObjectWillChangePublisher == ObservableObjectPublisher {
		let wrapper = instance[keyPath: storageKeyPath]

		if wrapper.box.cancellable == nil {
			wrapper.box.cancellable = wrapper.projectedValue
				.objectWillChange
				.sink(receiveValue: { [objectWillChange = instance.objectWillChange] in
					objectWillChange.send()
				})
		}

		return wrapper.wrappedValue
	}
}

As a reminder, this is what our usage of @Stored looks like.

final class ImagesController: ObservableObject {

	@Stored(in: .imagesStore) var images

	// More code here…

}

The wrappedValue is an array of the items in the Store, in our case images. This allows our Store’s items to be exposed to callers as images, providing a slick experience now that reading images is just like reading any other array.
The projectedValue is a representation of the Store which allows us to call self.$images.add(image) in a manner that doesn’t expose any of the underlying details.
The subscript is a trick I learned from @johnsundell’s post, and was able to implement with Ian’s help. The code looks rather complex but is simpler when you break it down into plain English. It’s important to know that if you have an ObservableObject inside of an ObservableObject, the outer ObservableObject has to manually republish the inner ObservableObjects changes for them to be reflected in your app. I honestly don’t know why this is the case, but it’s been well-documented as the way SwiftUI works.
In our subscript the first parameter is the _enclosingInstance, which is the object that holds a reference to this property wrapper. In our case that’s ImagesController, so when this subscript is invoked (transparently on any objectWillChange changes), ImagesController will republish changes from our Store. This technique is useful on it’s own, and I will be incorporating it into a @Republished property wrapper.⁵

Conclusion

Phew, that was a bit of a deep dive, so let’s come up for air and discuss at a high level what we’ve done. We talked about the tradeoffs of modern architectures used to build SwiftUI apps, and showed that there’s space for Model View Controller Store in between MVVM and TCA. We introduced a new concept, the Store, and a batteries-included implementation with everything you’ll need called Boutique that lets you build realtime offline-ready apps with just a few lines of code. We reviewed a condensed version of a full Model View Controller Store app, available on Github, and broke down its constituent parts, the Model, View, Controller, and Store. And then we did a technical breakdown of Boutique. It may look like there’s a lot here, but it takes a lot of work to make something simple to use.

As a developer you’ll get to take advantage of all this infrastructure to build SwiftUI apps in the same straightforward and familiar manner you’re used to, without making any changes or compromises. Model View Controller Store is so familiar that I’m almost hesitant to even label this a new architecture. Model View Controller Store is more of a modern day twist on an old architecture that’s been proven to work over decades. Please let me know if you’re using Boutique or Model View Controller Store in your apps, I’ve opened up Discussions on GitHub for Boutique. And if you have any thoughts, any ways to improve the what I’ve developed, I’m always available on Twitter. I welcome any and all polite discussions.

Thank you so much for reading all of this, and a special thank you to Conrad Stoll for the multiple editing passes, and Romain Pouclet for this post’s amazing header artwork. Most importantly, happy hacking! I can’t wait to see what you all build. 🧑🏿‍💻🧑🏼‍💻👩🏽‍💻🧑🏻‍💻👩🏼‍💻

Footnotes

It’s possible to create a Store backed by any database or storage system, or even no persistent storage system. Boutique’s Store and @Stored can serve as a good reference implementations for you to create a similar construct. Rather than creating a Store protocol I’ll give you a blueprint for defining your own Store in plain English, or you can read this section for a much more in depth explanation..
1. Define one property, @MainActor @Published public private(set) var items, to expose the underlying stored data.
2. Add five functions add(_ item: Item), add(_ items: [Item]), remove(_ item: Item), remove(_ items: [Item]), and removeAll() for the purposes of mutating the Store.
3. The @Stored property wrapper should be identical, though you can add your functionality based on the needs of your Store if you choose.
↩
Saving an item with the same cacheIdentifier as an item that already exists in the Store the newer item will override the older saved item. The same applies to saving two items at once with the same cacheIdentifier. Bodega is the library which powers Boutique’s SQLite storage, and it provides a CacheKey type that takes a URL or String, hashes it, and saves it to disk in a file-system safe manner. Since URLs can be 4096 characters and files on disk can only be 256 characters I recommend using this whenever using a URL as your cacheIdentifier, but using CacheKey shouldn’t be necessary otherwise unless your identifiers are Strings that are long strings, longer than 256 characters, or contain characters that aren’t file system safe. A shorter version of that, it’s almost always the smart move to use CacheKey. ↩
A nice tip for unit testing is to create a Store using the .temporaryDirectory, that way your data won’t be persisted past the tests’ execution. ↩
If you had a server responsible for syncing favorites this would be a good place to call API.save(image: image) as well. Since that’ll also be asynchronous you may take one of two strategies, both of which are valid.
1. Wait until you get a response from the API telling you an image has been saved to the server, this is especially easy when using async/await.
2. Add an isSynced boolean to your models and optimistically save your image to the Store before calling the API. When the API responds you would change isSynced from false to true, and show users in the user interface that their model has been synced to the server.
↩
@adam_zethraeus reached out to me and let me know that he’d built an @Republished property wrapper, and it is exactly what I would have extracted from this implementation so I thought it’d be useful share. ↩

Maximum Design For Minimal Effort

Joe Fabisevich — Wed, 15 Jun 2022 12:00:00 GMT

Whether you’re starting your design journey or if you’ve been doing design for years, nothing’s more important than the fundamentals. The fundamentals are what help you get from 0 to 60, and when it comes to design it turns out that that 60% may be all you need. You can create something really beautiful by understanding color, spacing, typography, and animation, which is what we’ll cover in this video. I gave this talk at Pursuit, while live coding, showing you how to take an app from stock UIKit to something beautiful in only 15 minutes. I’ve been told quite a few times by people I’ve shared this talk with that it was invaluable for them, so if you’ve ever opened up Figma and thought “I don’t know where to start”, you should take 15 minutes to watch.

And if you need inspiration, here’s a repository of resources I’ve put together to help you along your design journey.

Coding As Creative Expression

Joe Fabisevich — Sat, 21 May 2022 12:00:00 GMT

Is coding a science or an art?
— Matthew Garlington (@dejadu13) May 21, 2022

I’ve seen many versions of this question posed over the years, and to Matthew’s credit it’s a very good question. As you can see in the replies people translate their lived experience writing code and answer art or science based on however they conceptualize and practice programming. A few years ago MIT conducted a study that concluded “reading computer code is not the same as reading language”, answering the question of whether coding is art or science with a rigorously documented “both”. While I’m hard-pressed to argue with science, I’d like to provide a different answer, one that’s a little more conceptual.

The instinct to qualify coding as art comes from the practice of programming. While writing a program software developers make many choices, ones that rarely have hard and fast rules. As long as your program compiles and runs as expected, you can make any choice you want. It’s all human input, if you ask 100 developers to write a complex program they’ll write it 100 different ways. Heck, if you ask one developer 100 times they may write it 100 different ways. Code can create something beautiful, enable an amazing experience, and people will even call a piece of code elegant or exquisite. To someone in the arts this all sounds very familiar.

The instinct to qualify coding as a science comes from the output of a program. Developers desire deterministic results for their programs, when you provide an input to a program you expect to receive the same output every time. The practice of programming itself can be imprecise, and the same way that science operates in unknown space, building a program can often feel the same. Developers will try to minimize the ambiguity by using industry-tested practices, much the same that a scientist uses a standardized beaker rather than throwing some chemicals in an unclean cup and seeing what happens. When put together that truly sounds like the practice of science.

What we’ve found ourselves asking is whether code is a paint brush or a calculator, and frustratingly the answer appears to be both. Despite the fact that programming looks like art and looks like science, I still think there’s a concept that better fits the practice of coding, creative expression.

We can look to writing as a point of comparison. Sometimes it’s hard to believe that the most beautiful poem uses the same medium as boring technical documentation because the artifacts look and feel so different, but we all know it’s true. The medium doesn’t impose limitations on how someone can choose to express themselves, it’s a tool for creative expression. With writing it’s impossible to separate the medium from the artifact created, and the same is true for code. Code can be artistic and create something new in the world, or it can simply exist to accomplish a task. Code helps people capture the meaningful moments of their lives, lets you carry the beauty of every song ever recorded in your pocket, but it’s also the boring spreadsheet that helps you run your business.

So is coding an art, a science, or creative expression? I say coding isn’t science, it’s not art, it’s not quite a craft, but a malleable form of creative expression. When given an infinitely flexible and manipulable canvas people use their imagination to create wondrous things, ones not limited to simple categorization.

Creating Slick Color Palette APIs

Joe Fabisevich — Tue, 24 Aug 2021 12:00:00 GMT

The work of writing maintainable code is an ongoing endeavor and some of my favorite problems to solve are ones that build maintainable systems. Maintainable systems are ones you can learn once, easily manipulate, and ideally take from project to project. My favorite part of building maintainable systems is that it minimizes the amount of work I need to do when starting a new project, and like it is for many programmers hitting ⌘ + ⇪ + N to start a new project is one of the most satisfying feelings in the world for me.

A color palette is something every well-designed app needs, and it turns out there are a lot of ways to solve this problem. If you don’t yet have a good sense for how to construct a color palette, I highly recommend this post by Refactoring UI that explains the fundamentals of a good color palette. Generating a good color palette can be tricky if you’re new to the practice and can require some trial and error, so if you’d like a shortcut a tool like Coolors is a great starting point.

I’ve spent years iterating on approaches to codifying color palettes in my iOS and macOS apps, seeking to create one that’s flexible, scales well, and is easy to understand, landing on the version we’ll explore below. We’ll be able to leverage asset catalogs, create a clear sense of hierarchy, provide statically typed semantic colors, even take advantage of the built in features of SwiftUI. As a bonus, if you’re working with designers, your palette will be so straightforward to modify that a designer can submit a pull request to change colors without ever involving you.

Considering we’ll be leveraging asset catalogs, the first step should be pretty intuitive, we should create an asset catalog to hold our color palettes.

As I was piecing together different instructions and ideas this second step confused me, so I’ll spare you the misery. You’re going to want to make a different folder for each color palette you create, and you can do that by right clicking in the asset catalog and selecting New Folder.

Now it’s time to create our color palettes. I’m showing you the Night palette I created for my app, and below it are Spring, Summer, and Winter. Each palette has the same name but all of the colors are named the same, each palette will have colors named background-alt, primary, quaternary, etc.

Do not miss this incredibly important step, guide your eyes towards the pink arrow on the right side of the image. You must select the folder you’re adding colors to and check the Provides Namespace checkbox. This is what will enable our code to have a clear and consistent naming structure, matching the folder’s name to our palette’s name.

Now that we’ve got our asset catalogs setup, we’re ready to write some code. We’ll start by constructing a new Palette struct, and populating it with some Colors that we’ll reference across our app.

extension Color {

    struct Palette {
        let name: String

        var mainBackground: Color {
            Color(fromPalette: self.name, semanticName: "background-main")
        }

        var midBackground: Color {
            Color(fromPalette: self.name, semanticName: "background-mid")
        }

        var alternativeBackground: Color {
            Color(fromPalette: self.name, semanticName: "background-alt")
        }

        var primaryText: Color {
            Color(fromPalette: self.name, semanticName: "text-primary")
        }

        var alternativeText: Color {
            Color(fromPalette: self.name, semanticName: "text-alt")
        }

        var primary: Color {
            Color(fromPalette: self.name, semanticName: "primary")
        }

        var secondary: Color {
            Color(fromPalette: self.name, semanticName: "secondary")
        }

        var tertiary: Color {
            Color(fromPalette: self.name, semanticName: "tertiary")
        }

        var quaternary: Color {
            Color(fromPalette: self.name, semanticName: "quaternary")
        }
    }

}

This is a pretty standard palette and should cover most of the use cases you’ll encounter in building an app. You can modify it to your needs, but the important thing is that the colors you choose need to match the names of the colors you declared in your asset catalog. But what is this Color(fromPalette:semanticName:) initializer?

private extension Color {

    init(fromPalette palette: String, semanticName: String) {
        #if os(macOS)
        self.init(NSColor(named: "\(palette)/\(semanticName)")!)
        #else
        self.init(UIColor(named: "\(palette)/\(semanticName)")!)
        #endif
    }

}

You can just as easily use a private method in Color.Palette, something like private func assetCatalogColor(semanticName: String). I happen to prefer the ergonomics of a custom initializer, and this whole post is about improving ergonomics, so let’s run with that.

This initializer lives in Color.Palette and takes advantage of our namespaced folder structure to pull out colors from the asset catalog. palette unsurprisingly is the name of our color palette, and semanticName is the name of the color we’re pulling out of it, such as primary, secondary, or background-main. Combining the two with a /, we’ll get the primary, secondary, or background-main color from our current palette. All that’s left is to define the palettes we’ll be constructing.

extension Color.Palette {
    static let spring = Color.Palette(name: "Spring")
    static let summer = Color.Palette(name: "Summer")
    static let autumn = Color.Palette(name: "Autumn")
    static let winter = Color.Palette(name: "Winter")
    static let day = Color.Palette(name: "Day")
    static let dusk = Color.Palette(name: "Dusk")
    static let night = Color.Palette(name: "Night")
}

Constructing palettes is pretty easy. All you have to do is instantiate a Color.Palette object with a name. That name must match the folder name, so in my app the palette name for Night will be Night because the folder we chose for that palete was "Night".

Now that we have a color palette created, we should probably start using it. If you’re using UIKit you’ll likely have built your palette atop UIColor instead of Color and used .palette.primaryText wherever a UIColor is expected.

But if we’re building our app in SwiftUI, we can go the extra mile with just a few lines of code to leverage the Environment, making our palette easily accessible and SwiftUI-friendly.

private struct ColorPaletteKey: EnvironmentKey {
    // We need to default to a palette so without any particular preference let's pick `day`
    static let defaultValue = Color.Palette.day
}

extension EnvironmentValues {
    var preferredColorPalette: Color.Palette {
        get {
            return self[ColorPaletteKey.self]
        }
        set {
            self[ColorPaletteKey.self] = newValue
        }
    }
}

This creates the preferredColorPalette property in our Environment. If you’re not sure how the Environment works there are a lot of great resources on the internet like this post by Keith Harrison.

struct HeaderView: View {

	@Environment(\.preferredColorPalette) private var palette

	var body: View {
		Text("Hello World")
			.foregroundColor(palette.primaryText)
	}

}

Now accessing our colors is a nothing more than two lines of code, how slick is that?

Hope I didn’t wear you out, there’s a lot here, but when you throw it into Xcode you’ll see that it’s pretty easy to digest. After a few iterations I’m really happy with this solution and have been using it in my personal apps for a while now. It allows us to easily add or change colors, have a visual representation of our colors, with minimal code, and a pretty slick API.

But no code is perfect (except for mergesort), so I’m always looking for improvements. I’m excited to hear your thoughts or suggestions, so don’t be shy about reaching out.

Putting the U in GraphQL

Joe Fabisevich — Fri, 12 Mar 2021 12:00:00 GMT

GraphQL has been on my list of technologies to learn for a few months now, and last week I came across Majid Jabrayilov’s post, feeling pretty excited to tackle the subject. The post was very good, but it didn’t answer the one question I’ve had as I’ve gone through numerous exercises to understand GraphQL, how do I make GraphQL requests without a library?

I’ve read about how to create a GraphQL query and how to integrate GraphQL on your server a dozen times, but one topic that’s highly under-covered is how to make a GraphQL request from the client. In the world of GraphQL it’s very common to reach for Apollo, a library that handles turning GraphQL queries into functions, leveraging tooling to turn those functions into type-safe API requests the client can make.

While this is a perfectly reasonable approach, and actually a pretty good developer experience, it still didn’t answer the questions I had as an ever-curious engineer, how would I do this on my own?

I broke the problem I saw down into two smaller problems, request-generation and request-making. Generating a request, especially in Swift, it turns out is pretty easy. I really like the approach that SociableWeaver takes, leveraging Swift’s function builders to let you build a type-safe directly in Swift. The second problem was a bit fiddlier. I knew that I had to make a POST request, and I knew the endpoint that was being hit, and through some trial and error (and a friend’s help¹), I was able to start making GraphQL requests without any external libraries needed.

extension URLSession {

    func graphQLRequest(url: URL, query: String) -> URLSession.DataTaskPublisher {
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.addValue("application/json", forHTTPHeaderField: "Content-Type")

        let body =
        """
            { "query": "\(query)" }
        """
        let queryData = body.data(using: .utf8)
        request.httpBody = queryData

        return self.dataTaskPublisher(for: request)
    }

    // If using SociableWeaver or a similar GraphQL query generator, you can do it in a type-safe manner.
    func graphQLRequest(url: URL, query: Weave) -> URLSession.DataTaskPublisher {
        return self.executeGraphQLQuery(url: url, query: query.description)
    }

}

After looking over the above code a few times I realized that the majority of it was handling the creation of a URLRequest. That served as a hint to me that we could refactor the code into a custom URLRequest initializer. This would be less prescriptive about how the URLRequest is used, since my first code snippet assumes you always want to return a URLSession.DataTaskPublisher.

extension URLRequest {

    init(url: URL, graphQLQuery query: String) {
        self.init(url: url)

        self.httpMethod = "POST"
        self.addValue("application/json", forHTTPHeaderField: "Content-Type")

        let body =
        """
            { "query": "\(query)" }
        """
        let queryData = body.data(using: .utf8)
        self.httpBody = queryData
    }
    
    // If we're going all in on SociableWeaver we can make a similar initializer that takes a `Weave` parameter instead of a `String`.

}

Now if you’d like to use URLSession.DataTaskPublisher you’re free to by creating a URLRequest from our new initializer and using it, but you can also return a URLSession.DataTask or any other reason mechanism that involves a URLRequest.

extension URLSession {

    func graphQLRequest(url: URL, query: String) -> URLSession.DataTaskPublisher {
        let request = URLRequest(url: url, graphQLQuery: query)
        return self.dataTaskPublisher(for: request)
    }

    func graphQLRequest(url: URL, query: Weave) -> URLSession.DataTaskPublisher {
        return self.graphQLRequest(url: url, query: query.description)
    }

}

That looks a lot cleaner, and our responsibilities seem a lot more well-divided.

Is there room for tools like Apollo? Absolutely! I’m not going to pretend that my dozen lines of code replaces the value that a multimillion dollar company provides. (I’ll only make sick jokes about it.) But before importing a library like Apollo, any library really, it’s worth asking yourself whether you need a big solution for a small problem. Or maybe question the better question to ask before that is, have you really understood the problem you’re trying to solve?

But we still haven’t really answered where exactly we should put the U in GraphQL. (I say after the Q since Q is almost always followed by U, but I’m open to feedback on that or the rest of this post.)

Footnotes

Special thanks to Dave DeLong for his debugging prowess. ↩

Empower Apps Podcast: Large Scale Teams

Joe Fabisevich — Fri, 12 Feb 2021 12:00:00 GMT

I recorded an episode of the Empower Apps podcast, where Leo Dion and I discussed a wide range of topics. We spoke about everything from how we scale app development to thousands of people and millions of users at Twitter, communication, documentation, people working together, and a lot about and the complexity of holding moral frameworks at a global level.

Context-Bound Types

Joe Fabisevich — Mon, 21 Sep 2020 12:00:00 GMT

I’ve been thinking about privacy lately. No, not online privacy, but about how APIs can balance exposing the right amount of implementation details without revealing too much.

I’ll walk through a task I find myself doing often when building iOS apps, creating a view controller with header view, and four different ways to go about it.

Regular View Configured as a Header

SettingsViewController.swift

final class SettingsViewController: UIViewController {
    private let headerView = UIView()
    
    private let tableView = UITableView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
    
        self.view.addSubview(self.tableView)
        self.setupTableView()
        self.configureHeaderView()
    }
    
    func setupTableView() {
        self.tableView.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            self.tableView.leadingAnchor.constraint(equalTo: self.view.leadingAnchor),
            self.tableView.trailingAnchor.constraint(equalTo: self.view.trailingAnchor),
            self.tableView.topAnchor.constraint(equalTo: self.view.topAnchor),
            self.tableView.bottomAnchor.constraint(equalTo: self.view.bottomAnchor),
        ])
    }
    
    func configureHeaderView() {
        // Some code configuring self.headerView
        // ...
        // ...
        self.tableView.tableHeaderView = self.headerView
    }
}

For folks new to iOS development, this is a common approach I see when adding a header. It makes sense, you want to have a header, and a header is a view, so why not configure and style UIView to be the UITableView header. While this is a good first try, it lacks the encapsulation that makes your code easy to edit and reason about.

Separate Class For The Header

SettingsViewController.swift

final class SettingsViewController: UIViewController {
    private let headerView = SettingsTableHeaderView()
    
    private let tableView = UITableView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
    
        self.view.addSubview(self.tableView)
        self.setupTableView()
    
        self.tableView.tableHeaderView = self.headerView
    }
}

SettingsTableHeaderView.swift

final class SettingsTableHeaderView: UIView {
    // Some code creating and configuring SettingsTableHeaderView
    // ...
    // ...
}

A naive approach to improve our readability would have been to move our configuration code into a function, but an even nicer improvement is to move it into its own class. This looks a lot better, it’s easier to reason about and it’s well-encapsulated. But a new problem this introduces is adding SettingsTableHeaderView into our module’s namespace. Now I’ll admit this isn’t the world’s biggest problem, but as you start adding different view controllers with different headers, suddenly finding the right header view for a given view controller becomes difficult.

Private Class for the Header

SettingsViewController.swift

final class SettingsViewController: UIViewController {
    private let headerView = HeaderView()
    
    private let tableView = UITableView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
    
        self.view.addSubview(self.tableView)
        self.setupTableView()
    
        self.tableView.tableHeaderView = self.headerView
    }
    
    private final class HeaderView: UIView {
      // Some code creating and configuring SettingsViewController.HeaderView
      // ...
      // ...
    }
}

Now this is a solution that I’m really liking. We’ve moved SettingsTableHeaderView out of our module’s namespace and into one dependent on the context it’s in, SettingsViewController. When referring to SettingsViewController.HeaderView inside of this class we can plainly refer to it as HeaderView, which is not only less verbose, but emphasizes the pairing between HeaderView and SettingsViewController.

There is a downside to this approach though, the more views we add to SettingsViewController, the harder this file becomes to parse. Now again this may not seem like a big problem, but if you have a well encapsulated view, you may have many subviews that belong to either SettingsViewController or HeaderView, and your file can get pretty large. (Trust me, I’ve seen written some pretty large files.)

Two Files with Namespaced Internal Classes

SettingsViewController.swift

final class SettingsViewController: UIViewController {
    private let headerView = HeaderView()
    
    private let tableView = UITableView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
    
        self.view.addSubview(self.tableView)
        self.setupTableView()
    
        self.tableView.tableHeaderView = self.headerView
    }
}

SettingsViewController.HeaderView.swift

extension SettingsViewController {
    final class HeaderView: UIView {
      // Some code creating and configuring SettingsViewController.HeaderView
      // ...
      // ... 
    }
}

This is the approach I’ve settled on today. You’ll notice that HeaderView is no longer private, but it’s also not particularly easy to access publicly. You still end up with the benefits from namespacing the API, and this extension can go into its own file, unlike the earlier approach.

If you were to accidentally misuse this API, it would be pretty clear. When calling HeaderView inside of SettingsViewController the call-site is clean and simple. But if someone were to attempt to use it from another class, they would have to reference the fully-qualified type, SettingsViewController.HeaderView.

While I’ve walked through one example with four approaches, binding a type to its context is something you can do throughout a codebase. In an ideal world Swift would have a submodule keyword to make types less ambiguous, but in the mean time this is a reasonable substitute that developers can take advantage of. While we don’t have a submodule keyword, we have a close approximation by using empty enums. One notable example is Combine’s usage of Publishers and Subscribers to help people have context and understanding for their subtypes.

As always, I’d love to know what you think or if you’ve come up with better solutions, so please don’t be shy about reaching out.

Special shoutout to Jasdev for taking a very rough first draft and helping me turn it into something coherent.

Building Better Views (Part I)

Joe Fabisevich — Thu, 26 Dec 2019 12:00:00 GMT

As iOS developers, a lot of our work involves taking models from a server, and transforming them to be displayed on an iPhone or iPad. This sounds like a job for some declarative architecture. 🤔

If you ask 3 programmers how to define MVVM, expect to get 7 different responses.
— ✨ Joe Fabisevich™ ✨ (@mergesort) April 14, 2016

Confession: I’ve never fully bought into MVVM. I don’t think it’s worse than MVC. I use View Models as a place to store state and actions for View Controllers, and preferably stateless functions for manipulating data. In my experience, things become harder to maintain when they start becoming a crutch, as a place to put your code if it doesn’t neatly fall into the Model, View, or Controller label.

With this in mind, I realized we need an answer for configuring our views in a way that’s maintainable, and ultimately transforms one or multiple models into a view. This led me to the idea of ViewData. I started working on this with @shengjundong at Timehop, and have been using it successfully across apps of varying sizes since.

There are three parts to this approach:

A UIView instance. This is your standard view that you’ll be displaying in an app. It can be a regular class, or a custom subclass as you need.
A ViewData protocol. This is what’s going to keep track of the data that needs to be displayed in your view. Most commonly this will be a slice of a model, used specifically for rendering the view.
A configure(viewData: ViewData) function. This is what’s going to map your View to your ViewData.

An Example

Let’s start with an example, where we’re building a view to display a comment. It will have a few properties you’d expect from a comment view. A commenter, their avatar, some text, and a timestamp. To make it easier to visualize, let’s imagine it looks like this:

We start with a simple model. This is what we’ll be later manipulating for display purposes.

public struct Comment {
    let text: String
    let commenter: String
    let createdAt: Date
    let avatarURL: URL?
}

A simple UIView subclass to display the comment.

public final class CommentView: UIView {
    let titleLabel = UILabel()
    let subtitleLabel = UILabel()
    let statusLabel = UILabel()
    let replyButton = UIButton(type: .custom)
    let avatarImageView = UIImageView()
}

Now we get a little to the fun stuff.

We’ll make our first ViewData protocol. This represents how we will render the data we’re trying to populate the UIView with.

protocol CommentViewData {
    var title: String { get }
    var subtitle: String { get }
    var timestamp: String { get }
    var replyText: String { get }
    var avatarURL: URL? { get }
}

Let’s conform our model to our CommentViewData protocol. This will be how we tell our CommentView how it should display our model whenever it comes across an instance of it.

// The original data source is made to conform to the protocol which we are using for display, CommentViewData

extension Comment: CommentViewData {
    
    var title: String {
        return self.commenter
    }
    
    var subtitle: String {
        return self.text
    }
    
    var replyText: String {
        return NSLocalizedString("Reply", comment: "Text for replying to a comment")
    }
    
    var replyImage: UIImage? {
        return UIImage(named: "reply")
    }
    
    var timestamp: String {
        return self.createdAt.timeAgoSinceNow
    }

}

One thing to note is that the avatarURL property automatically conforms to the CommentViewData! As long as we plan to use it directly, we don’t have to add it to our extension.

Last but not least, we need to configure the CommentView with a CommentViewData.

extension CommentView {

    func configure(viewData: CommentViewData) {
        self.titleLabel.text = viewData.title
        self.subtitleLabel.text = viewData.subtitle
        self.statusLabel.text = viewData.timestamp
        self.replyButton.setTitle(viewData.replyText, for: .normal)
        self.replyButton.setImage(viewData.replyImage, for: .normal)
        self.avatarImageView.setImage(from: viewData.avatarURL)
    }

}

We’ve got everything configured in a nice declarative fashion, but how do we actually use this? This is in my opinion the best part. Let’s look at the call-site.

    func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
      // My own homegrown solution, you're under no obligation to use it of course 😇
      let cell = tableView.dequeueReusableCell(forIndexPath: indexPath) as GenericTableCell<CommentView>
        
      // This is of type `Comment`
      let currentComment = self.comments[indexPath.row]
    
      // Comment conforms to `CommentViewData`, so we can use it directly!
      cell.customView.configure(viewData: currentComment)
    
      return cell
    }

And that’s it! All you need to do is pass the original model object to the view, and as long as it conforms to the right protocol, you’ve got it working without any intermediate objects.

This may seem like a lot of boilerplate, and to be honest, it’s more than I would like. There are other languages with features such as row polymorphism or extensible records which would make this easier. Until Swift supports these language features, or macros, or more powerful tooling that can fill the gaps, this is the best solution I’ve found to enforcing good practices and leveraging compile-time safety for view configuration.

Now you may also be thinking “sometimes my models don’t map to how they’re displayed one to one, how can I make that work?” Follow along with part 2, where we’ll cover that, and a few other questions you may have.

As always, I’m excited to hear your thoughts, and am receptive to feedback!

Building Better Views (Part II), Next Steps

Joe Fabisevich — Thu, 26 Dec 2019 12:00:00 GMT

If you haven’t checked out Part I, I recommend reading it because if you don’t, none of writing below will make sense!

Three Unanswered Questions

1. What happens when the views you want to configure are more complex?

My recommended approach is to construct a one-time use struct, specifically for displaying in that one place. This type should only have the properties you need to render the view.

struct HomeScreenCourseProgressViewDisplay {
    let course: Course
    let enrollment: Enrollment
    let customization: SchoolCustomization
}

Creating the ViewData should look familiar. We’re going to do the exact same thing we did before.

extension HomeScreenCourseProgressViewDisplay: CourseProgressViewData {

    var titleLabelText: String {
        return self.course.name
    }

    var subtitleLabelText: String {
        return self.course.author.name
    }
    
    var statusLabelText: String {
        return String.localizedStringWithFormat(NSLocalizedString("%@% complete", comment: "The percentage a course is complete"), self.enrollment.percentComplete)
    }
    
    var progress: CGFloat {
        return CGFloat(self.enrollment.percentComplete) / 100
    }
    
    var imageUrl: URL? {
        return self.course.imageUrl
    }

}

Using this ViewData object is just as simple as it was before. On our home screen, we now create the struct, and configure our custom view with it. Same as before, just leveraging how lightweight creating types in Swift is!

func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    guard let currentUser = self.userAtIndexPath(indexPath: indexPath), self.hasCoursesAtIndexPath(indexPath: indexPath) else { fatalError("Ruh roh"!) }
    
    let currentCourse = currentUser.courses[indexPath.row]
    let currentEnrollment = currentUser.enrollments[indexPath.row]
    let schoolCustomization = currentUser.school.customization
    
    let homeScreenDisplay = HomeScreenCourseProgressViewDisplay(
        course: currentCourse, 
        enrollment: currentEnrollment, 
        customization: schoolCustomization
    )
    
    cell.customView.configure(viewData: homeScreenDisplay)
    
    return cell
}

2. How does the `ViewData` pattern deal with user interaction?

I advise keeping user actions in the UIView realm. You can continue using the delegate pattern, closures, or wherever your preferences may lie. If you’re looking to get a little more advanced, I’d consider reading Dave DeLong’s A Better MVC series.

3. Where does logic code reside, and what happens if you have more complex transformations?

The scenarios so far have worked great. The models you received from the server looked a lot like the way you plan to display them, but that’s not always the case. Sometimes you’re going to need business logic, and that’s ok.

This is the question I had the most trouble coming up with one answer for. I realized the reason I couldn’t come up with one answer is because there isn’t only one answer.

Looking back at our Comment model, we see that there is a Date object in there.

public struct Comment {
    let text: String
    let commenter: String
    let createdAt: Date
    let imageUrl: URL?
}

In our first example we simply glossed over the fact that we were translating a Date into a String, by using a simple function that already exists in a third party library.

extension Comment: CommentViewData {
    var timestamp: String {
        return self.createdAt.timeAgoSinceNow
    }
}

But now let’s pretend we don’t have timeAgoSinceNow available to us. Where does that transformation code live? The answer is, it’s up to you!

Some people prefer to make an object to handle business logic, to make their code more testable. If it makes you happy to keep it in the ViewData file, go right ahead. If not, then don’t. Who am I to tell people how to be happy?

extension Comment: CommentViewData {

    var timestamp: String {
        let dateTransformer = DateTransformer(self.createdAt)
        return dateTransformer.asString()
    }
    
    private static func transformDateToString(date: Date) -> String {
        return someMagicalWayToTransformDatesToStrings()
    }

}
    
struct DateTransformer {
    let date: Date

    func asString() -> Date {
        return someMagicalDateTransformer()
    }
}

My personal preference is to use private static functions, keeping in tune with the functional nature of this approach.

extension Comment: CommentViewData {

    var timestamp: String {
        return transformDateToString(self.createdAt)
    }

}

private extension Comment {

    static func transformDateToString(date: Date) -> String {
        return someMagicalDateTransformer()
    }

}

The important thing to note is that when it comes to business logic, you have the agency to structure your codebase however you’d like. The ViewData pattern isn’t prohibitive or prescriptive, it’s just there to aid you in transforming models into views.

These are the big questions I’ve received while using this pattern over the last few years. I’m excited to hear your thoughts, and am always receptive to feedback!

The Learn Swift Podcast: Episode 28

Joe Fabisevich — Sun, 24 Jun 2018 12:00:00 GMT

I recorded an episode of @learnswift_fm with Steven Sherry a couple weeks back. We had a great chat about contracting, computing history, philosophy, Smalltalk, and even a little bit about Swift. I think you’ll really like it, and recommend giving it a listen.

The Learn Swift Podcast: #28: Joe Fabisevich

Original recording

Dev Chats - Joe Fabisevich

Joe Fabisevich — Tue, 24 Oct 2017 12:00:00 GMT

This is an interview that I did with Sam Jarman, originally posted on his blog.

Introduce yourself! Who are you? Where do you work?

Hey Sam, thanks for this interview! I’ve been reading your other developer interviews and am humbled to be in the same company as them.

I’m Joe Fabisevich, an iOS developer in New York City, with no specific ties to a company right now. I spent the first 5 or 6 years of my career working startups like Timehop, Betaworks, and Bitly. Last year I decided to take the things I’d learned and help other companies grow via consulting work.

My job is to help companies get through whatever challenges they’re currently face. I enjoy working most with early stage startups, so a lot of my work focuses around getting startups to their 1.0. Often times they’re starting with nothing more than sketches and wireframes. Other times I help businesses figure out their mobile strategy, or work with iOS teams to grow their skills. This is especially interesting as iOS has recently moved to Swift, and there are few experts in the field so far. I wanted to add flexibility in my life, and now I’m able to tackle all different kinds of challenges. Not all of my work is even engineering related, which makes it fun to grow in many directions.

Who or what got you into programming?

It’s a bit cliché, but I got into programming somewhat by accident. In high school my grades were pretty poor, and I had to choose a major for my junior and senior years. My mom was a mainframe programmer and told me that if I took the computer science course, she would help me out. (Please don’t tell my 11th grade AP Java teacher Mr. Turner). After about two weeks, she declared that she was completely out of her element, and that I was on my own.

I was never a great rote learner, but I was always good with understanding patterns and systems. Programming lends itself to hands on learning, which made me finally feel good about learning. After some initial success, I was pretty hooked. As I got better, I was able to start helping others, which was also something I’d never been able to do.

In college I majored in computer science, but rather aimlessly. When the iPhone came out, I really wanted to make an app for it with a friend, and so I mustered up my strength and did. The code was awful, and the UI was hideous by today’s standards, but there were probably only 10,000 or so people building apps, so it was felt like quite an accomplishment. Since there was so little iOS talent out there, I was able to parlay that app into an internship. As I left school (after spending most of it building apps in class), I was able to turn that internship and subsequent apps into my first startup job.

What’s the tech scene like in NYC? Any major upsides and downsides?

The tech scene in New York City is quite a mixed bag, but I feel that way about most things in New York. Tech is not the top dog in this city, which has it’s pros and cons.

The biggest pro is that as an industry, we stay mostly grounded. We use our technology to lift up other industries, as well as tech for tech’s sake. This helps us avoid a monoculture like you see in Silicon Valley.

The biggest con is that as an industry, we stay mostly grounded. This means that we don’t attract as much talent (though there’s still plenty), or work on as many moonshot ideas as you’d see in Silicon Valley. Those moonshot ideas are the one’s that grow to be Facebook or Airbnb, and affect our lives in an outsized manner.

As a person, it’s hard to say whether I would trade one for the other, but it’s always a fun thought experiment.

You’ve worked both for companies and for yourself – do you have a preference? What are the advantages and disadvantages?

Like everything in life, there’s pros and cons to everything. I don’t have a preference, and don’t think I’ll always be a consultant, but don’t think I’ll always work full time either.

Being a consultant gives me work-life balance that’s hard to beat. It’s quite an opportunity to use the extra time I have to invest in my own learning. I can spend more time reading about product, design, management, or even things like metacognition, which help me grow in my career.

On the other hand there are some skills you can learn at a company over the long term. I still work at and with companies, but being with a company for a while helps you develop different skills.

I tend to think of it as growing in a breadth-first manner vs. a depth-first manner. Both will likely get you to the place you want to be, but the path will look different. Ultimately what works best for you is in your hands.

What has been your toughest lesson to learn in your software career so far?

I’d say the career matters. Developers often don’t want to think about their career, and instead think about programming. It makes sense because it takes a while to become comfortable enough to feel confident in what you’re doing, but as a result other people’s other skills suffer.

I’ve always been interested in product, design, and programming, so choosing a linear path was difficult for me. Nowadays I’m able to leverage those skills as a consultant and former startup founder. On the other hand, I hadn’t spent much time thinking about management or a career track until recently, and realized that I’ve got little experience with that and now am playing catch up. Ultimately it may not matter because you can’t predict your future, but it is very important to be in touch with your goals to move forward as much as possible, without parallel diversions.

What would be your number one piece of advice for a successful software career?

Everyone starts at the beginning and there’s no way around it. Luckily, that’s ok. Over the first few years of my software career I read anything programming related in sight that sounded interesting. Even if it didn’t pertain to what I was currently working on, I would still read it. That ended up paying dividends as I started to expand my horizons. Even though I didn’t understand it all, I had all this knowledge tucked away in the back of my brain for a later day.

When it was time for me to try my hand at Python, I didn’t need to start from scratch. When I wanted to build a website, it was as easy as recalling that tutorial I read a month ago. Better yet, I took the lessons I learned in other languages and frameworks, and applied them to what I was working on as I saw fit. This allowed me to grow in ways that my peers weren’t, and made a more confident programmer.

While this technique worked for me, I can’t promise it will work for everyone. Everyone learns differently, and you have to find your path. What I will suggest though is trying it out and seeing if it works for you! Maybe it won’t be the only way you grow, but it can be another tool in your toolbelt.

What programming skill do you think is underrated?

There are two personality traits which go hand in hand. Empathy and modesty can take you from being a good programmer to being a good teammate. Being a good teammate can transform you into a great asset. If you apply these traits, you’ll more easily accept your flaws, and that will empower you to your co-workers and fellow community members.

One underrated aspect of empathy and modesty is that over time you become more confident and humble. Confidence and humility allow you to turn anything into a learning opportunity. The more you can say “I don’t know, but I want to learn about it” either to yourself or to a peer, the more you’ll open yourself up to an opportunity to grow. Over time it will become an innate part of how you approach solving problems.

What books/resources would you recommend?

I’m going to be a little self-serving here, but I maintain a Pinboard tag where I post articles. The articles are ones that I’ve come across in my career that taught me something, with information I wish I knew when I was just starting out as a programmer. Sometimes I go back and re-read the articles, and I’ll still pick up new things. As I’ve grown, the advice and stories take on new life and new meaning.

I recommend going through the posts in reverse order. The first posts are more foundational and encourage bigger thinking. I’m really big on RSS, so I recommend subscribing to the feed, so that way you can always get a new article right after it’s posted.

Finally, make your shoutout! What would you like the readers to go have a look at?

I think right now it’s important to not forget about others in need. There are people dealing with natural disasters that have entirely uprooted people’s lives. A cause that’s near and dear to my heart is the Hispanic Federation, where every dollar will go to aid on the ground in Puerto Rico. You can choose your own cause, but the important thing is to do something.

Personally you can find me on Twitter where I am busy saying anything that comes into my head, so my apologies in advance.