Joe's Blog

Hour by Hour is here!

Joseph Humfrey — Tue, 31 Mar 2026 24:00:00 GMT

I finally released my iOS app!

Hour by Hour is a day planner that lets you sketch out your schedule with natural language. Write things like "Flight departs at 3:30pm" or "Set off 2 hours before", and it figures out the timing for you. Follow along with Live Activities on your Lock Screen, share schedules with friends via iCloud, and more.

It's free to download, with an optional one-time purchase to unlock unlimited schedules.

Download Hour by Hour on the App Store

The origin story

I originally had the idea while flying to San Francisco for GDC two years ago. I was doing the classic thing of working backwards from a flight time — if I need to be at the airport by 9, and it takes an hour to get there, and I need an hour to get ready... I wanted an app where I could just type all of that out naturally and have the timing calculated for me. I'd been mulling it over ever since, and I'm thrilled it's finally out in the world.

Natural language

I've always loved the natural language input in Fantastical, and Apple's own take in the Reminders app refined the idea further, with a clearer highlight and confirmation step. Hour by Hour builds on this — as you type, it parses your timing in real time and highlights what it finds. Times can be absolute ("at 3pm") or relative ("20 minutes before"), and linked events update automatically when plans change.

Photo import

A feature I'm particularly fond of was inspired by Devin Davies's wonderful Crouton: snap a photo of a physical schedule — a conference programme, a printed itinerary, a festival timetable — and Hour by Hour imports it and lets you follow along.

The icon

The gorgeous icon was designed by Matthew Skiles. I absolutely adore it, and Matthew was super professional and easy to work with. Check out his incredible portfolio!

Huge thanks to everyone who tested the app and gave me great feedback ❤️ especially Chris Wu, Jon Ingold and Tal.

What if code wasn't a text document?

Joseph Humfrey — Fri, 27 Feb 2026 24:00:00 GMT

Your browser does not support the video tag.

You're looking at code, but it doesn't look like code.

Functions are named in plain English - forget snake_case, camelCase, PascalCase. A function is just called what it does: "Add two vectors." You can expand it to read an English explanation of what it does, and the functions it calls appear as linked pills that you can expand to explore further. There's real code underneath - you can drill down to it when you need to - but the idea is that most of the time, you shouldn't have to.

This is a prototype I've been playing with. I've reached the point where taking it further would mean a serious time investment, and I have other priorities, so I'm putting it on ice for now. I'm not releasing it, but that's exactly why I'm writing about it today - I've been thinking about this stuff for about twenty years, and if I'm not going to build it into something real, I'd at least like to get my thoughts down.

Will we be hand-writing code at all in 5 years?

How we write code is changing. How far and how fast depends on who you ask - it varies wildly by programmer, by project, by the day - but the direction is clear. AI is increasingly writing the nuts and bolts of line-by-line code. It ranges from "vibe coding," where the programmer theoretically isn't looking at the code at all, to getting the AI to write small snippets that accelerate what you'd write yourself, and everything in between.

What seems clear to me is that pure vibe coding can often work for small toy projects, but at any real scale the programmer loses oversight, and things turn into a jumbled confused mess. It becomes impossible to refactor because what prompt could you possibly give the AI if you don't understand what the problem even is? So it's critical to keep an eye on what the LLM is building, how it's architected, so it fits with your vision of where your project is going.

Either way, the programmer is moving into a code architect position - thinking about structure and architecture more than the nitty gritty details - and for me this has always been both the hardest and most interesting part of the job. If you need to read and understand an LLM's code, it helps to have tools that support understanding architecture from the top down, rather than tools built around editing text files line by line, where functionality is scattered somewhat arbitrarily across files.

Twenty years of noodling

I've been interested in this stuff for a long time. As far back as around 2005, I can distinctly remember opening up Photoshop while I was on my lunch break at Rare, and I drew something that looked remarkably like Scratch. Turns out Scratch was invented before that so I can't claim any originality, but I was thinking along similar lines!

Programming in Scratch using blocks

Scratch is interesting because it provides a contained, visual object-based programming model. But it's not visually dense and it's very slow to author. That makes it fantastic as a learning tool for children, and bad if you want to be really productive.

Editing in Shortcuts on iPhone

Apple's Shortcuts sits on a similar axis - ostensibly accessible for non-technical users, but with a steep learning curve despite that. Simple concepts like conditionals and loops are extremely cumbersome, "functions" don't really exist (you create shortcuts that call shortcuts), and they're really slow to activate. People have done powerful stuff with them, and I'd assume it's made logic programming more accessible to non-programmers. But it's extremely easy to hit the limitations. It feels telling that nowadays, I can't imagine something like Shortcuts being created nowadays - I'd expect it would be replaced by some kind of consumer-facing vibe coding app with a friendly block-based visualisation of the output.

At inkle, we'd already shipped one visual code editor: inklewriter. And I'd been thinking about more visual approaches to ink, our narrative scripting language. Our core users are often writers first, not programmers per se - they want the technical features only in so far as they help them achieve their interactivity goals. I liked the idea of keeping ink's power while providing a more visual representation.

A mockup I made 5-10 years ago of what a more visual ink editor could look like.
I keep coming back to this dynamic 2D code layout idea!

But I always liked the denseness of something more like what (the now defunct?) Dion Systems were doing. Allen Webster and Ryan Fleury were asking the question: what if code's underlying representation wasn't text? Their code still looks like text - it's laid out as if it's indented text - but internally it's... not. In technical terms the internal model is an Abstract Syntax Tree - a hierarchy of objects. The whitespace doesn't exist, the code is simply positioned according to its structure. The idea of tabs vs spaces doesn't exist; you can use a slider to set indentation however you like. Curly braces don't exist, they're just a visualisation; they could've equally chosen to draw rectangles around blocks of code. Renaming a variable literally happens in one place even though it may be seen in multiple. This allows a huge amount of power.

So: does code really have to be pure text with fun colours and refactoring tools as a layer on top?

My quick prototype

I've had this confluence of ideas brewing for a long time, so I decided to take a little stab at a prototype, with these aims:

Natural language first. The first thing you see is English, not code. Functions are named in English - "Add two vectors," not addTwoVectors. If you like, think of it as snake_case with the underscores removed, nicer capitalisation, and perhaps the odd (in)definite article. This has strong ties with Literate Programming: the idea that the English explanation is primary, structured to be read and understood by a human first, and compiled by a computer second.

An infinite canvas, not files. Instead of code split across text files, it's a structured bag of objects with references between them, explored freely on a 2D canvas - like Sketch, Figma or Apple's Freeform. The code itself is presented more like the UI from a pro tool - Final Cut, Unity, Godot, Photoshop. It uses a lot of text, but it's not a text document at heart.

Spatial presentation. Code is often thought about in terms of a top-down hierarchy: who calls who and who owns what. I don't know about other programmers, but I think about this spatially. In my usual IDE, I arrange the files I have open so that the tabs for important high-level controllers are on the left and smaller lower-level code progressively to the right. Similarly, I've noticed different programmers have different approaches within individual files, with functions and call order often roughly going top to bottom or vice versa.

My prototype makes this spatial thinking explicit. All functions are listed by code area on the left. On the main canvas, you start with the entry point. From there you spelunk through the code, exploring it top-down. As you read and understand what a function does, the functions it calls are brought in nearby. I've been experimenting with options to put them to the sides or underneath. Functions that call it are above. Perhaps you should be able to pin and drag these pieces around to match how you're thinking about them. Perhaps the editor should remember your spatial arrangement, or perhaps it should be fully dynamic.

Progressive disclosure. You don't see traditional "actual code" by default. Functions show their English descriptions. Expand one and you see step-by-step explanations, that can be further expanded. Functions that are called appear as linked pills. Hover a pill to preview it on the canvas; click to open it permanently. You can open and close functions a bit like tabs.

At the deepest level, you can see lower-level code - ideally presented in an elegantly terse block-based structure. If you want to edit by hand, it should be easy with keyboard input and good shortcuts, unlike Scratch or Shortcuts. But I'd expect the most common way to make small edits is to select some code and use a short AI prompt to tweak, rearrange or refactor it.

Mockup of how visual programming blocks look at code level (no base layer JavaScript)

Under the hood. The prototype wraps JavaScript, which is the actual code underneath. It's hackable, easily authored by an LLM, and great for prototyping in a browser. But the specific underlying language isn't fundamental to the idea. Internally, the English wording is written as comments within the JavaScript, then presented as the primary thing, with the code hidden unless you expand far enough. The JavaScript necessarily still has true function and variable names, used as unique identifiers internally. I'd like to aim for these "true symbol names" to never be necessary for a human reader, though that might not be possible for ambiguity reasons?

LLM generation. For generating new programs, you prompt the LLM (currently GPT-5.2 Codex). It writes JavaScript, and my system prompt tells it how to structure the code with a specific comment format. I ask it to link references to other functions using markdown-style links, such as // Now, [Parse](parse_text) the [raw text](raw_text).

Currently, the only visual representation beyond the English descriptions is a table of values for blocks of let definitions - which works nicely for things like defining 3D objects in a raytraced scene, a bit like an inspector in Unity or Blender. But I'd imagine different view styles for different code structures and flow control types.

Where it stands

Right now, you can only browse - you can't edit existing code. The function linking via markdown-style links adds ambiguity: it's not always 100% clear whether a link refers to a specific function, so you have to hover to check. I think this is probably solvable, but it's not great yet. There's a lot of work in figuring out how language features map to visual building blocks, and I'd only call it a success if the visual style is actually as clear to a programmer as traditional code - like for like, assuming both notations were new to them.

I'm also not sure how best to make use of an infinite canvas layout. Currently, code blocks just fill down vertically. I'd love it if the user could drag and rearrange things to match their intuition, and save that layout. Even better: when generating code, the LLM or the system could figure out how to lay things out in 2D in a way that actively helps you understand the structure.

I'm genuinely curious: do other programmers think about their code spatially, or is that just me and my graphic design background leaking through? Either way, I do wonder whether we'll really be using plain text files forever. I'd love to hear what you think (see my socials below).

Instant Actions added to Substage

Joseph Humfrey — Fri, 16 Jan 2026 24:00:00 GMT

This is a feature I've been wanting to add for a while, and I'm really pleased with how it turned out: Substage now has Instant Actions.

For hundreds of the most common operations, Substage now skips the AI entirely and just does the thing. Yes, bypassing the AI is a feature! It makes the app feel incredibly snappy for the stuff you do all the time.

Type jpg and your file converts. Type zip and it's zipped. No waiting for a model to think about it. Just instant.

Here's a real-time demo: no editing, no speedup:

Here's a taste of what works:

File conversion: jpg, png, mp4, plain text, word doc, make an animated gif
File info: word count, lines of code, file size, resolution, codec, aspect ratio, fps
File management: zip, unzip, trash, duplicate
Selection: select all pdfs, select first jpg, select last word doc
Quick actions: open in terminal (or just term)

The thing is, before this update, typing zip into Substage could feel a little silly. Was it really faster than right-clicking and selecting Compress? Well now I'd argue it genuinely can be—and there's something satisfying about it too.

I've also shaved almost a full second off prompt processing times more generally, so even when you do need AI, everything feels snappier—especially with lightweight models like GPT 4.1 Mini or Claude 4.5 Haiku.

If there are commands you think should get the Instant Action treatment, let me know! You can reach me on Discord, Featurebase, or via email.

Live Activities Are Usually Half Asleep

Joseph Humfrey — Sat, 27 Dec 2025 24:00:00 GMT

Your browser does not support the video tag.

Fanta keeps me busy.

Live Activities are a little less alive than I expected.

I went back and forth on whether they were a good fit for my app, Hour by Hour. The feature is powerful, but it has strong opinions and restrictions about how it wants to be used.

Hour by Hour is a day planner that lets you sketch out a plan for your day. It's designed for busy days such as travel where you need to figure out timing, or for tracking a detailed schedule such as at a conference.

Of course, Live Activities are a good fit for this. It just took longer than I expected to get there, mostly because Apple’s APIs are surprisingly limited in a few key ways.

Where things get awkward

Live Activities are clearly designed to be driven by the outside world. Taxis, flight tracking, food delivery. And this means they were designed with push delivery in mind - from a server.

Hour by Hour is not that kind of app. It is almost entirely local and time-based. The schedule usually does not change unless the user edits it. Running a server just to keep a local event “live” would be overkill and silly. (Also I hate server work, and am very bad at it.)

This becomes even more stark when you compare Live Activities to notifications. The notifications API was designed around local scheduling first, before push notifications even existed. Time-based triggers are a core feature. Live Activities were not built that way, and it shows.

Until iOS 26, a Live Activity could only be started now or with a push from a server. No scheduling at all. iOS 26 finally adds the ability to schedule a start:

static func request(
    attributes: Attributes,
    content: ActivityContent<Activity<Attributes>.ContentState>,
    pushType: PushType? = nil,
    style: ActivityStyle,
    alertConfiguration: AlertConfiguration,
    start: Date
) throws -> Activity<Attributes>

That helps. You can now say “start this at 2pm”.

What you still cannot say is “and make this update at 2:30” or “and finish at 3pm”. Live Activities cannot advance based on a timetable. They can only update while the app is open, or when the user triggers an App Intent by interacting with it directly.

You can remove a Live Activity programmatically once you decide it is finished, but only if the app is in the foreground. You just cannot schedule that finishing point in advance.

Interactivity exists via App Intents, but it is slow. Pressing a button takes around two seconds to react, even on an iPhone 17 Pro. There is also no control over animation timing, which makes every interaction feel heavier and even slower than it ought to.

There is a slight philosophical mismatch for my specific app, too. Hour by Hour normally progresses automatically based on time. You do not have to tick things off for the day to move forward. Live Activities want explicit interaction.

The compromise, and why it still works

In the end, I leaned fully into App Intents, and it's basically fine.

In the Live Activity, you tick off events as you go. Once everything is checked off, the activity marks itself as finished and removes itself. It is not quite the model I would choose in a vacuum, but it is predictable, fully offline, and easy to reason about.

It also has an upside. The Live Activity becomes something you actively engage with, rather than a passive progress bar you ignore. Clearing the final item and watching it disappear feels quietly satisfying.

Yes, it is slower than I would like. Yes, I wish it was more responsive. But within Apple’s constraints, it is a compromise I am happy with.

And overall, I think it adds a lot.

Being able to glance at your Lock Screen and see exactly where you are in your day, using a structure you sketched yourself, feels genuinely useful, personal and immediate.

Live Activities might be half asleep, especially when they are running entirely locally. But even half awake, they turn out to be a good companion for a real, messy, human (or cat) day.

Godot’s Scene System Is Just Brilliant

Joseph Humfrey — Fri, 28 Nov 2025 24:00:00 GMT

At inkle, we're currently making our first game in Godot after using Unity for just under 10 years. So far, I couldn't be happier!

I mentioned on Bluesky that I was thinking of writing a post about a few of my favourite Godot features. For now, I only want to talk about one of them, because it's hands down my absolute favourite. It's so fundamental to Godot, and I just can't get over how good it is.

Our upcoming game TR-49 in the Godot editor, with the notebook scene open.

Compared to Unity, the scene system just makes far more sense than the whole scene and prefab tangle that Unity ended up with. Especially once nested prefabs arrived and the whole thing grew a second head. Godot feels like someone stepped back, looked at the mess, went for a long walk, and came back with something simpler and much more powerful.

How scenes actually work

In Godot, a scene is just a hierarchy of nodes that can contain anything from an entire level to a tiny UI element. You can instance scenes inside scenes and nest them as deeply as you like. It is modularity baked right into the structure of the engine.

Before I had even touched Godot, this was one of the features I was most looking forward to. It didn’t disappoint, and it even had a few surprises up its sleeve.

The UX twist I didn’t expect: tabs

What I hadn’t expected was the UX paradigm: scenes are treated like independent documents that are opened in their own tabs, exactly like having multiple files open in your code editor, or multiple PSDs open in Photoshop. For the first few minutes this threw me slightly, but when it clicked it seemed totally obvious.

You can flip between several scenes and their hierarchies at once, editing different parts of your project simultaneously. If you've used tabs in any creative tool ever, you won't need me to explain that to you, though it does throw Unity's approach into stark relief: its approach of only loading one monolithic scene at a time (or multiple additively), with a weird and fragile prefab mode, now seems absolutely wild.

Nesting scenes is simple by default

When you nest one scene in another, you don't see its children by default. Instead of the implementation details of that scene exploding all over your parent hierarchy, you just see a single, clean node where it's been instanced. It keeps the parent scene readable while still letting you package up a whole bunch of complexity inside: a chunk of UI, a reusable interaction, or even a little collection of pick‑ups. Most of the time, I just want to split up a hierarchy so it's easier to think about, not start customising every single instance.

This ends up being a better approach to prefabs than Unity's prefabs themselves, because the instance behaves like a tidy, self‑contained unit rather than a little explosion of overrides waiting to happen.

Testing scenes in isolation

Another surprise for me: there is a separate play button for playing the current scene, whichever scene tab is active. And that scene can be anything. A whole level, a tiny component, a random bit of UI floating in space.

This is fantastic for testing features in isolation. In our latest game, we have a notebook overlay, and it was trivial to load and test that as its own scene.

It might take you a bit of time to figure out how large or small your scenes should be. I definitely went a bit too fine-grained at first. But once you get your head around it, you end up flying. It's a system that rewards a bit of thought up front and pays you back every single day afterwards.

Godot has lots of features I really like, but the scene system is the one that makes the whole engine feel fresh and modern. It's simple and powerful. And once you get used to it, returning to the alternative feels a bit like using a web browser that's banned tabs and the back button.

Getting Apple’s tiny on-device Foundational Model to pick SF Symbols in Hour by Hour

Joseph Humfrey — Fri, 14 Nov 2025 24:00:00 GMT

I’ve been experimenting with Apple’s on-device LLM, and most of what I’ve seen from it has been… absolute nonsense. But, with a cunning trick I got it to achieve greatness.

It is astonishingly dim a lot of the time and will cheerfully hand you rubbish with complete confidence. But that's honestly to be expected - it's a 3-billion parameter model (that err, acts like a 1b model). But I still wanted to see if I could bend it to my will and get something properly useful out of it for my upcoming day planning app Hour by Hour.

My first attempt was to try the most obvious thing: Give it the event title and ask for an SF Symbol. That went about as well as you'd expect. Even large cloud models like GPT-5 hallucinate SF Symbols that do not exist or pick something wildly off target. So, this was entirely expected.

But I did have a modicum of hope that if I gave it a list of only 12 SF Symbols to choose from, it might do the right thing. Right? Right???

Post by @joethephish@mastodon.gamedev.place

View on Mastodon

(One thing that genuinely helped in the early stages was the fact that the Shortcuts app has Apple Intelligence actions. It’s a great place to prototype prompts quickly without wiring anything into my code. I could tweak phrasing, see how the model behaved, and very quickly learn what it was hopeless at and what it could just about handle. Most of my dead ends and small breakthroughs happened in Shortcuts long before I wrote a line of Swift.)

I realised that it doesn't actually know what SF Symbols look like, or the concepts that they're intended to represent. So I tried changing the multiple choice to a semantic word list, and numbered each - which I would then turn into an SF Symbol. I also found that asking it to start by writing a brief description of the event helped as a sort of short "thinking phase" to expand on what a terse event title might refer to:

This worked... more than 50% of the time? But I want to hit at least ~95% accuracy, not 60%. Also, this is a very short list of possible symbols.

By the time you get to around 4-6 choices it's pretty reliable. So I considered splitting SF Symbols into nested tiers of categories, effectively having it navigate through menus to find the right symbol. It may have worked in theory but was far too slow and fragile. If each step takes about a second you end up waiting several seconds just to get an icon, and the categorisation itself is never perfectly clean.

🤓 Emojis are always the answer 🤯

So I took a step back and thought about what LLMs are trained on - the internet. Emoji. They swim in emoji. There is a mountain of training data online where people use emoji contextually with everyday language. Emoji are also short to produce which makes the prompts fast.

The new idea was simple. Ask the model for one emoji that represents the event title. Nothing else. No commentary. No fuss. That single change fixed almost everything. The prompt is tiny, the output is tiny, and the model is very confident when choosing emoji.

But I didn't actually want to use emoji - they weren't the tone or style I was going for - I wanted to use Apple's elegant vector SF Symbols. So I built what is now the secret sauce that makes the whole feature work. A giant dictionary that maps emoji to SF Symbols. In practice I author it backwards: as a limited number of SF Symbol names that map to a long string of possible emoji, which I then create a reverse mapping for on load. When the model produces an emoji, I look it up in the dictionary and convert it to the SF Symbol it belongs to:

let sfSymbolToEmojiMapping = [
    ("fork.knife", "🍽️🍴🥄🍕🍔🍟🥗🥪🍣🍜🍝🌮🌯🥘🍲🍱🥙🌭🥟🥠🥡🥨🥯🥞🧇🧀🍖🍗🥩🥓🧈🥐🥖🫓🍞🥢🍳👩‍🍳"),
    ...

So if your event title contains “eat tacos”, the model will likely produce the taco emoji which then maps neatly to fork.knife.

Most of the time this gives lovely results. Occasionally it does something ridiculous. “Eat breakfast” once came back as an 🥑 avocado emoji (?!) That then mapped to carrot.fill because I included all the vegetable and healthy eating emoji under that symbol. So breakfast briefly became a carrot. Fair enough. Breakfast is what you make of it.

Your browser does not support the video tag.

Known bugs – "Start work" should really have something like a briefcase, and it shouldn't default to having the previous icon for newly created events

The best part is that this is incredibly fast. The on-device model only gets a small prompt, and there is no heavy back and forth with the cloud. It behaves well, feels instant, and makes Hour by Hour nicer to use without draining power or requiring a connection.

I wanted Apple Intelligence to feel genuinely helpful and not like a gimmick. With this emoji trick it finally clicked into place. A tiny model can do something surprisingly clever if you ask it for the right thing.

The Selkie Design blog is now Joe's blog

Joseph Humfrey — Tue, 14 Oct 2025 24:00:00 GMT

Quick update: I've moved my blog from Selkie.Design over to here!

The main reason is that I wanted somewhere I could write about anything — whether it's inkle and game development stuff, or Selkie Design and Apple platform things. It felt weird having a blog on the Selkie site when half my thoughts weren't really Selkie-related.

I've been particularly excited to get back into Godot lately, and I've got some thoughts brewing about that. More to come soon!

All the old posts are still here of course, and if you were subscribed to the old feed, you might want to grab the new RSS feed instead, though hopefully all the redirects will work!

Cheers!

Substage Predicts...

Joseph Humfrey — Thu, 31 Jul 2025 24:00:00 GMT

I might have gone a bit overboard on this one: I built a Terminal command prediction engine for Substage, and to make it work, I ended up creating my own simulator for bash.

Before any command gets run, Substage now parses and simulates it, then shows you a visual representation of what’s about to happen to your files (and more). It's literally running the command in my own bash implementation, and seeing what the files would be changed as a result of running it for real:

If you know anything about the command line, you know how easy it is for small mistakes to cause headaches. After hearing from a few users who ran commands in Substage that err... didn’t quite do what they expected, it seemed worth putting some additional visualisation in to see what Substage is about to do. So yes, I ended up writing my own little version of bash (and a handful of standard commands) just to work out what a command will do before it actually does anything.

For example, if you’re about to batch rename a folder full of files, Substage will show exactly which filenames would change, if any files would get overwritten, and whether any new files would be created or deleted. I wanted it to be as visually clear as a GUI app for git, such as the excellent Fork. I also keep track of any side effects - such as changing system settings. Here's an example of requesting a video to be converted, and explicitly asking it to delete the original:

So how does it work? Substage fully parses the most common syntax you're likely to find in one-liner commands and also attempts to evaluate it as fully as reasonably possible. When it gets down to the individual command level, not every command is treated the same way. For simple, “harmless” commands, like checking a file’s metadata or listing files, can be run directly, since they don’t modify anything on disk. But for commands that could change or delete files, or do anything risky or long-running, Substage tries to model the effects without touching your real files.

What’s interesting is that the hardest commands to simulate aren’t always the ones you’d expect. Tools like ffmpeg look intimidating, but their input/output structure is actually quite predictable. Meanwhile, seemingly simple commands like cp (the copy command) have a huge number of options and edge cases, making them much trickier to handle. Most Substage workflows tend to use a fairly small set of tools (ffmpeg, sips, mv, etc.), so Substage mostly focuses on supporting those especially well.

It's not necessary to perfectly cover every single command for it to be useful. Most real-world usage in Substage relies on a relatively small set of common tools and patterns, so even partial coverage already catches a lot of issues and gives valuable visibility. Over time, I can keep expanding and improving Substage's understanding, adding support for more commands and edge cases as they come up. Since the vast majority of use cases are covered by the commands we support, Substage shows a strong warning when running an unrecognised command, making it clear to the user when they’re in less-charted territory. But let me know, either on Featurebase, via email or Discord if there's a command missing that you'd like to see supported!

Another benefit of this approach is that we can be a lot more precise about evaluating the risk of a command and allowing you to choose what commands can be run automatically without confirmation being necessary, so we have this new settings page:

For me, Substage is about making powerful tools more accessible, without losing any of the flexibility or control that makes the command line so useful. I’ve always preferred visual tools to the command line (hence Substage generally, and I use GUI git apps for similar reasons). I want Substage to be accessible for beginners but still efficient for power users. By simulating commands and visualising their effects, Substage helps take away a lot of the guesswork with understanding the effects of a generated bash command, especially when a rogue rename can cause data loss. But it’s not just about safety; it’s about understanding what’s going to happen, and feeling more in control.

Building this (even a partial) bash simulator was one of the most ambitious things I’ve done for Substage. The update is out now - give it a try in the latest Substage release!

Substage ❤️ Setapp

Joseph Humfrey — Wed, 02 Jul 2025 24:00:00 GMT

Good news, Substage is now on Setapp!

If you’ve already got a Setapp subscription, you can grab Substage right now for free. If not, this might be a nice excuse to give Setapp a try; I’ve always loved the idea of it, especially for smaller indie apps like mine where a subscription might feel like a bit much.

If you don't know it, Setapp is a curated collection of Mac apps you get access to with a single subscription. They’re pretty selective about what they include, so I was really pleased when they chose to accept Substage.

Even better, they gave me some super thoughtful feedback during the review process, stuff that actually led to improvements in the app itself, and that benefits everyone: I've added a brand new feature in the latest release of Substage, directly inspired by Setapp's feedback: full Spotlight search. You can now ask Substage things like “show me all jpg images created yesterday” and it’ll use Spotlight behind the scenes to find the right files:

Your browser does not support the video tag.

So far, I've found that most people prefer to go for the "Bring Your Own AI" option over the subscription version, and I totally get that - it appeals most to a technical audience who might have access to their own API keys already, and people do get a bit weary of too many subscriptions. What's cool about Setapp is that you can get the benefit of bundling all your apps into a single subscription to keep things simple. It also lets you try out more apps without doing the whole “is this worth it?” calculation every time.

The version of Substage on Setapp includes GPT-4.1 Mini by default, which I’ve found to be a great all-rounder—quick, reliable, and good enough for almost everything I throw at it. But if you’re the kind of person who likes having more control (or already has your own API keys), you can still plug those in too. Just like the other editions of Substage, the Setapp version supports “Bring Your Own AI” as well.

That's it for now! By the way, I’m always keen to hear how people are using it (or what’s not working!) Come say hi in the Discord if you’ve got questions, feedback, or just want to compare AI models.

The Shortcut to integrating Private Cloud Compute into my app

Joseph Humfrey — Fri, 20 Jun 2025 24:00:00 GMT

Apple’s Private Cloud Compute is pretty cool - it lets you use Apple’s cloud LLMs with strong privacy guarantees, and it's a much more capable LLM than their on-device models. Best of all? So far, it seems to be completely free.

But if you’re a developer, you might have noticed something odd: there’s no public API for Private Cloud Compute, and this is a shame given that their new Apple Foundation Model API is fantastic, and super well designed. There's no way to integrate it into your app, or even use it from the command line. Or is there...?

The Shortcut (literally)

Here’s the twist: Private Cloud Compute is available to users via Shortcuts. That means, if you're a Mac app developer, then with a little creativity, you can actually call PCC from your own code, by wrapping it up in a Shortcut and invoking it from your app. (I'm curious, is there a way to do this on iOS? Do apps have the ability to call arbitrary Shortcuts...?)

I’m not a Shortcuts power user by any means, but after a bit of tinkering, I managed to put together a super simple Shortcut that takes a prompt as input, runs it through Private Cloud Compute, and outputs the result. Here’s what it looks like:

The Shortcut itself is just a couple of actions: it takes the input, passes it to the “Use Model” action with the PCC model selected, and returns the result. That’s it!

Calling Shortcuts from Swift

Now, how do you call this Shortcut from your own app? Turns out, macOS ships with a handy command-line tool: /usr/bin/shortcuts. You can use it to run any Shortcut, pass in input, and capture the output.

So, in my Swift app I simply used Process to run the shortcuts command-line tool and then returned the output, something like this:

    let process = Process()
    process.executableURL = URL(fileURLWithPath: "/usr/bin/shortcuts")
    process.arguments = [
        "run",
        "Substage-PCC",
        "-o", pccOutputPath
    ]

This approach lets me effectively use Private Cloud Compute as an AI model within Substage. I’ve been experimenting with it, and so far, its performance feels comparable to an average 8 billion parameter open source model. Fine for general tasks, in my experience it doesn’t quite match the coding abilities of specialized models like Qwen Coder 7b. That said, I'm currently reusing the same prompt that I use for other models, and maybe it could do with some tweaks to improve its accuracy. It’s also noticeably slower and less capable than something like GPT-4.1 Mini.

But there’s a big upside: for the user, it’s not just cheap - it’s completely free, with no tokens to buy or API keys to manage. (Presumably though, Apple must have put in some fair use restrictions somewhere?)

From a user’s perspective, the setup won't be entirely seamless though. To get started, they’ll need to agree to add the Shortcut to the Shortcuts app (and err, not mess with it?), and the first time it runs, macOS will likely prompt them to grant permission for automation. It’s a couple of extra steps, but once set up, it works reliably in the background without needing to be prompted again.

Overall, while it’s not a drop-in replacement for the fastest or most capable cloud models, this method is a fun way to tap into Apple’s privacy-preserving AI for your own workflows... at least until Apple adds support officially via API. I think I'll hold back from doing more work to integrate it until I can be sure that the user experience can be streamlined, or at least closer to September when macOS Tahoe is released, since maybe they'll add an official API by then.

If you try this approach, let me know how it works for you, or if you find any clever ways to improve the user experience!

Substage update: Bring Your Own AI & One-off purchase out now!

Joseph Humfrey — Tue, 25 Mar 2025 24:00:00 GMT

Good news! Substage now supports custom API keys and local LLM models, and a one-off purchase option is out now, if you want to Bring Your Own AI! That means you can:

Use your own API key for OpenAI, Anthropic, Google or Mistral
Run local LLMs via LM Studio or Ollama — right on your own machine

The one-off purchase option is only available in the latest version of Substage, so be sure to grab the update if you decide to pick it up!

Also, in this new version: I'm re-enabling support for Google Gemini. I was previously uncomfortable with their privacy stance, as it varied depending on payment tier. After reviewing it more carefully and ensuring everything was properly configured on my end, I'm comfortable re-including it. Additionally, with users now able to use their own API keys, I wanted to ensure I was meeting people where they were at.

If you already have a previous version of Substage installed, click its icon in the menu bar and choose Check For Updates. Otherwise, download the latest version here!

I’ve also set up a brand new Discord server. If you’ve got questions, ideas, or want to share what models are working well for you, that’s the place!

How to get started

Using your own API key

Click the Substage settings button, head to the new AI Models tab, pick a model (like GPT-4o), and paste in your API key. That key is saved for the provider, so if you later pick another OpenAI model—like GPT-4o-mini—it’ll use the same one.

By the way, if you haven't tried Mistral yet, I can highly recommend them - their models are really fast and accurate.

Running a local LLM

You’ll need either LM Studio or Ollama. If you haven’t used either, LM Studio is probably the easier way in — it’s got a solid UI and good setup defaults.

Once it’s running and you've got a model downloaded, click Substage's Settings button, and browse to the AI Models tab. Click the "+" button and selected "Add new custom model". Fill in the model name (such as meta-llama-3.1-8b-instruct) and base URL. For LM Studio that's http://localhost:1234, and for Ollama that's http://localhost:11434.

I've tested a few models and would suggest using something in the 7–8B parameter range or larger if your Mac can handle it. Qwen 2.5 Coder has been working well for me on my 5 year old M1 iMac. I also recommend reducing the context length for speed. Around 1000 tokens works well. In LM Studio, you can do this by selecting the model in the main model list, clicking the cog settings button, and adjusting the "Context Length" parameter. I wouldn't recommend reasoning models such as DeepSeek R1, since the reasoning prevents Substage from feeling snappy, and I don't believe the thinking time helps, especially.

If you'd rather not mess with separate tools, I’m considering building in a simple way to download and use recommended models straight from the app. If that sounds good, let me know.

Behind the scenes

This release needed a fair bit of reworking under the hood—especially to support local models cleanly.

Prompting had to be redesigned. Previously, Substage used a long example-laden prompt to teach the model how to behave. That was fine for big cloud models, but local ones couldn’t handle the length. So now, prompts include just a few targeted examples, chosen dynamically based on what you type and what kind of files you’ve selected. If you ask it to convert a video to mp4, for instance, Substage quietly drops in an ffmpeg example behind the scenes. It’s faster, leaner, and still accurate.

I also had to rethink risk assessment for local LLMs. Cloud models analyse risk as they generate the command, using a custom format I specify. Local models couldn’t stick to the format reliably, so I added a new “Fast Mode” option for custom models which ONLY outputs the Terminal command, and we use a new hand-coded method to do risk assessment instead.

The new risk assessment checks for the existence of numerous tool usages in certain patterns. For example, if the command includes something like rm, it's flagged high risk; if it’s something harmless like echo, it’s low. It's never going to be absolutely bulletproof though; and you can still require confirmation every time if you prefer.

That's it! Let me know what you think:

Introducing Substage: A natural language command bar for Finder

Joseph Humfrey — Tue, 18 Mar 2025 24:00:00 GMT

I made a Mac productivity app! 🎉

Substage puts a command bar underneath your Finder windows and lets you use natural language to convert media, manage files, perform calculations, and more!

Although Substage translates natural language into Terminal commands, I’m hoping it finds a broader audience beyond developers. The number one use case I’ve found for it is converting media—quickly resizing images, re-encoding videos etc. But it can also handle file management, metadata inspection, and general tasks like web requests and calculations.

How It Works

1️⃣ Converts your natural language request into a Terminal command.

2️⃣ If it’s potentially risky, it asks for confirmation first.

3️⃣ Runs the command and summarises the output for you.

I'd love to hear what you think! You can grab it right here, and take it for a spin:

👉 Try Substage for free

What About Hour by Hour?

In case you're wondering, my iOS time-planning app Hour by Hour is also still in development!

Hour by Hour has been named!

Joseph Humfrey — Mon, 13 Jan 2025 24:00:00 GMT

After much deliberation, I've finally settled on a name for my time planning app: Hour by Hour!

I explored quite a few options along the way. "Inamo" (as in "in a mo") had a nice ring to it. "Andiamo" felt energetic. "Thyme" was a cute play on words, and "Day by Selkie" would have tied nicely to future apps under the Selkie umbrella. But they all had issues - either they were already taken by other apps, or carried associations that didn't quite fit.

In the end, I kept coming back to "Hour by Hour". It's descriptive (which helps people find it on the App Store), but I think it's also elegant in its simplicity. Sometimes the straightforward choice is the right one!

I'm excited to be getting close to the first public release.

I'd love to hear what you think!

Playful visual design for indie apps

Joseph Humfrey — Tue, 03 Dec 2024 24:00:00 GMT

I’m working on a time-planning app for iOS. It doesn’t have a name yet, but the idea is to let you sketch out a schedule hour by hour—like working backwards from a flight time to figure out when you need to wake up.

A while ago, I was listening to the excellent Launched podcast with Charlie Chapman (can’t remember the episode), and they were talking about how it’s almost a cliché for indie developers to design apps “as if Apple had made it.” That really hit me, because it's exactly where my head was at when I started.

Here was my first mock-up:

It’s fine, but it felt… generic. The main reference I had in mind was the Apple Reminders app, with the core difference being that each item would have a time attached.

The thing is, people who gravitate toward indie apps on iPhone often want something more exciting. They’re looking for something playful, something that stands out—something that brings a smile to their face.

Take apps like Crouton, Up Ahead or CARROT Weather. They’re not just useful—they’re fun, they’re quirky, they’re charming. That’s a big part of their appeal. It doesn’t need to be in-your-face like the Not Boring apps (although those are fantastic too!) It might just be a rainbow colour palette here, or an unusual widget there.

Apple doesn’t need to do this to make high quality apps, because they’re already the default. They need to make apps that just get out of the way and get the job done for the masses. Yes, they want their apps to be beautiful in a minimal elegant sense, but they also need to inoffensive and clutter free. (This has been their brand for almost two decades: extreme polish, no rough edges, almost to a fault.)

Good indie apps are literally colourful. Instead of a cautious accent colour here and there, they can afford to lean a little more into bold, playful palettes.

One other thing I’ve noticed is how many apps are using the rounded version of Apple’s San Francisco font. It’s become almost a badge of indie apps—a bit more gentle, quirky and informal than the default UI style:

SF Rounded everywhere! Pictured are the excellent Yarn Buddy and recent Apple iPhone App of the Year winner Tripsy.

They can afford to be, and absolutely should be silly, passionate, edgy and surprising.

But it’s a fine line. Go too far, and you risk slipping into clunky, overly custom designs—like a bad banking app, or that one annoying local public transport app you have to use. The problem isn’t just that it looks cheap; it’s that it actively gets in the way. Apple’s default UI works for a reason—it’s refined, polished, and it just gets the job done.

That’s the challenge: how to make the app feel joyful and different, without messing up what makes it usable.

So here are my latest mock-ups, though I'm sure it's still got a few more iterations left before the first public release:

It's still early days, but I'm excited to keep experimenting. I'll share more as it comes together.

Exploring CloudKit and CKSyncEngine for my SwiftUI App

Joseph Humfrey — Sat, 16 Nov 2024 24:00:00 GMT

If you're building a SwiftUI app in 2024, you'll face a key decision: how to handle data persistence and sharing. Modern apps need collaboration—users expect to share and sync their content seamlessly across devices and with others. But implementing robust sync in iOS isn't straightforward. Let me walk you through my journey with CloudKit, and why I landed on a surprising solution.

I’m working on a time planning app in SwiftUI with a simple hierarchical structure: a Schedule (top-level "document") contains multiple Days, and each Day has multiple Events. A key feature is iCloud syncing and sharing—users should be able to collaborate on Schedules seamlessly.

Since my goal is to stick to Apple's ecosystem, I turned to CloudKit. A major advantage is that users don't need a separate login - they're already signed into iCloud on their devices, making it feel like a seamless, native Apple experience.

The CloudKit/Sharing Dilemma

Option 1: SwiftData

For my brand new app, I'm trying to use the latest Apple recommended tech. It seeeems promising but doesn’t yet support sharing, which I think it a critical feature for my app. Plus, I’ve heard it still has growing pains, so I'd be concerned about using it in production at this stage.

Option 2: Core Data + CloudKit

This is where I initially made the most progress, since it seemed like the most mature option. It's also the most popular one that I see mentioned online: NSPersistentCloudKitContainer supports syncing and recently added sharing.

As a newcomer to the Apple backend ecosystem, I think I assumed that CloudKit directly synced as Core Data behind the scenes. Unfortunately they're two separate systems, and although Apple handles most of the translation for you, there are still a bunch of intricacies that can trip you up. So, you still need to understand both systems to use them effectively.

You need to set up Core Data model files or manually create NSManagedObject subclasses, then handle synchronization between your app's models and Core Data entities. This creates a dilemma - either use pure NSManagedObject subclasses and lose access to SwiftUI's modern @Observable macro, or maintain separate model layers.

So, when you create a Schedule in my app, it flows through multiple layers: Schedule (your @Observable app model) gets mapped to ScheduleEntity (Core Data), which then gets translated to a CKRecord (CloudKit) behind the scenes.

I did get synchronisation working, but sharing via iCloud is when the frustrations began. I thought it would be relatively straightforward since I already had all the data in iCloud, and that it would be a matter of telling it to share a specific root object in a hierarchy or a set of objects.

Although it seems to be possible to share Core Data via CloudKit as explained by this Apple documentation, it seems like yet another layer of complexity.

Option 3: CloudKit only?

When I realised that CloudKit and Core Data were two completely different technologies that Apple has bridged, it made me start to wonder why I was bothering with Core Data at all. Local persistence in my app is pretty trivial: I don't expect users to accumulate a vast quantity of data. I can store each Schedule to be a small JSON file.

However, the CloudKit API is very complex - NSPersistentCloudKitContainer is doing a lot of heavy lifting for you.

Enter CKSyncEngine

After more digging, I discovered CKSyncEngine, a newer CloudKit framework from Apple, introduced in WWDC 2023. CKSyncEngine simplifies syncing by removing Core Data entirely—no translating NSManagedObject into CloudKit records. That’s one less complex layer in the stack, which I love. Syncing is inherently tricky, so cutting out Core Data removes one huge source of potential bugs and confusion.

The setup isn’t trivial, but the documentation feels less daunting. Apple’s WWDC talk and the sample project are decent starting points. Jordan Morgan from Superwall also published this helpful guide.

Syncing is complex, but CKSyncEngine’s direct CloudKit integration makes it more manageable. No dual-layered technologies fighting for control. I hated having to learn Core Data and CloudKit when all I wanted was iCloud sharing to "just work." CKSyncEngine strips this down to one API. It's still not as simple as the idealised SwiftData approach, but it's the best option I've found so far. There’s surprisingly little written about this approach. Hopefully, CKSyncEngine gains traction because it feels like a more modern and efficient way to handle iCloud syncing.

The Future

I can’t help but feel a little outraged that Apple hasn’t made iCloud sharing easier. The “ideal” Apple app, with CloudKit and collaboration, should be straightforward to build—yet it's not. Maybe SwiftData will eventually support sharing and mature into the obvious choice for new apps. Until then, CKSyncEngine seems like the cleanest path forward.