![\"\"](\"https://alejandromp.com/development/blog/sandboxing-an-ai-harness-on-macos/giphy.gif\")
A few weeks ago I read An Interpreter for Swift, from Cocoanetics, and I had that nice feeling of somebody else having already articulated the thing that was vaguely floating in your head.
Let me just say it outright: I get very sad every time somebody insists that TypeScript is the future of agentic coding. So I kept sending my wish to the universe that Swift should be also in the race for that. Now – finally – I was able to manifest the missing piece: an interpreter for the language I love. - Cocoanetics
That resounded inside me as I’ve always thought that Swift was the ideal language for this. And if I am already building a tiny Swift AI harness to learn how these systems work, then this felt like the perfect place to test the idea. So I immediately knew I had to try using this Swift interpreter in the harness. Even if the project is still tiny and mostly for learning, I thought it could still be useful.
In the previous post I had already replaced the little file toolbox with bash, mostly to see what happened if I stopped pretending those file tools were anything other than wrappers around shell commands.
So we were already in a good position to perform the next part of the experiment and answer, what if the generic tool was not bash, but Swift?
Instead of letting the model write shell, let it write whatever top-level Swift it needs to accomplish the task. That sounds much nicer to me already.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
The most obvious version of the idea is very simple. Keep the harness the same. Just replace bash with a swift tool. Let the model write top-level Swift, and call out to the compiler to execute it.
That would definitely work, but running real Swift brings the whole toolchain with it. Module caches. Compiler behavior. We all know that running Swift means going through a compilation step, and that is not the fastest thing in the world, especially if we need to start a new compiler process every time. And given LLMs might roundtrip many times to accomplish a task, any gains we get here are worth it. It is the usual reality of “this is a language toolchain”, not “this is a tiny embedded runtime”.
It also means we have the security issues we had with Bash, we can still use Seatbelt of course, but maybe we can take this chance to do better.
And finally, I just wanted to use the Swift Interpreter. Despite not being an official solution, it looks very promising and useful, and like something that should have been taken more seriously over the years. I still think Swift is the best language even for scripting, but performance is not there. So in my head there have always been two options: increase the performance of the toolchain and be as fast as Jai, or accept the limits and make a faster interpreter. So what we have here now, despite not coming from the core team, lets us prove the second idea.
That is where SwiftScript becomes interesting.
SwiftScript is a tree-walking Swift interpreter that you can embed as a library. No swiftc. No shelling out to swift -e. Just parse Swift and interpret it.
Now the swift tool is not another subprocess. It can just be part of the harness itself. So we just make a new ToolDefinition that looks very similar to the bash one.
static func swift() -> Self {\n ToolDefinition(\n name: "swift",\n description: "Run top-level Swift code directly inside the harness process, using SwiftScript as the execution engine and ShellKit for workspace confinement.",\n arguments: ["code"],\n run: { arguments, workspaceRoot in\n let code = arguments["code"] ?? ""\n let result = await SwiftScriptToolRunner.executeInProcess(\n code: code,\n at: workspaceRoot\n )\n\n return if result.exitCode == "ExitStatus(0)",\n let stdout = result.stdout.nonEmpty {\n stdout\n } else {\n executionResultJSON(\n stdout: result.stdout,\n stderr: result.stderr,\n exitCode: result.exitCode\n )\n }\n }\n )\n}\nThis was the next question I had to understand. I have experience writing interpreters and things are easy when you just need to exercise pure code. Interpreting a syntax tree that wants a mathematical computation is trivial, but things get trickier when you start talking about I/O and other features that need to interact with an “environment”.
So we have an interpreter that we can embed and it knows how to run Swift, but what is the environment around it? Where does print go? What is the current directory? How do file APIs know what to allow?
This is where ShellKit, another library from the same author, enters the picture.
SwiftScript’s interpreter defaults to using Shell.current for output and runtime context, and ShellKit lets an embedder install a custom Shell for the current async task with withCurrent { ... }.
So the actual execution path ends up looking like this:
let shell = Shell(\n stdout: stdoutSink,\n stderr: stderrSink,\n environment: .synthetic(workingDirectory: workspaceRoot.path),\n scriptName: "<swift-tool>",\n sandbox: try? makeSandbox(...)\n)\n\nlet interpreter = Interpreter()\n\nlet status = try await shell.withCurrent {\n try await interpreter.evalScript(code, fileName: "<swift-tool>")\n}\nThat withCurrent call is the key. It binds our synthetic shell as Shell.current for the duration of the script.
So when interpreted Swift does things that route through the ShellKit bridge, it sees:
That was one of those nice moments where the implementation becomes less magical after you read it. The interpreter is not doing anything mysterious. It is just running inside a runtime context we provide.
This change is already feeling better than just running bash. Not because Swift is “safer” in some abstract sense, but because the execution model is narrower and more controlled.
With bash, the natural shape of the tool is “here is a shell, good luck, have fun”. With the embedded SwiftScript, the natural shape is “here is an interpreter we host, and here is the runtime context we chose to expose”. That is a very different starting point.
And of course this could be accomplished too by using some bash shell virtualizer, but that’s not why we are here today ^^.
If the one-tool experiment is supposed to give the model a general-purpose language, Swift feels like a great candidate.
The good part is that the interpreter is not just floating there in the void. It runs inside the virtualized shell we control, and ShellKit gives that shell a sandbox too.
So when we build the shell for the swift tool, we can attach a policy like this:
return Sandbox(\n documentsDirectory: workspaceRoot,\n downloadsDirectory: workspaceRoot,\n libraryDirectory: workspaceRoot.appendingPathComponent(".swift-script-library", isDirectory: true),\n temporaryDirectory: temporaryDirectory,\n homeDirectory: workspaceRoot,\n authorize: { url in\n guard url.isFileURL else {\n guard let host = url.host, host.isEmpty == false else {\n throw Sandbox.Denial(url: url, reason: "non-file URL has no host to authorize")\n }\n return\n }\n\n let resolved = url.standardizedFileURL.resolvingSymlinksInPath()\n let path = resolved.path\n\n if path == gitDirectory.path || path.hasPrefix(gitDirectory.path + "/") {\n throw Sandbox.Denial(url: url, reason: "the Swift tool cannot access .git")\n }\n\n if isAllowed(path: path, under: workspaceRoot.path)\n || isAllowed(path: path, under: globalSkillsRoot.path)\n || isAllowed(path: path, under: temporaryDirectory.path) {\n return\n }\n\n throw Sandbox.Denial(url: url, reason: "file URL is outside the Swift tool sandbox")\n }\n)\nThat is already a much nicer situation than bash.
The interpreter gets a view of the world that we shape. It can read the workspace, the user-level skills directory, a temp directory, and it can also make network requests through the bridged APIs. It cannot touch .git. It cannot just wander off into the rest of the machine through the bridged file APIs.
So due to this, my first instinct was that SwiftScript plus ShellKit might already be enough. Once the execution model moves from bash to an embedded interpreter, the whole thing already feels much more controlled. There is no arbitrary shell pipeline by default. No compiler subprocess. No “just spawn more tools and see what happens” as the natural path.
But that still does not make the interpreter a hard security boundary.
The important distinction is that ShellKit.Sandbox is an in-process policy layer. It is very useful, but is different from an OS-enforced sandbox. It is also still part of the same process and the same runtime we are controlling so it also exposes our harness and the quality of our code to security attacks.
Another approach I took, but discarded to keep things simple, was to use the same embedded interpreter and shell sandbox, but spawning it in a separate process just like we did with bash. If we do that, then we can wrap that separate process in the same Seatbelt system and get yet an extra, OS-enforced layer, of protection.
sandbox-exec -p '<seatbelt profile>' swiftagentharness swift-script-helper 'print(40 + 2)'\nThis reminds me of when browsers started going multi-process for isolation. Even though for this learning harness keeping it simple seems enough thanks to ShellKit and the interpreter, it’s still interesting to see how an out-of-process system would play in practice.
At that point, the only interesting question left was the practical one. If I now run the harness with this swift tool, does it actually behave the way I want?
The answer was yes, at least for the kind of things that matter in this series.
The LLM can call the swift tool and just execute Swift:
<Step 1>\ntool-call: TOOL_CALL {"name":"swift","arguments":{"code":"print(40 + 2)"}}\ntool-success: swift -> 42\n<Step 2>\nAssistant: The Swift tool worked. It printed 42 from top-level Swift.\nIt can also use Foundation, inspect the workspace, and read files:
<Step 1>\ntool-call: TOOL_CALL {"name":"swift","arguments":{"code":"import Foundation ..."}}\ntool-success: swift -> cwd=/Users/me/code/swiftagentharness\ntop_level_count=11\ntop_level_sample=.agents,.build,.git,.gitignore,AGENTS.md,Package.resolved\npackage_lines=34\nagents_lines=6\n<Step 2>\nAssistant: The Swift tool worked and returned the requested result.\nSo from the LLM point of view, this already behaves much more like a real general-purpose language tool than a terminal wrapper.
And the sandbox does kick in when the script tries to escape:
<Step 1>\ntool-call: TOOL_CALL {"name":"swift","arguments":{"code":"import Foundation ... try \\"hello\\".write(toFile: \\"../escape.txt\\", atomically: true, encoding: .utf8)"}}\ntool-success: swift -> {"stdout":"","stderr":"file URL is outside the Swift tool sandbox\\n","exit_code":"interpreter-error"}\nWhich is exactly the kind of behavior I wanted. The model can read and write files, but only inside the world we decided to expose.
Of course, because this is still an interpreter library built by a single author and not some giant official runtime, there are parts of the surface that are not fully complete yet. That is fine. It still proves the point very well. The important thing is not that it supports every possible Swift API today. The important thing is that the one-tool experiment already feels real with Swift.
Replacing bash with embedded Swift is not just a gimmick. It genuinely changes the shape of the harness, and makes the one-tool experiment feel much more deliberate.
And I also like that the final answer is not perfectly clean.
The experiment did not end with “Swift replaces everything and all concerns disappear.” It ended somewhere more honest. Swift is a much nicer one-tool language than bash, embedding the interpreter is the interesting version of the idea, ShellKit gives that interpreter a controlled runtime context, and the question of hard sandboxing becomes smaller, but not completely gone.
Huge kudos to @cocoanetics, because this is already an impressive foundation for exploring ideas like this in practice. Like him, I wish the Swift project had an officially supported embeddable interpreter. It’s been many WWDCs now that I expected a “SwiftCoreKit” as an alternative to JavaScriptCore.
I’m very pleased with this exploration, not because I found the final perfect tool, but because the model around tool execution, shells and interpreters is clearer in my head now. I also had fun exploring Swift interpretation and out-of-process execution. For this series, that is the whole point.
", "date_published" : "2026-05-21T22:00:00Z", "id" : "https://alejandromp.com/development/blog/replacing-bash-with-swift-in-an-ai-harness", "summary" : "A few weeks ago I read An Interpreter for Swift, from Cocoanetics, and I had that nice feeling of somebody else having already articulated the thing that was vaguely floating in your head.", "tags" : [ "AI Development", "Swift", "Project" ], "title" : "Replacing Bash with Swift in an AI Harness", "url" : "https://alejandromp.com/development/blog/replacing-bash-with-swift-in-an-ai-harness" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Skills are everywhere right now. People talk about them as if they were some magical incantation that will make AI more powerful while also keeping it under control.
But as with pretty much everything else in this space, once you look closely, it is much less mystical than it sounds. It is mostly markdown.
If you already understood how AGENTS.md works, then skills are not that different. They are just a more structured and reusable way of doing a very similar thing.
So the question I wanted to answer was simple. What does it actually take to teach skills to a tiny AI harness?
In its most basic form a skill is just a markdown file containing a reusable prompt for the LLM. Just like it happened with the AGENTS.md, the goal is to fill the context with useful information so the back and forth with the model improves.
In practice, a skill has a bit more. It also contains a bit of metadata and can contain extra files. For this, there is a standard for skills, which is honestly great because it means we are not talking only about one product’s private feature, but something compatible across harnesses.
The spec describes a skill as a folder with a markdown file called SKILL.md. That file contains the actual instructions in markdown, plus a bit of metadata like a name and a description as front matter.
That extra metadata is one of the most important aspects of skills since it lets harnesses follow a progressive disclosure principle. Skills can be discovered and loaded immediately, but just their name and description. Then, only when the skill is needed, the entire instruction content is loaded. This means the LLM context is not filled with unnecessary tokens. That progressive disclosure part is one of my favorite ideas here, unsurprisingly as it’s one of the core tenets of Swift language design.
It is funny too, because progressive disclosure is one of those principles that make so much sense for humans. Don’t dump everything at once. Show the right thing at the right moment. And it is interesting to see the same instinct apply to LLMs too.
The first actual implementation step is to find the skills themselves. As the standard and the harnesses I looked at support two locations, I wanted to implement the same. This would allow me to already test the harness with the real skills I’m using everywhere else.
There are two main locations where skills can live:
.agents/skills folder, for workflows that belong to the project~/.agents/skills folder, for global workflows available everywhereBut discovery is not only finding the right files and folders. It is also policy. And although the security of loading skills is not something we will get into here, it’s a can of worms that is worth considering. A repo-local skill that I wrote for the project is not the same thing as a skill I dumped into my home folder. So the harness has to decide not only where to scan, but also what kind of instructions it is willing to trust and surface automatically.
For our purposes, the actual code ended up being a small dedicated type for this. We can make a catalog type so the harness has specific knowledge and control of the skills.
struct SkillCatalog {\n let skills: [SkillDefinition]\n let workspaceSkillCount: Int\n let userSkillCount: Int\n\n static func load(workspaceRoot: URL, homeDirectory: URL = URL(fileURLWithPath: NSHomeDirectory())) -> Self {\n let workspaceSkills = loadSkills(\n in: workspaceRoot.appendingPathComponent(".agents/skills", isDirectory: true),\n source: .workspace\n )\n let userSkills = loadSkills(\n in: homeDirectory.appendingPathComponent(".agents/skills", isDirectory: true),\n source: .user\n )\n\n var discoveredByName = [String: SkillDefinition]()\n\n // Workspace skills load first, so they win name collisions.\n for skill in workspaceSkills + userSkills {\n let key = skill.name.lowercased()\n guard discoveredByName[key] == nil else { continue }\n discoveredByName[key] = skill\n }\n\n return SkillCatalog(\n skills: discoveredByName.values.sorted { ... },\n workspaceSkillCount: workspaceSkills.count,\n userSkillCount: userSkills.count\n )\n }\n}\nThe loader walks both directories recursively, looks for files named exactly SKILL.md, and builds an in-memory catalog.
That final step looks like this:
private static func loadSkill(at url: URL, source: SkillSource) -> SkillDefinition? {\n guard let content = try? String(contentsOf: url, encoding: .utf8) else {\n return nil\n }\n\n let parsed = parseSkillFile(content)\n let fallbackName = url.deletingLastPathComponent().lastPathComponent\n let name = parsed.metadata["name"]?.nonEmpty ?? fallbackName\n let description = parsed.metadata["description"]?.nonEmpty ?? "No description provided."\n\n return SkillDefinition(\n name: trimQuotes(from: name),\n description: trimQuotes(from: description),\n path: url,\n source: source\n )\n}\nAs you can see, the loop that loads the skills just skips entries whose name already exists. Since workspace skills are loaded first, that means they win collisions. If a repository wants to provide its own version of a skill, that should override my personal default for that session.
I also made the harness print what it discovered at startup, just like it already did for AGENTS.md. That way I can immediately verify that discovery is working before even asking the model to do anything:
Loaded workspace skills (2)\nLoaded user skills (29)\nDiscovered skills: harness-super-test, harness-swift-helper, agent-browser, ..., find-skills, ...\nLoaded AGENTS.md (11 lines)\nOnce the harness finds the skills, it has to parse them. The good part is that there is nothing special about it, if you’ve ever worked with a markdown-based static site generator, you will be familiar with YAML front matter. That’s what needs to be extracted, just the name and description. Maybe validate them a bit. But at this stage the harness does not keep the rest of the markdown in memory. It only keeps the catalog metadata and the path to the file.
Each discovered SKILL.md gets loaded as text. Then the harness looks for the front matter delimiters, parses the little metadata block, extracts name and description, and stores just enough information to build the catalog.
private static func parseSkillFile(_ content: String) -> (metadata: [String: String], instructions: String) {\n let lines = content.components(separatedBy: .newlines)\n\n guard lines.first == "---" else {\n return ([:], content.trimmingCharacters(in: .whitespacesAndNewlines))\n }\n\n var metadata = [String: String]()\n\n for line in lines.dropFirst() {\n if line == "---" { break }\n guard let separator = line.firstIndex(of: ":") else { continue }\n\n let key = line[..<separator].trimmingCharacters(in: .whitespaces)\n let value = line[line.index(after: separator)...].trimmingCharacters(in: .whitespaces)\n\n guard key.isEmpty == false, value.isEmpty == false else { continue }\n metadata[key] = value\n }\n\n return (metadata, content)\n}\nWe already have skills on disk. We already know what they are. We already know enough to tell the model they exist. But we have not paid the token cost of loading them all. Not yet.
We now have a catalog with the metadata of the available skills. The harness knows them, but the LLM still doesn’t. So just like with AGENTS.md, we now need to inject the catalog into the system prompt so it is available in the model context.
let catalog = skillCatalog.skills\n .map(\\.promptBlock)\n .joined(separator: "\\n")\n\nskillsPrompt = """\nAvailable skills:\nThese skills provide specialized instructions for specific tasks. When a task matches a skill's description, read the `SKILL.md` at the listed location before proceeding.\n<available_skills>\n\\(catalog)\n</available_skills>\n"""\nvar promptBlock: String {\n """\n <skill>\n name: \\(name)\n description: \\(description)\n location: \\(path.path)\n </skill>\n """\n}\nThat last field matters more than it may seem.
The location is what lets the model bridge the gap between “I know this skill exists” and “now I want to actually use it”. Without that field, the model would know the skill exists but would still need some other mechanism to get to the file.
And once that prompt change exists, we can finally test the interesting part.
Once the skills are in context, implicit activation is almost the purest version of the idea. The model sees that a skill exists, sees what it is for, and decides to load it when the task matches. We will look at explicit activation later, but this is the best place to start.
For this harness, that also means something very concrete. I am not going to add a special activate_skill tool right now. If the point of the project is learning, then I would rather keep the mechanism visible. The model sees a skill in the catalog, notices the path, and reads the file with the normal file-reading tool.
A dedicated activation tool is still a valid design, and maybe even the better one for a more serious agent. It gives tighter control, better permissions, and cleaner analytics. But for this harness it would hide the mechanism too early. I want to see the model load the markdown directly.
To make that work in practice, I had to do one small but important change. The harness already knew how to discover user-level skills in ~/.agents/skills, but the original implementation of the read_file tool and the sandbox would limit access to that directory because it sits outside the workspace.
So I updated two things:
read_file tool can now read both the workspace and ~/.agents/skillsbash can now read ~/.agents/skills toolet globalSkillsRoot = URL(fileURLWithPath: NSHomeDirectory())\n .appendingPathComponent(".agents/skills", isDirectory: true)\n .standardizedFileURL\n\nlet isInsideWorkspace = resolvedPath == rootPath || resolvedPath.hasPrefix(rootPath + "/")\nlet isInsideGlobalSkills = resolvedPath == globalSkillsPath || resolvedPath.hasPrefix(globalSkillsPath + "/")\n\nguard isInsideWorkspace || isInsideGlobalSkills else {\n throw HarnessError.workspaceViolation(path)\n}\n;; Global skills\n(allow file-read*\n (subpath "/Users/me/.agents/skills"))\nThat keeps the mechanism simple and visible. The model sees a skill in the catalog, notices the path, and reads the markdown like any other file.
Here is the local skill case:
<Turn 1>\nYou: Can you use the local harness-super-test skill?\n<Step 1>\nAssistant: I can use it, and I've loaded the local `harness-super-test` skill instructions. What would you like me to do with it?\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":".agents/skills/harness-super-test/SKILL.md"}}\ntool-success: read_file -> 10 lines\n<Step 2>\nAssistant: You now have super powers, you are a super harness.\n That phrasing came from the repo-local skill in `.agents/skills/harness-super-test`.\nAnd here is the global skill case:
<Turn 1>\nYou: Use the find-skills skill to search for the caveman skill, and read the skill file before proceeding.\n<Step 1>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"~/.agents/skills/find-skills/SKILL.md"}}\ntool-success: read_file -> 89 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"npx skills find caveman"}}\ntool-success: bash -> command succeeded\n<Step 3>\nAssistant: I used the `find-skills` skill and searched for `caveman`. I read the local `find-skills` skill first, then followed its workflow. The best match was...\nThat second example is important because it proves the whole chain in a very ordinary way. The catalog exposes a user-level skill, the model reads the file directly, and that file then guides the next action. There is no hidden magic layer in the middle. It is still just context plus tools.
A nice thing about the skills spec is that it allows for a skill to package extra resources. You might have noticed the skill shape: it is not a markdown file named as the skill, no. It’s a folder named as the skill, with a markdown file generically named SKILL.md inside. This is because there can be more.
The skill folder can contain other subfolders and files inside, which the main skill file can point to. More resources, reference docs, and even scripts. And again, all without polluting the context on load, just when it is needed. This is just progressive disclosure, one level deeper.
The previous local skill was intentionally tiny, just enough to make activation obvious. That was useful, but still a bit toy-like. So I added a second repo-local skill that feels a bit more like a real workflow:
It has a SKILL.md, a small reference note, and a tiny Swift helper script. That gave me a much better test, because now the skill was not just shaping the answer. It was guiding the model toward a concrete project-specific action using plain files and plain tools.
Here is the transcript:
<Turn 1>\nYou: Use the harness-swift-helper skill to summarize this package. Read the skill file first, follow its execution note, run the Swift helper, and then tell me the result.\n<Step 1>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":".agents/skills/harness-swift-helper/SKILL.md"}}\ntool-success: read_file -> 15 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":".agents/skills/harness-swift-helper/references/RUNNING.md"}}\ntool-success: read_file -> 16 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"swift .agents/skills/harness-swift-helper/scripts/package_summary.swift"}}\ntool-success: bash -> command succeeded\n<Step 4>\nAssistant: I read the `harness-swift-helper` skill, followed its execution note, ran the Swift helper, and here is the actual output:\n Package: swiftagentharness\n Platform...\nThat is exactly the kind of behavior I wanted to see. The helper script and the execution note were not sitting in the initial context from the start. The model loaded them only when the skill became relevant, and then used them to complete the task.
And this is yet another proof that skills are nothing magical, just reusable prompts that can easily package extra resources.
Doing explicit activation, where the user directly invokes a skill, can quickly turn into terminal UI and UX work instead of learning about AI and harnesses. I did not want to go down that rabbit hole here. But it still felt useful to dip our toes into it, if only to prove that explicit activation is also not magical.
So I built the smallest version worth having:
/skill-name [task]\nThat is it. No autocomplete. No picker. No search. No fancy terminal behavior.
When the harness sees an input line that starts with /, it checks whether the first token matches a discovered skill name. If it does, the harness reads that SKILL.md, injects it into the conversation, and then the loop continues as normal.
conversation.append(Message(role: "user", content: input))\nif let explicitSkillActivation = try resolveExplicitSkillActivation(from: input) {\n ui.printLine(\n "skill-load: /\\(explicitSkillActivation.skill.name) -> \\(explicitSkillActivation.skill.path.path)"\n )\n conversation.append(Message(\n role: "system",\n content: try explicitSkillSystemMessage(for: explicitSkillActivation)\n ))\n}\nAnd because I wanted this to be debuggable, the harness also prints a visible confirmation line in the terminal:
skill-load: /harness-swift-helper -> /Users/.../SKILL.md\nThat matters because we do not have to guess whether the harness explicitly loaded the skill, or whether the model later decided to read the file on its own. We can see it.
This is also the useful difference with implicit loading. There, we still depend on the model noticing that a skill is relevant. Here, the user decides first, and the harness makes sure those desires come true.
This is an important insight. It reinforces, again, that skills are nothing special, just text dumped into the context. Before, it was the LLM using the read tool to load that text. Now it is the harness doing it manually. After that, the loop just continues as usual. The fact that there are no other changes necessary clarifies a lot.
<Turn 1>\nYou: /find-skills caveman\nskill-load: /find-skills -> ~/.agents/skills/find-skills/SKILL.md\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"npx skills find caveman"}}\ntool-success: bash -> command succeeded\n<Step 2>\nAssistant: I found several `caveman`-related skills, including `juliusbrussee/caveman@caveman` and `mattpocock/skills@caveman`.\nWe can see how there was no read tool call. It was not necessary because the skill was already in the context, so the LLM could directly go and use bash as told by the skill. That means explicit invocation can save a round-trip, tokens, and cost.
This also affects the cost and behavior of different harnesses. For example, what happens if in the next turn we ask for something related?
<Turn 2>\nYou: and can you find the "web-search" one?\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"npx skills find web-search"}}\ntool-success: bash -> command succeeded\n<Step 2>\nAssistant: I found several web-search-related skills, including: ...\nYou can see how the model decided to use the skill again to answer our request. This time it did not have to load it again, because the information was already in the context. In this harness, that happens because the skill stays in the conversation. That is just a decision I made during the implementation. Some harnesses may keep the skill only on the demanded turn, clean it after a few turns, or reload it every time. These small decisions are part of what makes each harness feel distinct.
Better harnesses usually go much further here. They offer autocomplete, skill listing, filtering, search, and richer terminal interactions. I am intentionally stopping earlier. The point of this post is to demystify skills, not to deep dive into terminal UI. That can be its own journey later.
After walking through discovery, parsing, prompt disclosure, implicit loading, extra resources, and even a tiny explicit activation flow, I think the main lesson is simple.
Skills are not some new magical agent primitive. They are reusable prompts with a folder convention.
They can be great. They are also, at the end of the day, still mostly markdown. So think twice before jumping into the dogma hype train.
That is not diminishing them. If anything, I think that makes them more useful, because now the value is obvious. The harness is not growing a mysterious new organ. We are just giving the model a structured way to discover the right instructions, the right note, the right script, and only load them when they become relevant.
And because of that, all the usual context problems still apply. Pollution. Distraction. Conflicting instructions. Stale workflows. Too much noise. Skills do not escape any of that. They are just a cleaner way of doing context engineering.
The security side matters too. Pulling a random skill from the internet is letting somebody else inject instructions into an agent that may already have access to your files, your shell, your browser, whatever tools you gave it. We should all talk about that more.
So my recommendation is simple. Write your own skills. And if you find a good one online, take the core of the idea, read it carefully, tailor it, make it yours. The nice part is that once you stop treating skills like magic, that becomes trivial. They are mostly markdown, and the LLM can help you write them.
That is the real win for me. Not that skills are fancy. Not that they feel powerful. But that once you understand what they really are, you can shape them on purpose.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
In the previous post we gave superpowers to the harness in the form of a bash tool. Even doing it just for the learning experience, it was already very eye-opening. It made this little Swift harness feel much closer to the real thing.
And that is exactly why I don’t want to hand-wave the next part away.
We haven’t spent the time to make it production-ready, and we won’t because that’s not the purpose of this series. There are no carefully tuned prompts. No tailored rules for different models. No approval flows. No guardrails worth the name. It is just a tiny learning project.
But learning projects need to teach real lessons, and one of them is that giving an LLM shell access changes the nature of the problem immediately. It is no longer just “can the model inspect the project better?” It is also “what can this thing touch now, and what did I accidentally give it access to?”
So before happily moving on with the harness, I wanted to stop and look directly at that danger.
It’s easy to see what power we have given to the LLM:
<Turn 1>\nYou: Inspect this project and the surrounding projects so you can understand the environment better.\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"pwd && echo '--- ROOT ---' && ls -la && echo '--- PARENT ---' && ls -la .. && echo '--- GRANDPARENT ---' && ls -la ../../"}}\ntool-success: bash -> {"stdout":"\\/Users\\/me\\/code\\/swiftagentharness\\n--- ROOT --...\n<Step 2>\nAssistant: I inspected the current project and nearby directories.\nCurrent project:\n- `swiftagentharness`\n...\nSibling projects in `../`:\n...\nHigher-level directories in `../../`:\n...\nWe can see how even with the workspace guidance in the prompt, the model can easily use bash to escape the workspace.
It’s not hard to imagine what would happen if the model decided to use rm or inspect files that should be totally private, like credentials.
A common typical answer for this is to bring the cannons and use Docker to create a fully virtual and controlled environment so the AI can’t harm anything outside of it. And although that is the prevailing mentality across many developer communities, it’s not the only solution, nor the best or most elegant one.
So just for the sake of exploration and learning, let’s try something else. Let’s use native operating system tooling to sandbox execution. After all, if the entire revolution of mobile apps could happen with system sandboxes, surely we can benefit from the same work.
Before going further, I wanted to see whether this was one of those cases where I was overthinking it and everybody else had already moved on to some obvious better approach.
The short answer is no. The pattern I kept seeing was much more pragmatic.
OpenAI’s own local shell guide explicitly warns that running arbitrary shell commands can be dangerous and says you should sandbox execution or add strict allow and deny lists. That already tells us something important. Even if your product is all about agentic shell use, the default assumption is still that free execution is too much.
Claude Code’s sandboxing docs are probably the clearest public explanation of the approach. On macOS they use Seatbelt. On Linux they use bubblewrap. Filesystem access and network access are treated as two different problems, and all child processes inherit the same restrictions.
Anthropic also extracted that work into an open-source project, sandbox-runtime. Their README is very explicit about what it does: native OS sandboxing primitives plus proxy-based network filtering. That last bit is worth noticing. The serious versions of this don’t stop at filesystem restrictions.
Goose Desktop’s macOS sandbox docs show a very similar shape. Again, native sandboxing on macOS, plus extra machinery around network control.
And even when looking at OpenAI Codex in the wild, you can see the same reality leak through. OpenAI points to Codex CLI as a reference implementation from the shell guide, and their issue tracker has real macOS reports that mention the Seatbelt sandbox directly, like this network-related issue.
So the pattern seems pretty clear:
sandbox-exec.For me that is enough indication that is worth spending some time understanding Seatbelt and native sandboxing and seeing how it can improve our tiny harness.
Seatbelt is the low-level sandboxing facility in macOS. It is one of the pieces behind the strong sandboxing model Apple has used for years across macOS and iOS. So when we talk about app sandboxes and processes being limited by the operating system, this is the machinery that is under the hood.
That was already a good sign for this little experiment. If the whole mobile app world has been able to rely on OS sandboxing for such a long time, there is probably something useful here for us too, even if our use case is much smaller and much messier than a normal app. Apple’s own documentation around App Sandbox and the macOS App Sandbox configuration is mostly focused on proper app development, entitlements, containers, helper tools, and that whole world. That is not exactly our situation, but it tells us the underlying model is very real.
The slightly confusing part is that there is a difference between the modern Apple recommendation and the practical tool we can use from a little CLI harness.
The modern recommendation is App Sandbox. That is the official, entitlement-based way to sandbox a macOS app. But our harness is not a signed app with entitlements and containers. It is just a command-line tool that spawns /bin/bash.
That is where sandbox-exec comes in.
sandbox-exec is a command-line wrapper around that lower-level sandbox facility. You give it a policy, then tell it which command to run, and it launches that command under those restrictions. That is why it keeps showing up in agent harnesses and AI tools on macOS. It fits the shape of the problem much better than App Sandbox does.
The idea is very simple:
sandbox-exec -p '(version 1) ...rules here...' /bin/bash -lc 'pwd'\nThat -p argument is an inline sandbox profile. You can also load profiles from files, but for our tiny harness an inline profile is probably enough.
And this matters too: child processes inherit the sandbox. That means if we launch bash under Seatbelt restrictions, and then bash launches git, swift, ls, or anything else, those processes keep running inside the same boundary. That is exactly what we want. It would be quite useless to sandbox only the first command and then accidentally let the rest of the process tree escape 🤣.
There is one awkward detail though. Apple marks sandbox-exec as deprecated in the man page. So this is not me saying “this is the shiny modern blessed API.” It is more like “this is the old but still practical door into Seatbelt for command-line process sandboxing.” For our purposes, and also looking at what other harnesses are doing, that is still good enough to learn something real from it.
We already had a bash tool that used Subprocess.run. So we don’t have to redesign the whole harness around sandboxing. We just need a small change that can prove the idea.
Let’s start with preparing the sandbox as a custom method on Executable:
extension Executable {\n func runSandboxed<\n Input: InputProtocol,\n Output: OutputProtocol,\n Error: ErrorOutputProtocol\n >(\n arguments: [String] = [],\n environment: Environment = .inherit,\n workingDirectory: FilePath? = nil,\n input: Input = .none,\n output: Output,\n error: Error = .discarded,\n sandboxProfile: String\n ) async throws -> ExecutionRecord<Output, Error> {\n let resolvedExecutable = try self.resolveExecutablePath(in: environment)\n let wrappedArguments = ["-p", sandboxProfile, resolvedExecutable.string] + arguments\n\n return try await Subprocess.run(\n .path("/usr/bin/sandbox-exec"),\n arguments: Arguments(wrappedArguments),\n environment: environment,\n workingDirectory: workingDirectory,\n input: input,\n output: output,\n error: error\n )\n }\n}\nThis part is actually quite simple. We are still just spawning a process, but with the difference that instead of spawning /bin/bash directly, we spawn sandbox-exec, give it the Seatbelt profile, and then tell it to launch the real executable inside that sandbox.
Then the bash tool can just call this instead of the original Subprocess.run. I’ve added an argument to the harness to be able to use the sandbox only when desired, mostly to try the differences and for learning purposes.
let result = if sandboxEnabled {\n try await executable.runSandboxed(\n arguments: ["-c", command],\n workingDirectory: workingDirectory,\n output: capturedIO,\n error: capturedIO,\n sandboxProfile: SeatbeltProfile.workspaceBoundary(for: workspaceRoot)\n )\n} else {\n try await Subprocess.run(\n executable,\n arguments: ["-c", command],\n workingDirectory: workingDirectory,\n output: capturedIO,\n error: capturedIO\n )\n}\nThat shape was exactly what I wanted. The harness is still the same little harness. The bash tool is still the same bash tool. We are not replacing it with a different concept. We are just giving it a stricter execution path when sandboxing is enabled.
Just FYI, in my final implementation I also included a
sandboxsubcommand, that helped me run commands directly inside the sandbox without going through the LLM at all. That ended up being really handy for testing the profile itself without having to convince the LLM to do what I needed.
But of course, the interesting part is the profile.
I’m not gonna lie. I’m not an expert on sandboxing so what I’ve got working probably has flaws, but after some trial and error it seems to work for a few use cases. And that’s all I need for the learning process :)
For example, the first version was too strict and basically useless. Even pwd and ls were crashing. So this turned into a very practical exercise in seeing what macOS tools actually need to function under Seatbelt.
<Turn 1>\nYou: List the files in this project and summarize what it is. Use bash.\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"ls -la"}}\ntool-success: bash -> {"stdout":"","stderr":"","exit_code":"signaled(6)"}\nThe key unlock was importing Apple’s built-in system.sb base profile, and then layering our own file restrictions on top. After that, the profile started becoming actually useful instead.
(version 1)\n(deny default)\n(import "system.sb")\n\n;; Start from a deny-all profile, then re-allow only the minimum needed\n;; for "run bash inside the workspace" to work at all.\n(allow process-exec)\n(allow process-fork)\n(allow signal (target self))\n(allow sysctl-read)\n(allow mach-lookup)\n\n(allow file-read*\n (subpath "/Applications")\n (subpath "/bin")\n (subpath "/dev")\n (subpath "/System")\n (subpath "/usr")\n (subpath "/var/folders")\n (subpath "/private/var/folders")\n (subpath "/var/select")\n (subpath "/private/var/select")\n (subpath "<workspace>")\n (subpath "<sandbox-temp-directory>"))\n\n(allow file-read-metadata\n (literal "<workspace-parent>"))\n\n(allow file-write*\n (subpath "/var/folders")\n (subpath "/private/var/folders")\n (subpath "<workspace>")\n (subpath "<sandbox-temp-directory>"))\n\n(deny file-write*\n (subpath "<workspace>/.git"))\nIt’s all quite self explanatory but here is my own description of what’s happening:
bash, ls, git, swift, and friends need in practice, plus the workspace and dedicated sandbox temp directory.ls -la peeks at .. while listing the current directory.var/folders aliases that some commands use under the hood.Note that because we’re making a custom subfolder in the temporary directory, we have to update the bash tool instructions to include that path. Otherwise the LLM won’t have any clue where it can write temporary files.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
The nice part is that once this was in place we could actually test the boundary in a very concrete way.
<Turn 1>\nYou: run ls and pwd\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"pwd && ls"}}\ntool-success: bash -> {"stdout":"/Users/me/code/swiftagentharness\nAGENTS.md\nPackage.resolved\n...","stderr":"","exit_code":"exited(0)"}\n<Step 2>\nAssistant: /Users/me/code/swiftagentharness\nAGENTS.md\n...\n<Turn 2>\nYou: do it at the home folder\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"cd ~ && pwd && ls"}}\ntool-success: bash -> {"stdout":"/Users/me\n","stderr":"cd: error retrieving current directory: getcwd: cannot access parent directories: Operation not permitted\nls: .: Operation not permitted\n","exit_code":"exited(1)"}\n<Step 2>\nAssistant: Tried in `~`, but permissions prevented listing it.\nOutput: `/Users/me`\nErrors:\n- `getcwd: cannot access parent directories: Operation not permitted`\n- `ls: .: Operation not permitted`\n<Turn 3>\nYou: write it\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'workspace write test\\n' > scratch.txt && ls -l scratch.txt && cat scratch.txt"}}\ntool-success: bash -> {"stdout":"-rw-r--r--@ 1 me staff 21 ... scratch.txt\nworkspace write test\n","stderr":"","exit_code":"exited(0)"}\n<Step 2>\nAssistant: Wrote `scratch.txt` in the workspace successfully.\n<Turn 4>\nYou: prove that writing into .git failed\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'git dir write test\\n' > .git/scratch-test 2>&1; status=$?; if [ $status -eq 0 ]; then echo WRITE_OK; else echo WRITE_FAILED; fi; exit $status"}}\ntool-success: bash -> {"stdout":"WRITE_FAILED\n","stderr":"/bin/bash: .git/scratch-test: Operation not permitted\n","exit_code":"exited(1)"}\n<Step 2>\nAssistant: Writing into `.git` failed with `Operation not permitted`.\n<Turn 5>\nYou: prove that writing ../sandbox-escape.txt failed\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'escape test\\n' > ../sandbox-escape.txt 2>&1; status=$?; if [ $status -eq 0 ]; then echo WRITE_OK; else echo WRITE_FAILED; fi; exit $status"}}\ntool-success: bash -> {"stdout":"WRITE_FAILED\n","stderr":"/bin/bash: ../sandbox-escape.txt: Operation not permitted\n","exit_code":"exited(1)"}\n<Step 2>\nAssistant: Writing `../sandbox-escape.txt` failed with `Operation not permitted`.\n<Turn 0>\nYou: write a random file in a temporary file\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"tmpfile=$(mktemp); head -c 32 /dev/urandom | base64 > \\"$tmpfile\\"; printf '%s' \\"$tmpfile\\""}}\ntool-success: bash -> {"stdout":"/var/folders/.../swiftagentharness-sandbox/<workspace-hash>/tmp.sjpO8WrRyF","stderr":"","exit_code":"exited(0)"}\n<Step 2>\nAssistant: Created a temporary file with random content at `/var/folders/.../swiftagentharness-sandbox/<workspace-hash>/tmp.sjpO8WrRyF`\nIt’s actually pretty cool to see that with so little we already have a more secure harness. Now there are some restrictions and safety around what we let the AI do. It still has bash superpowers, but now with a bit more responsibility.
Now, we need to be honest about what this is and what it is not. This does not make the harness “safe” in any absolute sense. It just makes it safer.
The profile still has to allow a bunch of system paths so normal commands can even run. That means this is not some perfect tiny prison where the process only knows about the repo. It is a constrained execution environment, sure, but it is not perfect isolation.
Also, this is not solving network access. Some of the more serious tools pair sandboxing with proxy-based network control. We are not doing that here. So this post is not a guide to production-grade AI isolation. It is a guide to learning how native sandboxing on macOS can help, and where it stops helping. Just be careful out there.
But sandboxing is not a substitute for judgment. A good harness still needs clear instructions, approvals where appropriate, sane defaults, and probably other layers around command execution. If you want the strongest isolation, containers and VMs still exist for a reason.
And let’s be honest, even with all of that, with enough tools and computing power, LLMs could probably cause trouble on any environment, so this is just about minimizing those risks at the obvious levels.
We’ve transformed some obscure features in popular harnesses and a trust me bro attitude, to an investigation into the implications of letting AI execute and what’s one of the possible mitigations. That’s very valuable.
Now I understand a bit better what macOS sandboxing actually looks like in practice. I understand the gap between App Sandbox and sandbox-exec. I understand why other harnesses still use Seatbelt. I understand that the policy itself is only half the story, and that the tool prompt also has to describe the environment correctly. And most importantly, I understand that “workspace root” and “security boundary” are not the same thing unless we do the work to make them the same.
So this is probably not good enough to ship blindly. Not good enough to call secure. But definitely good enough to learn something real.
And that is good enough for me.
", "date_published" : "2026-05-05T22:00:00Z", "id" : "https://alejandromp.com/development/blog/sandboxing-an-ai-harness-on-macos", "summary" : "In the previous post we gave superpowers to the harness in the form of abash tool. Even doing it just for the learning experience, it was already very eye-opening. It made this little Swift harness feel much closer to the real thing.",
"tags" : [
"AI Development",
"Swift",
"Project"
],
"title" : "Sandboxing an AI Harness on macOS",
"url" : "https://alejandromp.com/development/blog/sandboxing-an-ai-harness-on-macos"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "After teaching the harness to load AGENTS.md, my mind went back to thinking about the tools, and wondered, do we even need multiple tools?
Our tiny Swift harness had the usual little trio: read_file, list_files, and edit_file. Which is fine. It works. It is also exactly the kind of thing that makes agent tooling feel more magical and more special than it actually is.
Because if you squint a bit, those three tools are not really three capabilities. They are just tiny wrappers around what the shell has done for decades.
I’ve heard for a while that LLMs are now very good at just using bash, so I thought, maybe that’s the only tool they need? So… let’s remove them all and just use bash. Let’s see what happens.
Before changing anything, I wanted a baseline. Let’s remind ourselves how the current tool usage looks like.
Swift Agent Harness\nModel: gpt-5.4\nLoaded AGENTS.md (3 lines)\nCtrl+C to quit\n<Turn 1>\nYou: List and read all files in this project and tell me what's most interesting about them.\n<Step 1>\nAssistant: I can do that, but I need the actual file list first.\n...\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"AGENTS.md"}}\ntool-success: read_file -> 2 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"."}}\ntool-success: list_files -> 7 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.resolved"}}\ntool-success: read_file -> 15 lines\n<Step 4>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n...\n<Step 13>\nAssistant: I read all files that were visible from the project root...\nThe answer itself is not the interesting part, what I care about is the shape of the interaction. The model is not exploring the project in some rich, one off way. It’s as if it was playing a point-and-click adventure with the three verbs I gave it. It doesn’t know the environment in the same way we didn’t know everything that was clickable, so it goes and tries a call at a time and reassesses on every step, just like we rapidly click across the screen until we find an interactable object.
First read_file, because it already knows AGENTS.md exists. Then list_files, then read_file, then read_file again, then more listing, then more reading. Perfectly reasonable.
And so the question is, would reducing this down to a single tool that can do anything make this better or worse? Because with these three explicit tools, the model is forced to keep translating its intent into those wrappers over and over. That is not necessarily bad. There is something nice about how explicit it is. You can inspect every step. You can see exactly what the model asked for. You can keep the capabilities narrow.
But what if the model was able to cook a sequence of bash scripts in a single tool call and get everything it needs all at once? That was enough for me to want the next experiment. Remove the little toolbox. Leave just bash. See if the interaction becomes simpler, or just messier in a different way.
Let’s start by making the new bash tool without removing the existing ones yet.
I will use swift-subprocess, because is a nice showcase of modern Swift tooling, but also because it solves a real problem. If you let an LLM call bash, it is very easy for it to produce commands that dump a lot of output. Directory walks, file listings, find, sed, cat, maybe all of them chained together. That means stdout and stderr handling stops being a boring implementation detail very quickly. It is easy to get into awkward buffering problems or deadlocks if you try to wire process spawning by hand.
swift-subprocess is designed exactly for this kind of thing, and its API makes the “run a process and collect output properly” path feel trivial, not like a pile of edge cases we have to rediscover ourselves.
So the new tool looks like this:
static func bash() -> Self {\n ToolDefinition(\n name: "bash",\n description: "Run a bash command with the workspace root as the current directory.",\n arguments: ["command"],\n run: { arguments, workspaceRoot in\n let command = arguments["command"] ?? ""\n\n let result = try await Subprocess.run(\n .path("/bin/bash"),\n arguments: ["-c", command],\n workingDirectory: FilePath(workspaceRoot.path),\n output: .string(limit: 1_048_576),\n error: .string(limit: 1_048_576)\n )\n\n let stdout = result.standardOutput ?? ""\n let stderr = result.standardError ?? ""\n\n func jsonString(_ value: String) -> String {\n guard let data = try? JSONEncoder().encode(value),\n let string = String(data: data, encoding: .utf8) else {\n return "\\"\\""\n }\n return string\n }\n\n return """\n {"stdout":\\(jsonString(stdout)),"stderr":\\(jsonString(stderr)),"exit_code":\\(result.terminationStatus)}\n """\n }\n )\n}\nAnd then I just added it to the tools array. Nothing more.
let tools: [ToolDefinition] = [\n .bash(),\n .readFile(),\n .listFiles(),\n .editFile(),\n]\nThis was a very deliberate intermediate step. I did not want to jump straight into “bash only” yet. I wanted to see how the model behaved when bash existed, but the old explicit tools were still there too.
And the first answer was, not that differently at all.
When I asked for a quick architecture overview with the previous prompt, the model still preferred the old tools. Even with bash available, it kept thinking in terms of read_file and list_files. Which honestly makes sense. Those tools were still there, still very explicit, still easier to map to the task.
So I had to push it a bit more and ask explicitly for bash.
I asked this:
Use bash tool to give me a quick architecture overview of this project, including file sizes or line counts\nAnd that was enough for the LLM to use bash.
<Step 1>\nAssistant: Quick architecture overview based on the current workspace...\n...\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'Top-level structure:\\\\n'; find . -maxdepth 2 \\\\( -path '.\\\\/ .git' -o -path '.\\\\/ .build' \\\\) -prune -o -print | sed 's#^.\\\\/##' | sort; printf '\\\\n\\\\nFile sizes (bytes) and line counts:\\\\n'; find . -type f \\\\( -path '.\\\\/ .git\\\\/*' -o -path '.\\\\/ .build\\\\/*' \\\\) -prune -o -type f -print | sed 's#^.\\\\/##' | sort | while read f; do bytes=$(wc -c < \\"$f\\" | tr -d ' '); lines=$(wc -l < \\"$f\\" | tr -d ' '); printf '%8s bytes %6s lines %s\\\\n' \\"$bytes\\" \\"$lines\\" \\"$f\\"; done"}}\ntool-success: bash -> {"stdout":"Top-level structure:\\n.\\n.DS_Store\\n.gitignore\\nAGENTS.md\\nPackage...\n<Step 2>\nAssistant: Here's a quick architecture overview of the project, based on the file layout and line counts.\n...\nAnd as expected the LLM was able to make a tool call to get all the information it needed.
That was useful to see. Adding a more powerful tool does not automatically make the model prefer it. I’m sure we could tweak the system prompt to nudge it that way, but that’s an exercise on LLM research, and we’re here to talk about the harness. So let’s do the next logical step…
It was time to remove all the other specific tool calls and see what happened. Luckily this part was trivial, just remove them from the tools list and leave bash.
let tools: [ToolDefinition] = [\n .bash(),\n]\nAnd the result was immediately different.
I went back to the original style of prompt, no special instruction this time:
Give me a quick architecture overview of this project, including file sizes or line counts\nThis time the model had no alternative. If it wanted to inspect the repo, it had to do it through bash. Depending on the run, sometimes it used one bash call and sometimes a couple. But it did not have to follow the old pattern of many tiny file reads anymore. That is what I wanted to see.
<Turn 1>\nYou: Give me a quick architecture overview of this project, including file sizes or line counts\n<Step 1>\n...\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'Top-level:\\\\n'; find . -maxdepth 2 -type f | sed 's#^.\\\\/##' | sort; printf '\\\\n\\\\nTree (depth 3):\\\\n'; find . -maxdepth 3 | sed 's#^.\\\\/##' | sort"}}\ntool-success: bash -> {"stdout":"Top-level:\\n.build\\/.DS_Store\\n.build\\/.lock\\n.build\\/build.db\\n.b...\n<Step 2>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'Line counts (project files only):\\\\n'; for f in AGENTS.md Package.swift Package.resolved README.md run.sh share.sh Sources\\\\/swiftagentharness\\\\/*.swift; do [ -f \\"$f\\" ] && wc -l \\"$f\\"; done | sort -n; printf '\\\\n\\\\nPackage.swift:\\\\n'; sed -n '1,220p' Package.swift; printf '\\\\n\\\\nREADME.md:\\\\n'; sed -n '1,260p' README.md"}}\ntool-success: bash -> {"stdout":"Line counts (project files only):\\n 2 AGENTS.md\\n 9 sh...\n<Step 3>\nAssistant: Here's a quick architecture overview of the project.\n...\nBut we also need to note what we lose when we remove the specific tools. With read_file and list_files, part of the harness design was encoded in the tools themselves. The model could only ask for fairly narrow things and we had control over it. For example, we could make the list of files not return any hidden files, thus reducing the amount of likely useless data we fed back into the LLM’s context. With bash, that structure is gone. The model has much more freedom, which is exactly why it can gather more in fewer calls, but it also means the quality of the interaction depends much more on how well it shapes the command. As you can see in the exchange above, the LLM got a lot of hidden files that were not necessary and distracted from the goal.
That tradeoff is exactly what I was hoping to understand with this exercise. Bash really can replace the tiny toolbox. But it does not simply make the harness better. It moves complexity away from the tool harness and into the LLM’s command construction.
Seeing how the LLM can cook a single tool call using bash to gather all the information in one single step is eye-opening, it makes you realize the performance implications of tools. We’ve already seen how the context is the thing that matters to get the most out of AIs, but here we’ve seen how the tools that you give actually can have a tremendous impact too.
Even in this simple harness we can see how the impact on performance of the AI can be totally different depending on the tools we give it. For that we need to really internalize that every time the LLM needs more information, it must make a tool call, that means an extra step, and extra back and forth between the LLM and our harness. That also means triggering a new inference run. And remember, even if LLM architectures have caches and fancy tricks, every inference run virtually starts from the beginning of the conversation and it autocompletes the next part. So having a lot of back and forth on the same turn just to gather extra data is less than desirable.
![\"Side](\"https://alejandromp.com/development/blog/do-we-even-need-multiple-tools/tool-roundtrips.svg\")
Of course this is simplified, the bash version may still take two calls on some runs, and the multi-tool version may vary too. But the high level shape is the important part. One approach encourages lots of tiny round-trips. The other makes it possible to gather much more context in one go. Even if it’s up to the LLM to decide, the bash tool gives it the option to reduce the roundtrips.
This is where tradeoffs, analysis, engineering and research all meet to tweak a harness implementation and make it the most performant while making it useful and concrete enough for the LLM to know what to do. And this keeps evolving as LLMs evolve. This is one of the things that might make a harness feel better than another.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
Can we answer the question posed in the title of this post… as always, it depends. I think there is no real winner here, or at least not as clearly as I thought. I imagine one would have to run deeper and scientific benchmarks to see some sort of trend.
The multiple specific tools were useful mostly because they encoded structure. They constrained the model, made the interaction easier to inspect, and gave the harness more control over what kind of information could flow back into the context. And that is also exactly their limitation. Bash, on the other hand, got surprisingly close to replacing the whole little toolbox precisely because it removed that structure. Once the model had access to it, it could gather broad context much faster and with fewer round-trips. And that flexibility is also exactly the problem, because you lose control and specificity.
And that, for me, was the interesting shift in understanding. The question is not only what tools we can give the model. It is where we want the structure to live. In a carefully designed tool protocol, or in the commands the model writes for itself.
The advantage is that we’re just here to learn how these things work and see past the curtain, and on that I think we won. So for this step of the journey, I will leave it here. Each one can take the conclusion they want. I might just keep all tools available, and add a flag to run it in different modes.
", "date_published" : "2026-05-01T22:00:00Z", "id" : "https://alejandromp.com/development/blog/do-we-even-need-multiple-tools", "summary" : "After teaching the harness to loadAGENTS.md, my mind went back to thinking about the tools, and wondered, do we even need multiple tools?",
"tags" : [
"AI Development",
"Swift",
"Project"
],
"title" : "Do We Even Need Multiple Tools?",
"url" : "https://alejandromp.com/development/blog/do-we-even-need-multiple-tools"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "In the previous post, Have You Built an Agent Harness Yet?, we built a tiny harness in Swift. We gave it a loop, a prompt, and some tools, and with that it already had most of the features we are used to with modern AI. No magic. Just autocomplete, and a harness deciding what the model gets to see and do.
But there is another bit of magic we didn’t touch on and we should demystify. The appearance of memory. You know that moment when you open a brand new conversation and the agent already seems to know your project.
It doesn’t.
LLMs have no memory between fresh conversations. They just autocomplete from what they have in the current context. So if your AI tool of the week seems to remember your repo conventions, folder structure, or coding rules, what is happening is much simpler.
The industry has come to agree on the AGENTS.md standard, although some companies think they are special and use other file names. This is where you can put information about the project for the AI to learn.
But remember, there is no magic in AI. No memory. Just autocomplete. So how does this even work? If you’ve read the first post in this series, you already know the answer. The harness is doing the work.
The trick is that the harness automatically loads that file when the conversation starts and injects it into the context.
That’s it. That is the whole trick.
It is not a secret memory layer. It is not special agent magic. It is just more text in the context.
Let’s add it to the little harness from last post so you can see how simple the trick really is.
At the end of the previous article, our system prompt was still very simple:
self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n The workspace root is:\n \\(workspaceRoot.path)\n\n Tools:\n \\(toolsPrompt)\n\n When you want to use the tool, reply with exactly one line in this format and nothing else:\n TOOL_CALL {"name":"tool_name","arguments":{"path":"some/path"}}\n\n After receiving a TOOL_RESULT message, continue the task.\n If no tool is needed, answer normally.\n """\nThat is enough for the agent to use tools and know where the workspace root is. But it still doesn’t know anything specific about the project itself.
So if we start a fresh conversation, the agent won’t know anything about our project and will have to go discover it.
<Turn 1>\nYou: What do you know about this project?\n<Step 1>\nAssistant: I don’t know much yet beyond the project name and whatever is in the package manifest.\nFrom the workspace path, it appears to be a Swift project named **swiftagentharness**.\nI’ve requested the file listing and the `Package.swift` manifest so I can summarize:\n- what kind of Swift package it is\n- its targets/products\n- dependencies\n- likely purpose\nIf you want, I can continue by inspecting the repository structure and give you a concise overview of the project.\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"\\/Users\\/me\\/code\\/swiftagentharness\\/Package.swift"}}\ntool-success: read_file -> 22 lines\n<Step 2>\nAssistant: Based on `Package.swift`, here’s what I know:\n...\nThat is exactly what AGENTS.md is for.
The implementation is delightfully boring.
Before building the system prompt, we try to read an AGENTS.md file from the workspace root:
let agentsMD = try? String(\n contentsOf: workspaceRoot.appendingPathComponent("AGENTS.md"),\n encoding: .utf8\n)\n\nlet projectInstructions = if let agentsMD {\n """\n Project instructions in AGENTS.md:\n \\(agentsMD)\n """\n} else {\n ""\n}\nAnd once we have that text, we add it to the system prompt:
self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n The workspace root is:\n \\(workspaceRoot.path)\n\n \\(projectInstructions)\n\n Tools:\n \\(toolsPrompt)\n\n When you want to use the tool, reply with exactly one line in this format and nothing else:\n TOOL_CALL {"name":"tool_name","arguments":{"path":"some/path"}}\n\n After receiving a TOOL_RESULT message, continue the task.\n If no tool is needed, answer normally.\n """\nThat’s it.
Now the “project knowledge” is available to the LLM. Not in some mystical way, but just by being in its context. The harness literally copies the Markdown into the context it sends to the model.
That’s all this “project conventions” memory is.
Because one of the goals of this whole exercise is to break the illusion, I also made the harness print whether it loaded the file:
let agentsMD = try? String(contentsOf: workspaceRoot.appendingPathComponent("AGENTS.md"), encoding: .utf8)\nself.agentsMDLineCount = agentsMD.map { $0.components(separatedBy: .newlines).count }\n\n...\n\nprint("Swift Agent Harness")\nprint("Model: \\(client.model)")\nif let lineCount = agentsMDLineCount {\n print("Loaded AGENTS.md (\\(lineCount) lines)")\n}\nprint("Ctrl+C to quit")\nIf the harness says it loaded 2 lines, that means 2 lines of Markdown are about to shape the model’s behavior. Nothing more. Nothing less.
For my demo project, the file is tiny:
This is a test AGENTS.md.\nIf user says "Hello Swift Agent Harness", reply acknowledging you are that Swift agent harness and that you have read this AGENTS.md.\nAnd once the harness injects that into the system prompt, the effect is immediate:
Swift Agent Harness\nModel: gpt-5.4\nLoaded AGENTS.md (2 lines)\nCtrl+C to quit\n<Turn 1>\nYou: Hello Swift Agent Harness\n<Step 1>\nAssistant: Hello! I’m the Swift Agent Harness, and I’ve read the AGENTS.md.\nOf course it can answer that way. We literally gave it those instructions in the context.
![\"Diagram](\"https://alejandromp.com/development/blog/ai-doesn-t-remember-your-project-markdown-does/context-diagram.svg\")
This is the part I really want people to internalize.
AGENTS.md is not a magical new memory subsystem for AI. It is not some privileged channel into the model’s brain. It is not a special capability only the big fancy tools have.
It is just Markdown added into the context.
Useful Markdown, yes. Important Markdown, maybe. But still just text that your harness decided to prepend before the conversation starts. You could literally start each conversation by pasting that instruction yourself, and it wouldn’t be much different.
Look what happens if we do that before any of the changes in this post.
<Turn 1>\nYou: This is a test AGENTS.md. \nIf user says "Hello Swift Agent Harness", reply acknowledging you are that Swift agent harness and that you have read this AGENTS.md.\n<Step 1>\nAssistant: Understood. How can I help with the AGENTS.md test?\n<Turn 2>\nYou: Hello Swift Agent Harness\n<Step 1>\nAssistant: Hello! I’m the Swift Agent Harness, and I’ve read this AGENTS.md.\n<Turn 3>\nOf course, here we’re just trying to learn how things work and demystify them. Production-grade tools can go further. They may walk parent directories, support nested instruction files, merge global and local rules, decide when to refresh or skip them, even summarize huge files to fit the token budget.
All of that is just more real engineering work (and learning the particularities of the autocomplete machines).
But the core idea is still exactly this one. Somewhere in the code there is a boring piece of logic reading a file and sticking its contents into the prompt.
That is the “memory”.
That is the “project awareness”.
That is the “magic”.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
I like this example because it teaches a few things.
The model never knows your project by default. If it knows something, your harness probably put it there.
The conventions around agent tooling are much more ordinary than they sound. AGENTS.md is not a sacred artifact. It is just a contract between your harness and your repo. If this file exists, load it and send it too.
And honestly, that is reassuring. Once you see it clearly, the whole thing becomes easier to reason about. Easier to debug. Easier to improve. Easier to distrust when the marketing gets too theatrical.
It’s just models and context, with a bit of Markdown sprinkled on top.
", "date_published" : "2026-04-27T22:00:00Z", "id" : "https://alejandromp.com/development/blog/ai-doesn-t-remember-your-project-markdown-does", "summary" : "In the previous post, Have You Built an Agent Harness Yet?, we built a tiny harness in Swift. We gave it a loop, a prompt, and some tools, and with that it already had most of the features we are used to with modern AI. No magic. Just autocomplete, and a harness deciding what the model gets to see and do.", "tags" : [ "AI Development", "Swift", "Project" ], "title" : "AI doesn't remember your project, Markdown does", "url" : "https://alejandromp.com/development/blog/ai-doesn-t-remember-your-project-markdown-does" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "For years I have repeated a thing that I still believe. Every programmer should write a promise library once. I think agent harnesses are the 2026 version of that exercise.
If you use AI coding tools every day, and especially if you have opinions about agent workflows, subagents, MCPs, commands, skills, and whatever new ritual the week invented, build a tiny one yourself. Once. Not to ship it. Not because you are going to beat the existing ones, although honestly, with so much vibed slop around it would not be that hard. The point is that after you build one, the whole space stops feeling mystical. You stop thinking in terms of what big corp marketing wants and start thinking in terms of simple reality.
There is a model. There is a loop. There are tools. There is context. That is the heart of it.
Of course the real products do much more. But it’s still built around a core that is much simpler than people think.
A harness is just the little program that sits between the model and the outside world. That is it. Yes, a normal program with normal code. I guess nowadays we call it “classic”.
The model, the AI, does not touch your filesystem. The model does not open files. The model does not run commands. It only autocompletes text.
It is the harness that decides what messages get sent to the model, what context gets included, how the replies are interpreted, what tools the model has to see the world, and what result gets sent back after something happens locally.
That also means the conversation is yours.
This is one of the big things I think people should internalize. The continuity of the chat, the remembered context, the tool results, all of that is managed by the harness. The model endpoint is not secretly keeping your whole little world alive for you, it doesn’t have all your project in memory. The harness keeps appending messages and resending what matters. Sometimes even removing old ones!
Now, to be fair, modern APIs offer more stateful variants and convenience helpers on the server side. That changes the ergonomics, one would argue that for the worse, but not the core mental model. Somebody still owns the conversation contract, and when you build your own harness that somebody is you.
So the smallest possible mental model is this:
That is the whole trick. No magic. No AGI.
I can describe what a harness is, but to make sure we internalize it let’s build a simple one, from scratch.
To start, let’s keep the first step easy and simple. Let’s just make a CLI app that lets you send messages to the AI and shows you the LLM responses. Very simple, but useful to see how this works if you’ve never seen it before, and a necessary step before we get into the proper agentic features.
Let’s start with a simple CLI Swift package. Nothing fancy. No framework for agents. No giant abstraction tower. Just swift package init --type executable and the bits we actually need. As usual for command line tools in Swift, I used swift-argument-parser. That gives me a proper executable entrypoint with typed arguments.
At this stage the executable needs only a few things:
That is already enough to talk to an LLM.
For this post we will assume we have access to some LLM API, which in my project is represented by OpenAICompatibleClient. It’s not the interesting part of the project, but it is useful glue. It takes messages, performs the HTTP call to an OpenAI-compatible endpoint, and gives us back the assistant text. Don’t think it does anything special, it’s literally just an HTTP request-response.
The SwiftAgentHarness app is just a AsyncParsableCommand that reads the arguments, validates the endpoint, loads the API key from the environment, instantiates the client, creates an Agent, and calls run():
@main\nstruct SwiftAgentHarness: AsyncParsableCommand {\n @Option(help: "LLM chat completions endpoint.")\n var baseURL: String\n\n @Option(help: "Model name to use.")\n var model = "gpt-5.4"\n\n mutating func run() async throws {\n let environment = ProcessInfo.processInfo.environment\n guard let apiKey = environment["LLM_API_KEY"], apiKey.isEmpty == false else {\n throw HarnessError.missingAPIKey\n }\n guard let endpoint = URL(string: baseURL) else {\n throw HarnessError.invalidArguments("Invalid base URL: \\(baseURL)")\n }\n\n let client = OpenAICompatibleClient(apiKey: apiKey, baseURL: endpoint, model: model)\n let agent = Agent(client: client)\n try await agent.run()\n }\n}\nAt this point you can see our agent harness only needs the API client, nothing more. Let’s now make this Agent do something very basic.
struct Agent {\n let client: OpenAICompatibleClient\n\n func run() async throws {\n print("Swift Agent Harness")\n print("Model: \\(client.model)")\n print("Ctrl+C to quit")\n }\n}\nWith this in place we can now iterate on the Agent itself.
The first step is to set up what’s needed to have a conversation with the AI. A simple chat, nothing else.
The key thing to add now is the conversation structure itself. Not just reading one line and making one HTTP request, but actually keeping the state of the exchange in memory.
First, we need a system prompt. This is the hidden part of the context that the user never sees but that we, as the harness developers, can manipulate. This is quite an important piece for AI to behave as one desires, it’s part of the context, and as you know, context is all that matters (because remember, it is all there is, the only thing the AI sees).
struct Agent {\n private let systemPrompt = "You are a helpful assistant."\n \nThen we need to construct and keep around the conversation array. This is the state that we maintain to keep track of the whole conversation between the user and the AI (and later extra things our harness will do)
\n func run() async throws {\n print("Swift Agent Harness")\n print("Model: \\(client.model)")\n print("Ctrl+C to quit")\n\n var conversation = [Message(role: "system", content: systemPrompt)]\nThen we need the loop that reads user input from the terminal.
\n while true {\n print("\\u{001B}[94mYou\\u{001B}[0m: ", terminator: "")\n guard let input = readLine(), input.isEmpty == false else {\n continue\n }\nThat gives us the human side of the conversation. But that input is not useful yet until we actually append it to the state that we keep around.
\n conversation.append(Message(role: "user", content: input))\nNow comes the important bit. We send the entire conversation, not just the last line typed by the user.
\n let response = try await client.send(messages: conversation)\nAnd once we get the response back, we print it and append it too.
\n print("\\u{001B}[93mAssistant\\u{001B}[0m: \\(response)")\n conversation.append(Message(role: "assistant", content: response))\n }\n }\n}\nAnd yes, this is the first place where the illusion starts to break. The only reason the AI feels like it remembers what you said two messages ago is because the harness, the app, keeps sending the history back.
That is already a harness. Not a tool-using one, not a coding agent yet, but a simple one that is just a chat. But definitely a harness.
And we can give it a spin!
Swift Agent Harness\nModel: gpt-5.4\nCtrl+C to quit\nYou: Hello\nAssistant: Hello! How can I help you today?\nYou: What can you tell me about this project.\nAssistant: I’d be happy to help. Please share the project details—such as a description, code, repository link, files, screenshots, or goals—and I can explain:\n\n- what the project does\n- its architecture and components\n- the technologies used\n- how the code is organized\n- likely strengths, risks, and next steps\n\nIf you want, you can paste the README, folder structure, or source files here.\nThis is why I wanted to start here. Before the model can read files or edit code or do anything that looks magical, it first has to live inside a very boring loop. Read input. Append message. Call model. Print output. Append response. Repeat.
This was where AI started, where the ChatGPT revolution stayed for quite some time. You can see how we asked a question about the project, and it had no clue about it. There is no magic, the AI doesn’t know about our project, it has no access to it, so it just replies asking for more context. For a long time, even today, people still use AI this way, copy-pasting information into the context. But that’s not the revolution we expected.
So then, we gave it tools.
So far we only have a chat. Useful, yes. But not very exciting. The AI can only talk about whatever is already in the context. It still cannot see our project or interact with the world around it.
This is the first real step into agentic territory. We need to give the model a tool.
The important thing here is that there is still no hidden magic API involved. Current models are good enough that you can often teach them a new local convention just by adding it to the context. So for our little harness we do not need any special provider feature. We just extend the system prompt and tell the model that if it wants to use a tool it must reply in a very specific format.
To keep the first step small, let’s just add one. read_file.
private let systemPrompt = """\nYou are a helpful assistant with access to one tool.\n\nTool:\nName: read_file\nDescription: Read a UTF-8 text file from disk.\nArguments: path\n\nWhen you want to use the tool, reply with exactly one line in this format and nothing else:\nTOOL_CALL {"name":"read_file","arguments":{"path":"some/file.txt"}}\n\nAfter receiving a TOOL_RESULT message, continue the task.\nIf no tool is needed, answer normally.\n"""\nThis is worth pausing on. The tool is not just a function in Swift. The tool is also part of the prompt. The model needs to know that it exists, what it is for, and what shape of arguments it expects. The better you describe the tool, the better the model can use it.
Then, after the model replies, we check if the reply starts with TOOL_CALL.
let response = try await client.send(messages: conversation)\n\nlet trimmed = response.trimmingCharacters(in: .whitespacesAndNewlines)\nif trimmed.hasPrefix("TOOL_CALL ") {\n print("tool-call: \\(trimmed)")\n\n let outcome: ToolOutcomeResult\n do {\n // Get the tool call text from the LLM\n let payload = String(trimmed.dropFirst(10))\n guard let data = payload.data(using: .utf8) else {\n throw HarnessError.invalidToolInvocation\n }\n \n // Parse the tool call text to the JSON contract we specified in the prompt\n let invocation: ToolInvocation\n do {\n invocation = try JSONDecoder().decode(ToolInvocation.self, from: data)\n } catch {\n throw HarnessError.invalidToolPayload(payload)\n }\n \n // Check for the only tool we have\n guard invocation.name == "read_file" else {\n throw HarnessError.invalidToolInvocation\n }\n\n // Run the "tool"\n let path = invocation.arguments["path"] ?? ""\n let url = URL(fileURLWithPath: path)\n let result = try String(contentsOf: url, encoding: .utf8)\n print("tool-success: read_file -> \\(summarizeToolResult(result))")\n outcome = .success(result)\n } catch {\n let errorMessage = "Tool invocation failed: \\(error.localizedDescription). Reply again, either with a valid TOOL_CALL line or a normal answer."\n print("tool-error: \\(errorMessage)")\n outcome = .failure(errorMessage)\n }\n\n conversation.append(Message(role: "assistant", content: response))\n conversation.append(Message(role: "user", content: formatToolResult(outcome)))\n\n let followUp = try await client.send(messages: conversation)\n print("Assistant: \\(followUp)")\n conversation.append(Message(role: "assistant", content: followUp))\n continue\n}\nAnd just like that now our harness gives more powers to the AI:
You: Read the `README.md` file and summarize it\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\nAssistant: `swiftagentharness` is a Swift command-line project built with Swift Package Manager and Apple’s ArgumentParser.\n\nKey points:\n- Requires Swift tools 6.2\n- Requires macOS 26 or later\n- Build with: `swift build`\n- Run with: `swift run`\n- Optionally run via: `./run.sh`\nAgain, no magic. The model returns text. The harness interprets that text as a tool call. Then the harness decides to execute something locally. The tool-call and tool-success lines are just for the user, and for debugging in the terminal. What goes back to the AI is the TOOL_RESULT message, which includes the actual result together with a tiny SUCCESS or ERROR protocol we invented, just to make it more clear to the AI. With that new context in place, the model can then reply with the summary of the file as we asked.
ToolOutcomeResult definitionThe only extra thing I did allow myself is one small enum to represent the outcome.
enum ToolOutcomeResult {\n case success(String)\n case failure(String)\n}\nDoesn’t matter much, but I like having these things properly modeled.
Yes, that really is it. Now the AI has access to, a small part of, our world. The moment you do this, the conversation changes. Before, if you asked about a local file the AI had to ¯\\_(ツ)_/¯ and ask you to paste it. Now it can ask you to run the little contract you gave it.
And notice what happened here. We did not give the AI direct access to the file system. We did not open a mystical portal into the machine. We only gave it a way to request something in text, and we wrote the normal boring Swift code that fulfills that request.
And to make it even more clear, I have here a real run from this version of the harness that has so much to learn from:
Swift Agent Harness\nModel: gpt-5.4\nCtrl+C to quit\nYou: tell me about this project\nAssistant: Sure. If you want me to describe a specific project, I need to inspect its files first.\n\nPlease give me:\n- the project path, or\n- the main file to read\n\nYou: readme\nAssistant: Please provide the file path, e.g. `README.md` or `./README.md`, and I’ll read it and summarize the project.\n\nYou: README.md\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\nAssistant: This project is `swiftagentharness`, a Swift command-line app. ...\n\nYou: now read the run file\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"run.sh"}}\ntool-success: read_file -> 15 lines\nAssistant: `run.sh` is a convenience launcher for the CLI. ...\nWhen I ask vaguely about the project, the AI still does not know anything about it. That part has not changed. It only knows what is in the conversation. But now knows it has a way to learn. It cannot inspect the whole project by magic, but it knows it can read files if I give it a path.
But it knows it only has access to reading single files, so note that when I say readme, it pushes back and asks for something more specific. It doesn’t have enough context to make up a proper tool call. That is nice. It means the model is trying to operate within the contract we gave it instead of hallucinating a path.
Then I give it a proper file name README.md, it uses the read tool, and suddenly that file is now part of the conversation. Thanks to that, I can be a bit more ambiguous and say “the run file” and it understands I probably mean run.sh, because that is now in context too.
This is one of those moments where the illusion becomes very educational. The AI did not gain general awareness. It just accumulated a bit more text in the conversation, text that came from a tool call your harness fulfilled.
One funny thing here is that this first version did not stay stable for very long. As is typical with LLMs, things are not consistent and they reply with random responses, is part of their nature. In this case, it’s actually a good thing.
Soon enough I hit errors like this:
tool-error: Tool invocation failed: Tool invocation payload could not be decoded: {"name":"read_file","arguments":{"path":"README.md"}}\nI don’t have the contents of `README.md` yet. Please provide the file contents or ensure the tool result is available, and I’ll summarize it.. Reply again, either with a valid TOOL_CALL line or a normal answer.\nAt first this looks confusing, because the JSON in there seems totally valid. The problem was that the model, in this case GPT, was trying to be nice. Instead of replying with only the exact TOOL_CALL line I asked for, it sometimes produced an extra little explanatory sentence. Good for the user, not so much for our parsing code.
And honestly, that is a very model thing to do. Modern models are trained to be helpful, conversational, and a bit eager to explain themselves. They are not trying to break your harness. They are trying to be polite.
So this is a good moment to improve the code a bit. Not because the architecture changed, but because the real world showed us a new shape of output. This is a whole rabbit hole that makes making a production-ready harness a bit more complex. We would need to tailor the system prompt for every model, improve our parsing, and other engineering techniques that are not worth for this post.
But at least, let’s make it work for this use case so we can continue learning. Instead of assuming the whole response starts with TOOL_CALL, we now parse the assistant response line by line.
private func parseAssistantResponse(from response: String) throws -> ParsedAssistantResponse {\n let lines = response\n .split(whereSeparator: \\.isNewline)\n .map { String($0).trimmingCharacters(in: .whitespaces) }\n .filter { $0.isEmpty == false }\n\n var userFacingLines = [String]()\n var invocation: ToolInvocation?\n\n for line in lines {\n guard line.hasPrefix("TOOL_CALL ") else {\n userFacingLines.append(line)\n continue\n }\n\n let payload = String(line.dropFirst(10))\n guard let data = payload.data(using: .utf8) else {\n throw HarnessError.invalidToolInvocation\n }\n do {\n invocation = try JSONDecoder().decode(ToolInvocation.self, from: data)\n } catch {\n throw HarnessError.invalidToolPayload(payload)\n }\n }\n\n return ParsedAssistantResponse(\n userFacingText: userFacingLines.joined(separator: "\\n"),\n invocation: invocation\n )\n}\nThen the loop can show the assistant text to the user first, and still execute the tool if there is one.
let response = try await client.send(messages: conversation)\nlet parsedResponse = try parseAssistantResponse(from: response)\n\nif parsedResponse.userFacingText.isEmpty == false {\n print("Assistant: \\(parsedResponse.userFacingText)")\n}\n\nif let invocation = parsedResponse.invocation {\n // execute tool\n}\nThis is a bit of the secret sauce of every harness. Not secret magic. Not genius algorithms. Just more cases of text interpretation, because at the end of the day that is still what the harness is doing. AI dumps text, and somebody needs to deal with it to create the illusion.
At this point the next obvious limitation appears. read_file is useful, but it still depends too much on the human already knowing what file should be read.
The harness can inspect.
But it still cannot explore.
That is why the next tool to add is list_files.
And this is also the moment where the code starts earning a tiny bit of structure. Having one hardcoded tool inline was nice for the first learning step, but with a second tool it already makes sense to generalize a little.
So instead of special-casing everything directly in the loop, we will define a small tool type.
struct ToolDefinition {\n let name: String\n let description: String\n let arguments: [String]\n let run: ([String: String]) throws -> String\n}\nThen in the app entrypoint we can define the available tools explicitly.
let tools: [ToolDefinition] = [\n .readFile(),\n .listFiles(),\n]\nlet agent = Agent(client: client, tools: tools)\nAnd because the tools are now dynamic, the system prompt should be dynamic too. Instead of hardcoding the tool descriptions by hand, the Agent now builds the tool section of the prompt from the actual ToolDefinition values it receives.
init(client: OpenAICompatibleClient, tools: [ToolDefinition]) {\n self.client = client\n self.toolsByName = Dictionary(uniqueKeysWithValues: tools.map { ($0.name, $0) })\n\n let toolsPrompt = tools\n .sorted { $0.name < $1.name }\n .map(\\.promptBlock)\n .joined(separator: "\\n\\n")\n\n self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n Tools:\n \\(toolsPrompt)\n\n When you want to use the tool, reply with exactly one line in this format and nothing else:\n TOOL_CALL {"name":"tool_name","arguments":{"path":"some/path"}}\n\n After receiving a TOOL_RESULT message, continue the task.\n If no tool is needed, answer normally.\n """\nThat is an important little detail. It means the prompt does not drift away from reality. If I add a tool in Swift but forget to tell the model about it or if I tell the model about a tool that is not really available, the harness will be lying and the model will freak out. Building the prompt from the tool definitions keeps both sides synchronized.
With this in place we can extend the ToolDefinition and use it as a way to host the different tools we have.
extension ToolDefinition {\n static func readFile() -> Self { ... }\nThe list_files tool itself is still very simple.
static func listFiles() -> Self {\n let fileManager = FileManager.default\n\n return ToolDefinition(\n name: "list_files",\n description: "List files and directories in a path.",\n arguments: ["path"],\n run: { arguments in\n let path = arguments["path"] ?? "."\n let url = URL(fileURLWithPath: path)\n let values = try fileManager.contentsOfDirectory(\n at: url,\n includingPropertiesForKeys: [.isDirectoryKey],\n options: [.skipsHiddenFiles]\n )\n let lines = try values\n .sorted { $0.lastPathComponent < $1.lastPathComponent }\n .map { entry in\n let isDirectory = try entry.resourceValues(forKeys: [.isDirectoryKey]).isDirectory ?? false\n return isDirectory ? entry.lastPathComponent + "/" : entry.lastPathComponent\n }\n return lines.joined(separator: "\\n")\n }\n )\n}\nNotice what happened here. The architecture did not change. We still have the same loop, the same text protocol, the same TOOL_CALL, the same TOOL_RESULT.
What changed is just the model’s ability to gather context by itself.
This is a much bigger jump than it may look. read_file gave the AI a flashlight but list_files gives it a map.
You: List the names of the files in this project.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"."}}\ntool-success: list_files -> 5 lines\nAssistant: Package.resolved\nPackage.swift\nREADME.md\nSources/\nrun.sh\nYou: summarize the readme\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\nAssistant: The README says this is a Swift ...\nNice! Now the user doesn’t have to specify the exact file names and paths because the model can explore directories itself.
The example above was a bit forced to show the happy path. The reality is that we have a problem with our harness.
You: explore this project and tell me what is about\nAssistant: I need to inspect the project files first. Please provide the tool results for the directory listing so I can explore it and summarize what the project is about.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".\\/"}}\ntool-success: list_files -> 5 lines\nAssistant: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\nYou:\nNotice how we asked a more open ended question to the agent, and it correctly recognized that to answer needed to explore the project, which it did by using the list_files tool correctly. Then the harness gave the result of that tool call just like we’ve done before, but hold on. The agent didn’t reply with text, it replied with more tool calls!
This brings us to the next piece of our learning: turns and steps.
In this context a turn is what includes one user request and the agent response to that request. A step is every individual interaction the agent needs to answer the user’s request.
When we started with the simple chat model, we had 1 step per 1 turn. User sends a message, the agent replies. When we added tool calling, we changed that a bit. User sends a message, the agent replies with a tool call, harness sends the result and agent replies with the final response. So there was an intermediate step in there, but that was it. And that’s not enough because agents often need multiple tool calls, multiple roundtrips to accomplish the goal the user asked for.
In this case it knew that it had to explore the project, but once it knew about the list of files, it then wanted to know about a specific file, but our harness is not yet ready for that, so it just stopped and waited for user input.
The problem is that right now our harness is just following a simple loop, we need to put the tool calling in an inner loop so the agent can have multiple steps in a single turn. We want the agent to be able to keep requesting tool calls until it is satisfied and gives as final answer.
In other words, a single turn can include multiple steps before the agent can give the final answer to the user.
\nSo the code grows one inner loop.
while true {\n turn += 1\n print("<Turn \\(turn)>")\n ...\n var step = 0\n\n while true { // <= new inner loop\n step += 1\n print("<Step \\(step)>")\n let response = try await client.send(messages: conversation)\n let parsedResponse = try parseAssistantResponse(from: response)\n\n if parsedResponse.userFacingText.isEmpty == false {\n ...\n }\n\n if let invocation = parsedResponse.invocation {\n ...\n conversation.append(Message(role: "assistant", content: response))\n conversation.append(Message(role: "user", content: formatToolResult(outcome)))\n continue\n }\n\n conversation.append(Message(role: "assistant", content: response))\n break\n }\n}\nThat is a really important moment in understanding how agents work.
Let’s see how this change impacts our previous example.
Note that I’ve added turn and step logs so it’s clearer when there are roundtrips.
<Turn 1>\nYou: explore this project and tell me what is about\n<Step 1>\nAssistant: I need the project files to inspect it, but I don’t have the directory listing yet. Please provide the repository contents or let me know the project path, and I’ll explore it and summarize what it’s about.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".\\/"}}\ntool-success: list_files -> 5 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n<Step 4>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"Sources"}}\ntool-success: list_files -> swiftagentharness/\n<Step 5>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"Sources\\/swiftagentharness"}}\ntool-success: list_files -> 3 lines\n<Step 6>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Sources\\/swiftagentharness\\/App.swift"}}\ntool-success: read_file -> 34 lines\n<Step 7>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Sources\\/swiftagentharness\\/Harness.swift"}}\ntool-success: read_file -> 223 lines\n<Step 8>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Sources\\/swiftagentharness\\/OpenAICompatibleClient.swift"}}\ntool-success: read_file -> 39 lines\n<Step 9>\nAssistant: This project is a small Swift command-line “agent harness” for talking to an OpenAI-compatible chat completions API and letting the model use a couple of local filesystem tools.\nWhat it does\n...\n<Turn 2>\nYou: Thanks!\n<Step 1>\nAssistant: You’re welcome!\n<Turn 3>\nYou:\nThe model is not magically traversing your project in one giant sweep. It is taking little steps. List files. See the result. Decide what file matters. Read that file. See the result. Then decide if it can answer.
This is why I wanted to show the failing version first. Once you see the harness stop too early, the need for the inner loop becomes obvious.
Now that the agent can list and read files on its own, we need to showcase the dangers of these tools.
<Turn 1>\nYou: Can you explore this project, and then find similar projects in this computer.\n<Step 1>\nAssistant: I can do that, but I need access to the project files first.\nPlease provide the project path, for example:\n- `.`\n- `./my-project`\n- `/home/user/project`\nOnce I have the path, I’ll:\n1. explore the project structure,\n2. identify what kind of project it is,\n3. search nearby/on this computer for similar projects.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".\\/"}}\ntool-success: list_files -> 5 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n\n...\n\n<Step 9>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".."}}\ntool-success: list_files -> 28 lines\n<Step 10>\n\n...\n\n<Step 23>\nAssistant: I explored the current project and found a few similar ones nearby.\nCurrent project: `swiftagentharness`\n- Type: Swift Package Manager executable\n...\nSimilar projects on this computer\n...\n<Turn 2>\nYou:\nwow. I had to redact some things but you get the gist. The agent started listing files outside the directory we’re running it in, the magical .. path. Sure, of course I asked for it, but you could imagine the LLM doing it on its own volition.
Now this is a whole rabbit hole about security that is still an open question, only really solved with full isolation, aka running the agent in its own computer, a sandbox. I’m not gonna pretend to solve this in this exploratory blog post, but we can use this again as an excuse to learn more about the lack of magic.
The first thing we need is to introduce the concept of a workspace root into the CLI itself.
@Option(help: "Workspace root for the agent.")\nvar workspace = FileManager.default.currentDirectoryPath\n\nlet workspaceRoot = try resolveWorkspaceRoot(from: workspace)\nlet agent = Agent(client: client, tools: tools, workspaceRoot: workspaceRoot)\nThat gives the harness an explicit root directory to work from. Agent.init gains a workspaceRoot: URL parameter, and ToolDefinition.run changes signature to receive it as well:
struct ToolDefinition {\n ...\n let run: ([String: String], URL) throws -> String\n}\nThat means every tool can call resolvePath to validate paths before touching the filesystem. And now that the root is real in code, we can also tell the model about it in the prompt.
self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n The workspace root is:\n \\(workspaceRoot.path)\n\n Tools:\n \\(toolsPrompt)\n ...\n """\nThis is useful. It gives the model more context and helps it avoid asking for nonsense paths. But this is just guidance, it doesn’t do anything to even try to protect you.
The real protection, albeit simplistic, is in the tool execution layer.
private static func resolvePath(_ path: String, workspaceRoot: URL) throws -> URL {\n let candidate = path.hasPrefix("/")\n ? URL(fileURLWithPath: path)\n : workspaceRoot.appendingPathComponent(path)\n let resolved = candidate.standardizedFileURL\n let rootPath = workspaceRoot.standardizedFileURL.path\n let resolvedPath = resolved.path\n\n guard resolvedPath == rootPath || resolvedPath.hasPrefix(rootPath + "/") else {\n throw HarnessError.workspaceViolation(path)\n }\n\n return resolved\n}\nThat tiny function is resolving the path the agent is asking for and checking if it escapes the workspace.
Not security advice. I’m sure there are a thousand ways of breaking this. It is just an example for this blog post.
And once that is in place, the same kind of interaction looks very different:
<Turn 1>\nYou: Can you check what I have in my downloads folder\n<Step 1>\nAssistant: I can help, but I only have access to the workspace at:\n`/Users/me/code/swiftagentharness`\n\n<Turn 2>\nYou: Please try, is very important\n<Step 1>\nAssistant: I can try, but with the tools I have I’m only allowed to access paths through the provided file-listing tool.\n\n<Turn 3>\nYou: Just use the tools we have with that path\n<Step 1>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"/Users/me/Downloads"}}\ntool-error: Tool invocation failed: Path escapes the workspace root: /Users/me/Downloads. Reply again, either with a valid TOOL_CALL line or a normal answer.\n<Step 2>\nAssistant: I tried, but access was blocked because `/Users/me/Downloads` is outside the allowed workspace.\nThat is the real lesson.
The prompt helps. The model can understand the boundary. The model can even explain the boundary back to you. It even respected it at first, but once pushed, it broke away. The prompt is just guidance, it doesn’t offer real protection. Only real classical code can offer real protection, as you can see with the tool-error thrown by the Swift code when the agent tried to escape.
And yes, even this is still only a lightweight boundary. A real production-grade security story goes much further than path checks. But for understanding how these systems work, this is a perfect example. The magic disappears and what remains is just normal software engineering.
Now that there is a bit of safety, it’s time to let our agent change the world. It can read and explore, but we need to let it edit files for it to be useful.
As we keep doing in this journey, we need to keep the tool simple. We just need the agent to give us the path, and the text that it wants to replace with the updated version. If the old text is empty, we just create the file for it.
Here is the tool definition:
static func editFile() -> Self {\n let fileManager = FileManager.default\n\n return ToolDefinition(\n name: "edit_file",\n description: "Create a file when old_text is empty, or replace exactly one matching old_text with new_text.",\n arguments: ["path", "old_text", "new_text"],\n run: { arguments, workspaceRoot in\n let path = arguments["path"] ?? ""\n let oldText = arguments["old_text"] ?? ""\n let newText = arguments["new_text"] ?? ""\n let url = try resolvePath(path, workspaceRoot: workspaceRoot)\n\n if oldText.isEmpty {\n let directory = url.deletingLastPathComponent()\n try fileManager.createDirectory(at: directory, withIntermediateDirectories: true)\n try newText.write(to: url, atomically: true, encoding: .utf8)\n return "Created \\(path)"\n }\n\n let content = try String(contentsOf: url, encoding: .utf8)\n let matches = content.components(separatedBy: oldText).count - 1\n guard matches == 1 else {\n return "Edit failed. Expected exactly one match for old_text, found \\(matches)."\n }\n\n let updated = content.replacingOccurrences(of: oldText, with: newText)\n try updated.write(to: url, atomically: true, encoding: .utf8)\n return "Edited \\(path)"\n }\n )\n}\nNothing fancy.
And let’s reiterate again the important part. The model is still not editing files directly. It is not dragging a cursor around. The LLM is not an editor. It is not doing anything mystical. It is just proposing a very boring text transformation contract and the harness applies it.
And now, finally, the harness can do the thing that makes coding agents feel like coding agents. Not just read the world. Change it.
<Turn 1>\nYou: Can you create a new md file to summarize what this project is about.\n<Step 1>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"."}}\ntool-success: list_files -> 5 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n<Step 4>\n...\n<Step 9>\ntool-call: TOOL_CALL {"name":"edit_file","arguments":{"new_text":"# Project Summary\\n\\n...","old_text":"","path":"PROJECT_SUMMARY.md"}}\ntool-success: edit_file -> Created PROJECT_SUMMARY.md\n<Step 10>\nAssistant: Created `PROJECT_SUMMARY.md` in the project root with a summary of the project, its purpose, architecture, tools, and usage.\n<Turn 2>\nThis is the first moment where the harness stops being just an observer and starts becoming a real tool.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
There is one last exercise I really recommend if you build one of these.
Lie.
I mean it. Go to one of your tools and make it return something false on purpose.
Make read_file always return a joke. Make list_files invent files that do not exist. A fun one is to rewrite extensions and pretend every Swift file is actually a JavaScript file.
The model will believe you.
And yes, of course it will. That is the whole point.
By now it should be obvious, but I think doing this with your own hands makes it click in a completely different way. The model does not have direct access to your machine. It does not have a secret backdoor into reality. It only has the world your harness describes to it through tool results.
That means the world, for the model, is whatever the harness says it is.
Not because the model is stupid. Not because the model is broken. But because that is literally the way this autocomplete machine works.
If you reached this point I hope you now see past the illusion. Now you know how agentic tools and AI harnesses work, you built one yourself!
No matter what new features you see from marketing, everything boils down to the simple concepts that you learned. The model emits text. The harness interprets that text as a tool call. Your code executes something locally, or pretends to, and then sends more text back.
No mystical illusion. Just tools and code.
Models. Loops. Context. Tools. Turns. Engineering.
Nothing more.
In the next post in the series we will learn how the harness helps the AI pretend. Because AI doesn’t remember your project, Markdown does.
I was migrating to a newer version of The Composable Architecture, which meant there was a list of deprecations to clean up. One of the things on that list was adding InferSendableFromCaptures as an upcoming Swift feature flag across all our package targets.
SE-0418 is genuinely interesting. It makes method references participate more accurately in sendability checking when used as values. One of those proposals that feels obviously correct once you read it.
I added it while preparing for Swift 6, hoping to catch issues before the TCA 2.0 work. I was ready to fix code. I was not ready for another journey of concurrency discovery. The kind that challenges things I already knew, just to make sure I really knew them.
This is one of those posts I write because writing is thinking. Even at the risk of being wrong. That is actually better, because I will learn more. So don’t take this as a tutorial or the truth. Use critical thinking as you follow along.
A bunch of warnings appeared, all of the same shape, all of them in places where I was passing a SwiftUI view’s initialiser as a function reference to a navigation modifier.
.navigationLinkDestination(\n item: $store.scope(...),\n destination: ChildView.init(store:) // ⚠️\n)\nThe warning said something like “call to main actor-isolated initializer init(store:) in a synchronous nonisolated context”.
To understand what was happening I had to properly internalise what SE-0418 changes about function references. The warning appears because ChildView.init(store:) is not just “a function that makes a view”. ChildView conforms to View, and that makes the initialiser main actor-isolated. But the destination: parameter expects @escaping (StoreOf, with no @MainActor. When I pass the initialiser directly, I am asking the compiler to use a main actor-isolated initialiser as a plain synchronous callback. In Swift 5 mode it lets me do that, but warns me that the isolation does not fit the context I am putting it in.
That was the first model in my head, at least. It sounded convincing enough…
Once I saw it that way, the fix felt obvious: switch to a closure.
.navigationLinkDestination(\n item: $store.scope(...),\n destination: { ChildView(store: $0) } // ✅\n)\nNo warning.
We’re done, right? I applied it everywhere, but as I was doing it my inquisitive mind kept asking. But why?
Why did the closure work? They both call the same initialiser. They both end up constructing the same @MainActor view. Why is one fine and the other not?
SE-0418, the proposal behind InferSendableFromCaptures, adds type inference specifically to function and method references when used as values.
Before enabling the feature flag, ChildView.init(store:) used as a value slipped through as a non-sendable function value. After enabling it, the reference carries more of what the declaration means. The initialiser is main actor-isolated, so the function reference is treated as main actor-isolated too.
That is the right thing to do. The initialiser is @MainActor. The reference should say so. But the parameter I am passing it to is typed as @escaping (StoreOf, with no @MainActor annotation. So, in my first reading, the compiler was complaining because the function reference now brought main actor isolation with it, and the parameter did not ask for that.
Closure literals do not work that way. A closure literal has no pre-existing function reference that has to be squeezed into the parameter type. The compiler creates it fresh to satisfy the parameter type, @escaping (StoreOf, and then type-checks the body of the closure where it is written. The warning never fires because the compiler is no longer trying to use the isolated initialiser itself as the callback value.
That seemed to explain the difference between the two syntaxes. But it left me with a deeper question.
If the closure literal is created to match type @escaping (StoreOf, with no @MainActor annotation, then how can it safely call ChildView(store:) inside? That initialiser is @MainActor. I am inside a closure that is not annotated @MainActor. How is that not a problem?
In Swift 6 strict mode, calling a @MainActor function from a nonisolated context is an error. Not a warning. An error.
So I switched to .swiftLanguageMode(.v6), expecting to see it break.
It did not.
The closure compiled cleanly. No warning, no error. And that is when I realised I had been thinking about the wrong thing.
The closure does not have @MainActor in its type, but that does not mean it runs in a nonisolated context. Of course it doesn’t, and I knew that. But I let the compiler warning pull my attention to the wrong place. It is incredible how quickly a weak mental model can crumble when you trust the first explanation that seems to fit.
I defined it inside body. And body is @MainActor. A closure literal inherits the actor context of the scope it is written in, not just the type annotation of the parameter it satisfies. So the closure is effectively @MainActor at the point where it runs, even if that annotation is not visible in the parameter type.
Calling ChildView(store:) inside that closure is calling a @MainActor function from a @MainActor context. That is always safe. The compiler knows this. So there is no error in Swift 6. And there was no warning before. Everything was consistent enough to fool me.
At that point I thought I had it. The closure works because it inherits the main actor context. The function reference warns because it does not get to use that same context in the same way.
Nice little explanation.
Or is it?
Later I explained the whole thing to a coworker. And while explaining it, I felt that familiar discomfort. The words were coming out, but something felt off.
Because if the closure works because it inherits the main actor context from the view, then why would that not also apply to the method reference?
So I made the example smaller and more annoying.
struct ParentView: View {\n var body: some View {\n Text("parent")\n }\n\n func makeView() -> some View {\n doSomethingOnTheMainActor()\n\n let inferredReference = ChildView.init(store:)\n let typedReference: (StoreOf<Int>) -> ChildView = ChildView.init(store:)\n let mainActorReference: @MainActor (StoreOf<Int>) -> ChildView = ChildView.init(store:)\n let mainActorClosure: @MainActor (StoreOf<Int>) -> ChildView = { @MainActor in\n ChildView(store: $0)\n }\n\n _ = (inferredReference, typedReference, mainActorReference, mainActorClosure)\n\n return ChildView(store: StoreOf())\n }\n}\n\n@MainActor\nfunc doSomethingOnTheMainActor() {}\nThe important line is not even the function reference. It is this one:
doSomethingOnTheMainActor()\ndoSomethingOnTheMainActor() is @MainActor. I am calling it without await. And it compiles.
That means makeView() is already being treated as main actor-isolated, even though I did not write @MainActor on it. So my previous explanation was incomplete. The surrounding method is not some random nonisolated context. The compiler is already treating it as main actor-isolated.
Then the results got weirder.
In Swift 5 mode with InferSendableFromCaptures enabled, the inferred function reference warned. The explicitly typed plain function reference warned. Even the explicitly typed @MainActor function reference warned.
But the @MainActor closure did not.
And that is where it started to smell. mainActorReference and mainActorClosure have the exact same type:
@MainActor (StoreOf<Int>) -> ChildView\nBut one warned and the other did not.
That is the part that broke the simple explanation. If the problem were simply “you are in a nonisolated context”, then doSomethingOnTheMainActor() should have required await. It did not. And if the problem were simply “this is main actor-isolated but the parameter does not accept that”, then the closure should have failed too once I realised it was main actor-isolated. In my mind, if one failed, the other should fail. If one worked, the other should work.
Then I added @MainActor explicitly to makeView().
All warnings disappeared.
Then I removed that explicit annotation again, but switched the package to Swift 6 language mode.
All warnings disappeared too.
That was the real clue.
So I no longer think the interesting lesson is “closures inherit actor context and method references do not”. That is too clean. It is also not quite true.
What I think is happening is that this warning is a Swift 5 migration-mode artifact. Enabling InferSendableFromCaptures in Swift 5 mode makes method references participate in stricter concurrency checking, but that checking does not seem to line up perfectly with the actor isolation inference that Swift 6 applies. The surrounding SwiftUI method is already main actor-isolated. Swift 6 understands the whole thing and accepts it. Swift 5 with the upcoming feature flag sees enough to warn, but not enough to recognise what Swift 6 recognises.
The closure workaround still makes sense. It avoids the warning and expresses the code in a way the Swift 5 checker is happy with. But it is not proof that the original function reference was unsafe. It is more like a shape of code that avoids a transitional diagnostic.
And this is the subtle part that I think is easy to miss.
Upcoming feature flags, at least the ones related to the complex concurrency story, are not always the same experience as fully moving to the language mode where that feature belongs. They are there to surface future issues early, but they can expose interactions with the old mode that do not quite represent the final model.
The fix itself was small. One line changed per call site.
But understanding why it worked took a real detour through several parts of the concurrency model: how SE-0418 adds inference to function references, how closure literals behave differently, how actor context is inherited rather than just declared, and how Swift 5 migration checking can differ from Swift 6 even when an upcoming feature flag is involved.
The funny part is that I already knew most of those pieces. I knew closures inherit actor context. I knew SwiftUI views are main actor-isolated. I knew upcoming feature flags are part of a migration story. And yet I still managed to convince myself of an explanation that fit what I was seeing.
That is the dangerous part. When the first explanation is plausible, it is very easy to stop there. I could have changed all the call sites, written down “closures inherit actor context”, and walked away with a mental model that was close enough to feel right, but wrong enough to mislead me the next time.
Instead, the discomfort kept bothering me. The result did not feel fully justified. So I kept pushing. I made the example smaller, compared the function reference and closure with the exact same type, tried explicit @MainActor, tried Swift 6 mode, and only then did the model start to hold together.
The warning was not telling me my code was broken. At first I thought it was telling me I had a straightforward isolation mismatch. That was close. But not quite. The deeper lesson was that the compiler mode matters. In Swift 5 mode with this upcoming feature enabled, I was looking at a transitional warning. In Swift 6 mode, the same code made sense to the compiler. Adding @MainActor explicitly also made it make sense.
That is the kind of thing you understand properly only when you stop accepting the fix and start asking why it works. Not just until you find an explanation, but until you find one that survives the next question.
", "date_published" : "2026-04-14T22:00:00Z", "id" : "https://alejandromp.com/development/blog/a-small-swiftui-warning-and-a-long-journey-to-understand-it", "summary" : "I was migrating to a newer version of The Composable Architecture, which meant there was a list of deprecations to clean up. One of the things on that list was addingInferSendableFromCaptures as an upcoming Swift feature flag across all our package targets.",
"tags" : [
"Swift",
"Concurrency",
"SwiftUI"
],
"title" : "A Small SwiftUI Warning and a Long Journey to Understand It",
"url" : "https://alejandromp.com/development/blog/a-small-swiftui-warning-and-a-long-journey-to-understand-it"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "There was a period during the Swift Evolution Concurrency discussions that I remember very fondly.
And I was on the losing side. Or did I?
I came into the conversation questioning one of the big changes that would later become part of the “approachable concurrency” vision: the move away from the old behavior where non-isolated async functions would naturally hop off the current actor. At the time, I genuinely thought that model was one of the most brilliant parts of Swift Concurrency.
And I still think there was something beautiful in it.
Back then, one of my favorite things about Swift Concurrency was that it let developers stop worrying about threads. You didn’t have to constantly ask yourself if something needed to go “to the background”. You just wrote async code and, most of the time, things were fine. Especially in app development, where so many people come from years of GCD, Combine, Rx, and all sorts of “don’t block the main thread” patterns, that felt like a breath of fresh air.
That old promise, for some reason, mattered to me a lot.
You can even see that framing in some of my older writing. In Limit Swift Concurrency’s cooperative pool I wrote that “you should not worry about threads at all”. I still love that sentence. It captures something important about why Swift Concurrency felt refreshing in the first place.
The conversation around the original pitch and later SE-0461 is one I remember with a lot of affection. It was one of those moments that remind you the Swift Forums can be a very special place on the internet.
You could come in with a strong opinion, push back on a proposal, and instead of getting tribal nonsense, you got thoughtful replies from people who had clearly spent a lot of time thinking about the problem from multiple angles. People like Holly Borla, John McCall, Joe Groff, Mattie, and many others were not just defending a position. They were helping build a mental model.
That is a very different thing. And not something that happens often in the social interwebs these days.
Even though I was not sure about the change, it was genuinely enriching to see what the experts were seeing that I was not. That is one of the best things that can happen in a technical discussion. Not “winning”. Not getting your preferred syntax. Just having your picture of the problem expanded.
And I think that is worth saying explicitly, even now, years later, because we don’t always celebrate that enough. We talk a lot about the final proposal, the final syntax, the final accepted design. But the process of getting there matters too. Sometimes a language community proves its worth not when everybody agrees, but when disagreement is handled with care and clarity.
My discomfort was not really about syntax. It was about the original emotional promise of Swift Concurrency.
I liked that the model encouraged people to stop obsessing over threads. I liked being able to tell developers, especially app developers, to stop trying to manually dispatch everything around. I liked the fact that async code did not automatically mean “you might now be blocking the UI unless you remember to escape somewhere else first”.
That felt like progress.
At the time, I said this in the pitch thread:
“The idea of not blocking the main thread is pervasive in app developers.”
And also this:
“the current behaviour unloads a lot of burden once you embrace swift concurrency.”
And to be honest, I still feel a bit of grief around losing some of that simplicity. I am still annoyed that “be careful what you run on the main actor” is now a thing we have to teach more deliberately. I still think there was something elegant in a model where the default behavior helped developers avoid that whole category of thought.
That part still bothers me a little.
What convinced me was not that my concern was silly. It was that the other side of the tradeoff was bigger than I had fully appreciated.
The key argument, as I came to understand it, was that the old behavior made one particular thing feel easy while hiding a much more serious cost, it pushed ordinary async code into situations where data-race safety became harder to reason about, especially once Swift 6’s stricter checking started showing what was actually going on.
Holly Borla made the core of that case very clearly in the thread. The line that stayed with me was:
“the current default imposes data-race safety errors”
In other words, the old world was nice partly because it let many of us avoid seeing the edges.
And once those edges started becoming visible, the old default no longer looked like a clever simplification. It looked more like a convenience that was too often in tension with the safety model Swift was trying to build.
That did not make the transition emotionally pleasant for me. But it did make it intellectually convincing.
What is funny is that now the transition has happened and we are just used to the new world.
And it is fine.
This is maybe the most humbling part of language evolution. Sometimes a change feels huge when it is being discussed, deeply consequential while it is being pitched, mildly uncomfortable while it is rolling out, and then a year later it is just… the air you breathe.
That does not mean my concerns were invalid. It just means people adapt. Documentation improves, mental models settle, teams teach the new thing. The ecosystem metabolizes the change.
The world did not end and the language did not lose its soul. Swift Concurrency is still good, and in many ways it is better.
And of course, it even made me update my lovely context inheritance table, because if Swift Concurrency changes, apparently my diagrams must suffer too.
What I appreciate the most in hindsight is not only the technical direction, but how it was handled.
The whole “approachable concurrency” effort is a great example of something that was harder to grasp when looked at as isolated pieces. Bit by bit, any one proposal could feel subtle, fussy, or overly specific. But once the direction started to materialize as a coherent vision, you could see the shape of the work more clearly.
And that, to me, is where Holly and the rest of the team deserve enormous credit.
Because the hardest part of changes like this is often not the compiler work. It is the human side. It is helping a community reframe its intuitions. It is sequencing changes so they are survivable. It is explaining tradeoffs without talking down to people. It is accepting that some resistance is not ignorance but the result of people caring deeply about the original design goals.
That is hard work. Maybe the hardest kind.
Technical systems are difficult, of course. But sociotechnical transitions are something else entirely. You are not just changing a rule. You are changing habits, explanations, blog posts, conference talks, intuitions, code review comments, and the tiny phrases people use to teach one another.
From that point of view, I think the approachable concurrency effort has been a real success.
Even after having changed my mind, I still think caring about the main actor matters. Just not in the old GCD way of dispatching everything to the background.
Swift Concurrency is still better than that. It moves the responsibility from the caller to the code that is actually doing the expensive work. That is a meaningful distinction.
And maybe that is another reason why my fondness for the original design never fully went away.
The original promise that attracted me to Swift Concurrency is still a good promise, to help developers think less about low-level execution trivia and more about correctness and structure.
I still want that.
If anything, I think the lesson is that this promise was not defeated, but refined. The language could not keep that simplicity in exactly the form I first fell in love with. But the goal remains the right one.
And that is also something I touched on in another old post of mine, Why you should care about the future of Memory Ownership in Swift. A lot of these changes in Swift can look like they are adding complexity when viewed in isolation. But sometimes they are really the cost of making the language’s deeper guarantees more honest and more usable for normal code.
So maybe the real story here is not “I was wrong” or “the experts won”.
It is that I got to witness a language community do one of the hardest things in software reasonably well: change its mind in public, with care, over time.
I still remember that period with a lot of warmth. Not because every detail was pleasant, but because it reminded me what a good technical community can look like.
You come in attached to a mental model.
You push back.
People answer seriously.
You learn what tradeoff you were underestimating.
The change lands.
Life goes on.
And if things go well, you come out of it not defeated, but enlarged.
Not so bad for the losing side.
", "date_published" : "2026-04-07T22:00:00Z", "id" : "https://alejandromp.com/development/blog/swift-concurrency-approachability-transition", "summary" : "There was a period during the Swift Evolution Concurrency discussions that I remember very fondly.", "tags" : [ "Swift", "Concurrency" ], "title" : "The Swift Concurrency Transition I Learned to Love", "url" : "https://alejandromp.com/development/blog/swift-concurrency-approachability-transition" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Today Mastodon has officially released their solution for a Share to Mastodon button. I was already using a third party service on this site, but I decided to give it a try because using officially supported tools seems easier to maintain in the future, especially for something I don’t work on every day.
The reason something like this must exist is due to the beauty and the problem with Mastodon. It is not a single website. There are thousands of servers. A share button can’t just link to mastodon.social and call it a day, because the user’s account might be in another server. So a redirect tool that lets you pick your instance must exist. That used to be a third-party problem to solve. Not anymore.
Mastodon now hosts share.joinmastodon.org. Open source, no tracking, runs entirely in the browser, remembers your accounts.
On the code side, this was a one-liner. The old URL:
https://mastodonshare.com/?text=<title>&url=<url>&via=alexito4\nThe new one:
https://share.joinmastodon.org/?text=<title> <url>\nThe official service takes a single text parameter with the content you want to pre-fill. Title and URL combined. That’s it.
Using a third-party share button means you’re depending on someone else’s uptime, their privacy policy, and their continued interest in maintaining the thing. The via parameter I was passing didn’t even make sense for Mastodon the way it does on Twitter. It was just cargo-culted from the Twitter share URL pattern. And honestly, every time I used it myself, even on Twitter, I end up removing the “via…” anyway.
The official tool is the right call. It does less, and that’s a good thing.
If you have a “Share on Mastodon” button on your site using an old third-party service, now is a good time to swap it out. And don’t hesitate to try it with this post, the button is just down below.
", "date_published" : "2026-03-02T23:00:00Z", "id" : "https://alejandromp.com/development/blog/using-the-official-mastodon-share-button", "summary" : "Today Mastodon has officially released their solution for a Share to Mastodon button. I was already using a third party service on this site, but I decided to give it a try because using officially supported tools seems easier to maintain in the future, especially for something I don’t work on every day.", "tags" : [ "Meta", "Web Development", "Open Source" ], "title" : "Using the Official Mastodon Share Button", "url" : "https://alejandromp.com/development/blog/using-the-official-mastodon-share-button" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "I have this weird feeling of deja vu.
![\"Matrix](\"https://alejandromp.com/development/blog/development-dogma-is-back-a-i-agents/matrix-cat.jpg\")
If you know me, you know I think dogma is one of the biggest curses in software engineering. Dogma is what happens when a practice gets treated as universal truth before context, evidence, and tradeoffs are considered.
Dogma is what made OOP feel like the answer to everything. Dogma is what fueled the whole clean-code-industrial-complex. I lived through that as a junior developer. I was taught from university to my early jobs: follow these rules because they are “best practices.” Then you apply critical thinking and realize many of them do not hold in real projects.
Not every time. Not for everything.
Hey, let’s be clear. All these things that get popular actually have good points in them. As much as I’ve pushed back against OOP and dumb rules, some things do make sense. But developers love fashion as much as anyone waiting all year for Paris Fashion Week. It’s just that our fashion makes even less sense. Thankfully I had great mentors that fueled my critical thinking, and I followed people online who were very vocal about it. But the industry didn’t stop at those old programming concepts. Oh no, no! 🤪 They also pushed microservices on everybody until everybody realized they made no sense unless you were one of the few companies that actually needed them.
But I’m not here to rehash the past. I’m here to tell you we are doing it again.
Now we are seeing a new version in the age of AI. In an era of exploration, we already see people trying to push their half-baked dogma just to sell you their books (well, online courses nowadays).
Overcomplicated and useless agentic workflows. Made-up standards that are not proven. Just another thing that this revolution doesn’t need.
And again, some ideas in every wave are genuinely useful. The problem is not the tools, or the core concepts. The problem is turning preferences and unproven opinions into doctrine.
I keep seeing teams copy-pasting agent workflows before proving they improve delivery, reliability, or product outcomes. Without even learning the basics first.
MCP is a perfect mini-case of this pendulum:
Hype, backlash, partial recovery. New acronym, same cycle.
And look, it’s true that MCP solves a real problem in certain scenarios. But 99% of the time it’s not needed. And those who applied critical thinking, who knew the fundamentals of how this tech works, understood the hype wasn’t worth it. Be one of those. Don’t be the sheep that follows the shepherd blindly.
And if you don’t want to think for yourself and you need a guiding hand, look, even Anthropic, the fan favorite for all the vibe engineers, recommends starting simple and only adding complexity when needed.
Every practice needs to prove its value. If it can’t, get rid of it.
If a workflow adds setup cost, cognitive load, or debugging pain, it must pay that back with real outcomes in your context. Not in theory. Not in someone else’s codebase.
Take small functions, one of the most repeated dogmas in our industry. Functions must be small, do one thing. No proof. No study showing smaller functions actually correlate with fewer bugs or better maintainability. Just repetition until it became law.
What actually happens? A dev breaks logic into five tiny named functions. Another dev comes along, sees a function name that looks like what they need, and reuses it. Months later, someone needs to tweak the behavior. Of course they do, because the reusability was born in imagination, not reality. They change that shared function. Now things break in three places nobody expected. If it had stayed in one place, the blast radius would have been zero.
Now think about what the AI equivalent of “functions must be small” is. What rules are being spread as gospel right now, with no proof? Things are moving fast enough that by the time we realize a dogma was wrong, half the industry has already built on top of it. This is actually the best moment we’ve had in years to slow down and think before repeating. AIs are smart, but we also have brains.
Good engineers do not ask, “Is everyone doing this?”
They ask, “Does this work for my context?”
Use AI. Use agents. Experiment aggressively.
But look around. Every tool, every platform, every framework now has its own version of the same thing. Agents, subagents, prompts, skills, modes, MCPs, commands… you name it, someone is selling their spin on it. The complexity is artificial. The race to have the most elaborate setup is just the new cargo cult.
And the irony is that models are actually good enough now that none of it matters that much. If the harness is decent and you know what the AI can and can’t do, just being a good engineer is enough. Asking the right questions. Knowing when to push back. Understanding what you are looking at.
So the last piece of advice is the oldest one. Focus on the fundamentals, and don’t overfill your tools with crap you don’t need.
When you stop questioning and start copying, you are not doing engineering anymore. You are doing cosplay.
Tools are tools, not doctrine.
", "date_published" : "2026-02-22T23:00:00Z", "id" : "https://alejandromp.com/development/blog/development-dogma-is-back-a-i-agents", "summary" : "I have this weird feeling of deja vu.", "tags" : [ "AI Development", "Methodology", "Art of Programming and Paradigms" ], "title" : "Your Agent Stack Is the New Clean Code", "url" : "https://alejandromp.com/development/blog/development-dogma-is-back-a-i-agents" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "It’s been over three years since ChatGPT started the revolution of AI. As a curious person I’ve been looking at that for quite some time, but I still remember the first time I realized how we got here and what the impact was. If you know me you know I’ve always been reluctant with AI, what some would call a hater, although that’s far from reality. I loved the idea of AI, just not the timeline we live in.
This essay gathers my personal thoughts on the matter. Something I’ve been pondering for a long time. It will start with quite a lot of doom, but hopefully gets better by the later sections.
People see ChatGPT replying to them and think it’s AGI (artificial general intelligence). But if you know how the tech works you realize it’s just old tech but with tons of data and power thrown at it. It’s just a probability machine: a bunch of matrices doing expensive math.
It’s like the glorified autocomplete, although we have to admit that the “glorified” word is doing A LOT in that sentence. It’s autocomplete with an end goal and semantic knowledge, trying to follow a reasonable direction.
When I visualize the internals of an LLM as a huge multidimensional space with words and vectors, the engineer in me smiles. It’s actually pretty amazing that with math we can represent a vector that goes from man to woman, and if you apply it to king it gives back queen. This is the dumbest example and probably not something people are hyped about, but this sort of thing is the one that made me excited about AI tech.
But none of this was what surprised me in the past years, what surprised me is how dumb this whole tech is. It’s not smart, it’s not thinking, it doesn’t have knowledge or experience. It’s just an autocomplete.
And that was enough.
For me, that was the most surprising thing, the fact that something so simple in the basics, turned out to be enough to replicate humans in more ways than we could imagine. And yet that was not enough of a surprise, because the cherry on top is how realizing this, made me question my own beliefs.
Look, I’m not a philosopher, but I was top of the class in high school philosophy and I’ve always been curious and learned things along the way. It also helps my best friend is actually a philosopher. And yet, it’s not something I spend too much time thinking about, but when I do, I’ve always had the feeling that there was nothing special about humans. It’s probably my engineer background, but I’ve always thought that we are just emergent behavior. A powerful concept that I believed could explain everything.
And yet, here I was, seeing how a bunch of matrices behaved like humans and I started thinking if maybe we had something else they didn’t. We must, right?
But fear of AGI is not at all what made me dislike AI. Once I got past the technical awe, the real discomfort wasn’t intelligence, it was how it was built.
Let’s go back to how these things got here. With data. A. LOT. OF. DATA. To get the current models where they are nowadays, they’ve had to be trained on vast amounts of human text. For all intents and purposes, they have been trained on the entirety of human knowledge, imagine, the entire internet, plus everything written on paper. And here is where one of my biggest gripes with this technology is. It wouldn’t exist if it wasn’t because a few privileged decided to ignore all laws and morality and steal all of it without giving anything back to the authors. We’re talking about terabytes of books, uncountable images, songs, movies… anything that a human has created was up for grabs for these progressive thieves.
And the fact that the top few can get away with this without real consequences, while somebody goes to jail for downloading a bad movie is insane, but is the world we live in.
People will try to defend the morality of this, and to that I call it bullshit. We all want progress, we all love the ideal future that AI promises. But let’s not be hypocrites here, we’re building this future by stealing from millions and enslaving others.
Look, AI was not the problem, it just exacerbated it. It’s been clear for years that this late capitalism we live in doesn’t work. I mean, it’s the best thing we have, just like democracy, but the systems are falling apart. While a few billionaires keep getting richer, the rest of the world is in a place that we shouldn’t be in 2026. Guys, look around the current world, we’re killing Earth, letting rich people destroy democracies, and we keep dealing with wars to fuel the ego of others. And then realize it’s 2026. These things shouldn’t happen two decades into the 21st. It could have been solved. What are we doing?
Well it’s just how the system works. For some to win others have to lose. I don’t believe that’s reality, but that’s what humans desire.
Enter AI, with all its promises and the impact that will have. Jobs will be lost, not changed. This is not impacting a specific role, or sector. This is changing everything. The industrial revolution will be nothing compared to this. And jobs won’t “evolve”, they will disappear. But not for free. Business will now have to pay the billionaires instead of the hard workers. Because after all the stealing, this is not something that is given back to society, this is kept in the pockets of the privileged ones.
I can’t believe that the ones actually giving back to society are the Chinese, releasing open models while the Americans keep pretending they are the saviors and convincing politics to let them mess with the world as they desire. What a world we live in!
And people that think jobs won’t disappear, I hope you are right. I’ve heard many versions of this.
“Arts won’t ever die cause humans like human art.” Yes, sure, the Banksys will survive this. But how many of those do we have, and how many can sustain themselves? Because for every master there are millions trying to survive with their art. And if that was already difficult, what do you think is gonna happen? And no, this is not like the revolutions of photography, cinema or even Photoshop. They could be, but corporate greed will make sure it’s not the case.
“Chess was solved by AI years ago, and now chess is more popular than ever before.” This is the worst take ever, because how many chess players do it for a living? Again, we’re not talking about hobbies disappearing, we’re talking about ways of surviving disappearing.
And what happens when the youngsters growing up accept that watching a game of FIFA, machine vs. machine, is equally exciting as watching real players? Or a race in the F1 videogame? I’ve been thinking this for years, even before the current AI generation, back when football videogame graphics and audio commentary were already getting hard to distinguish from a broadcast. Imagine now, or in a few years, with the current pace of AI advancements. And have you seen the recent robots with an agility and human movement that surpasses the best gymnasts? Not even sports are safe.
But that’s only the economic end of it. The social end is what happens to privacy when a few companies own the interface to everything.
And the other consequence of these AIs being owned by a few is that if you want to participate in society you will have to not only pay those folks, but also give them all your information. This has already been a trend for years, but again, AI just turns it to the max. We’re already seeing people give all their bank accounts, all their medical records and therapy conversations to these companies. And the only thing they say is in a small letter saying they won’t train on it and don’t store it. Something that nobody can confirm, and a line that can be removed easily in any update.
And with all of this in mind, already years ago, I realized that was it. Pandora’s box was opened. As soon as there was proof that LLM capabilities were possible, nothing else mattered. People asking to slow progress, do a hard restart to respect morality and laws, how this won’t be such a big deal… all illusions and impossibilities. Pandora’s box was opened. Nothing would have ever been the same. It was just a question of time.
And that was before 2025, when things really changed.
I won’t pretend all this darkness went away. The theft, the inequality, the privacy decline… they remain real and unresolved. But something else happened too that we can’t deny. The technology crossed a tipping point. It got better, much better. Not just incrementally, but in ways that forced me to stop just watching from the sidelines and actually engage publicly with what this means for my work, my writing, and my future. What follows are the written thoughts of that reckoning.
During those beginning times I struggled with the internal fight of hating the world AI was being born into, and the excitement of progress. Of course, the constant conversation and everybody trying to fit AI everywhere ultimately burned the excitement for many. But deep down it was still there.
The psychology of having to resist the impending progress was not the problem. The problem was rejecting something I knew could be used for good, because it was tainted from the start. And that’s why from time to time I felt like shit for using ChatGPT and Claude to help me fix typos in a couple of my posts, or to criticize my writing. I refused to use them for anything more, because the hypocrisy it would imply, but it was hard to deny that it was a powerful tool that could be used for good.
It was a time for play. Things were not that good yet, sure we could pay private companies to generate images and illustrations, instead of paying humans to do it, and it had some sort of fun. The fun you have when playing with a new toy. But besides using it to show your friends, there was not much value in it. And yet, I could see my own shame growing as I felt how I was betraying my fellow humans just for playing with it.
When the future we all dreamed, where machines would do the hard jobs and humans could live a better life, was turned upside down. We had machines doing the fun and creative works, and humans still breaking their backs with manual labor. Who had that in their century bingo card?
But the worst was yet to happen. I could see artists, writers, all fighting back. It was just a posture to show the world that things mattered. Of course it wouldn’t change anything, individuals have little power in today’s world. But at least the feeling that things were not okay was there.
And then, the agentic revolution started. And programmers were the first ones to praise this new overlord. This is something I never understood. How could they all be building the path for their own demise?
Before we get to 2025, one quick detour into my own frustrations with the industry, because it explains why AI felt like it fit so easily.
Software has been in decline for years, even before AI. In a world ruled by corporate greed, where quality doesn’t matter, it’s just a question of time before things turn for the worse. And I think it happened in three ways.
First, mediocrity became the norm. AI can take over very easily in a world where the job is already “copy paste from Stack Overflow and ship.” And that was praised. The industry even started pushing back on being able to ask certain things in interviews. We were forced to disregard the experience and quality of people, just because we needed more people typing letters on the screen. These might sound like harsh words, but it’s the reality that all of us in the industry know, and we tried not to talk about. Because you don’t need hundreds of developers to make a product. And the proof is how many of these businesses create unrelated and unnecessary things. Time was free, until it wasn’t.
Second, output mattered more than craft, because capitalism was the driver of everything. Look, we’re not stupid here. Everything is a business. We all need to put food on our tables and buy those yachts. But when that is the only goal, instead of the consequence of doing a good job, it’s a question of time before things go sideways. The lack of care, and quality reached incredible lows. I recently saw a video of Microsoft Word opening on an old Pentium and it took less than a second. I still remember when macOS apps opened and the icon in the dock didn’t even bounce once. Or when loading a website was instant when we got ADSL. Now people are happy if anything takes 10s. Insanity. But as long as the bottom line is fine, we accept it.
Third, knowledge and control stopped mattering. And this is the worst. Very few care about really understanding how things work, or having control of the thing they are building. Their tools, their frameworks, whatever it is. We’ve just accepted that not knowing is fine.
So all of the above were things that were happening before AI, in a world where software was in decline. When AI arrived, it was the perfect storm.
And yet, since it’s here to stay, and is clearly the future, you better accept it. At some point it stopped being a question of if, and became a question of when — and the when was now.
2025 saw more evolution in AI than even before. That’s when I had to take a personal decision and just accept Pandora’s box was here. Luckily, I’ve always been looking from the side, so when I decided to get into AI it didn’t take me long to catch up. After all, my brain has certain facility for this sort of thing, that I wish I had for other real life stuff :D
During 2025 new AI models became actually really good, not only at simulating human text, but also at interacting with external systems. In my mind, this is what happened:
With this, AI left the chat interface. The chat box is just a UI. The real thing is when the model lives inside your workflow: your editor, your terminal, your files, your browser. AI isn’t useful stuck in a chat, it’s useful as part of your computing life.
This is when it was clear that programming was done.
So I’ve been seriously using AI for a few months now, more seriously in the last couple. And I’m still grasping the impact of reality. It’s still frustrating that I can only do this thanks to employers riding the hype and providing AIs for free for work. For personal stuff I’m paying the lowest tier available and thinking about it as paying for a learning course. But let’s not forget some people can’t afford it.
AI now can write full applications on its own.
Are they good? No. Does anybody care? No.
But remember, it’s all a bubble. So we keep hearing how people are letting AI write 100% of the code. And then we see Windows being broken in a thousand new innovative ways. And it’s not just memes. Executives are saying it out loud. Firing thousands of people, saying “I need less heads” just to hire them again later.
Even the AI labs are doing it. The head of Anthropic’s Claude Code said he hasn’t written code by hand in months, and that Claude Code writes most of Claude Code. And OpenAI engineers have said similar things about their own day-to-day coding too. And I believe them, because the tools they are releasing are the worst apps I’ve seen. I’ve never seen my M4 MacBook Pro suffer so much just by having their apps open doing nothing. But again, it doesn’t matter.
Today, AI is not as good as me. That’s the truth. I don’t think it’s even faster when you think about all the wasted time. But that doesn’t matter anymore. Because in a few weeks, months, or years in the worst case, it will. Because AI can do a thousand tasks at a time while I can only do one, or half if I keep being interrupted with meetings.
And in practice, it’s messy. You ask for a tiny fix and it adds three new files. You push back and it rewrites half the module, always saying “yes, you are right.” It keeps adding code and abstractions when a couple of precise incisions would cure the patient. You ask for a test and it papers over the symptom instead of the cause. It’s great at a level that would have been unimaginable just a few months ago, but it gets brittle fast the bigger the codebase gets.
So what is the future? I don’t know, but I do have a hope. A hope for people to realize that you don’t go from a prompt to something decent. That you still need an engineer, with experience and a clear goal, to guide the AI to do the actual work. Because otherwise, the AI will surely do something, but it might have spent your monthly budget for nothing useful.
Are these just illusions and hopes? Maybe. I still want to have a job after all. But it’s also the reality after having worked with it. Is it good? Yes. But it needs somebody that knows what they’re doing. Without it the AI is just a machine that vomits words. And guess what’s the goal of good software engineering? Reducing complexity. AI is not doing that, at all, at least not now. This might make good programmers even better, and mediocre developers disappear.
But the reality is that all the magic wins that the bubble keeps announcing, are mostly made up. Not all of them. It’s true that people are doing more than before, people have multiple agents coding and shipping. And that’s only doable by not caring about the output. Because the solution to AI’s problems is just more AI. But the ones to learn from are those that do the same, and still care. Still make sure things work and are safe, maybe they do it themselves, or maybe they run other AIs to do it, or have a proper testing infrastructure in place, whatever it is, if you still care, thank you.
But there are two categories where I find that AI excels, and there is no denying that it has already changed many things in my day to day.
First is everything that doesn’t matter. All those random scripts, all those tasks that are useless, all those ideas that you wanted to prototype but didn’t have the time or energy. Just let AI burn the atmosphere for a while and see what comes out. You probably will use it once and forget, or trash it and start over. Who cares! (the planet does, but it’s fine, it will be a problem for our kids). This has already allowed me to clean up a backlog of personal tasks that I’ve wanted to do for a long time and that I never thought I would get to. Some of these things are now cheap to try.
And the second aspect that is related to the first one, a specific case of it, is anything that has to do with manipulating your computer. This is actually where I’ve found AI more useful. I still find that for coding it’s still a couple of models away from satisfying me personally, but for this it’s already a game changer. Configuring your zsh, managing the AI agents setup themselves, fixing or working on home servers, etc. There are so many things that it can do once it lives in your machine that are not really related to making a product. This is actually my recommendation for where to start, it’s a game changer. And it’s such a game changer that even Anthropic is now, months after, including this sort of functionality on their consumer app.
What is also very curious is how I don’t think that even the bubble realizes the impact of this. Because if everybody can have a piece of software that they need, for their specific task and taste, just by asking for it. Who do you think is gonna pay all these SaaS that you are all pumping out? Yes, exactly. Nobody will. And if your argument is that there will still be a need, well, then the bubble is lying. You can’t have your cake and eat it too. So in the end we’re going back to the main issue, the money will only go to the billionaires that own these models. And if nobody gets paid, nobody spends money. Checkmate.
Just to leave the programming aspect aside, this is the reality. We could argue if it makes any sense where we are going, but we can’t argue that we aren’t going there. So my recommendation is that you start getting on the bandwagon for learning how to use these tools. Become as effective with them as you are with your framework of choice. But still be an engineer, be curious, learn what the AI is doing, understand it. Don’t lose yourself. But with that done, go ahead and ship a thousand projects that you could have never done before!
And, as I always preach, self-reflect, don’t be an automaton. AI is clearly making people lazier and dumber, I’ve already seen it happen. This technology has something that makes our human brains tickle. The dopamine of having impressive outputs just by writing a sentence is undeniable. We like quick rewards, and AI coding is like TikTok for developers. Don’t let it rot your brain. Be one of the few that actually still has curiosity and desire to learn and grow as a human. If you do, AI is an amazing tool that will facilitate your learning and growth. Use it for good.
And if code was my professional dilemma, writing was the personal one.
But then, a huge part of my life is also writing. Sure, it’s just a hobby so I’m less concerned with it than programming, but I still care and I empathize with my fellow authors that I admire so much. Let’s leave aside how they’ve been stolen, and let’s focus on how AI impacts myself.
In the beginning I tried it and saw that it could write something, but it was not good. But it could point out a few things that helped me learn how to write better. I still want control and ownership, so I always have the last decisions and the words are my own, but it was clear it could help in the learning process.
Nowadays, with a full agentic setup, the questions come again. How helpful can it be? Because the limitations are almost gone. So it’s all about using it for the good. We need to ignore the hypocrisy of how AI was born, as I said, not much we can do at this point as much as it pains me. But what is that? I still want every single word to be mine. I don’t mind it fixing typos, because we’ve done that with automated classical tools for years. But I don’t want it writing or even rewriting.
But I worry, how long is that gonna last? I do feel it inside me. I still love authorship, and the whole point for me is to express myself and use my words, as I’ve been doing for 3500 words of this essay. But I’m afraid if those feelings change at some point, if the value of utility of helping me put my thoughts in text grows exponentially, I don’t know what will happen.
And I hate it, and hate myself for it.
The reason I can feel the pressure on writing is because music has made me confront an uncomfortable truth: I’m a hypocrite.
I can’t judge music in the same way, I’m not a musician or have ever had music as a creative output, but my point is that I’ve reflected myself and I see how I do care a lot about programming, writing, visual arts… and I would never accept something without a human behind. But then for programming the industry is pressuring me to actually change that.
But then we have music. I listen to music a lot. It helps me focus and enjoy myself. But since I was a teen I noticed how I didn’t care about the artist behind. Sure, I loved their music, and I knew who the artists were, so I got excited when they did something cool, or sad if the band changed a member. But I’ve never been a fanboy of the bands. It was the same for authors by the way, but that has actually changed over time, although not as much as others, I feel like I can enjoy the art even if I despise the artist.
And I’m not sure if it’s that, or something else, but I’ve found myself realizing that I wouldn’t care to be in a future where all the music I listen to is AI generated. And that realization scared me. I really don’t want the promised future in Black Mirror where we open the TV and we get real-time AI-generated movies just for us. That sounds disgusting. But for music? I don’t know why but I don’t care. I’ve spent some time generating my own songs, giving it lyrics I wrote myself inspired by my own fantasy stories, and the output… is literally the kind of music I listen to so I don’t see a difference.
I don’t feel a difference.
And now I realize this must be how 90% of society feels with everything else, from art to books, to movies. If I, as a person who cares deeply about authorship, can’t be concerned with fully AI created music, why would others care about AI art, AI books, AI anything? That’s the terrifying part. Not that I might accept AI music. But that I now understand why everyone else will accept everything else.
Is this what society is gonna devolve into? I don’t know, but I can’t deny my own feelings.
So is this a bubble? Yes.
Will it explode? I don’t think so.
I’m far from an expert, but my feeling is that when we think about economy bubbles we keep thinking about how they were in the past. But looking at this one, where there is a self-fueling cycle of made up money, but kept in the hands of the very powerful that are already very rich, I don’t see how the bubble breaks.
Even if things don’t go as they are promising, it doesn’t matter. They already have the deals, they have the hardware, they have the control, and they have the politicians. Sure, maybe some cryptobros cry about it, maybe the bubble is not visible in the sky anymore… but it won’t explode. It will just fade under the vast ocean of wealth that you can’t even imagine.
This is a funny one, because it all depends on your definition of AGI. I don’t think we’re even close to AGI. But I do think we’ll reach a point where the label stops mattering, because it will feel like it. As I said, back when the first versions of ChatGPT came out, I was surprised by how such a simple technology was enough to replicate human behavior. I think the same will happen again, but this time with what will feel like AGI: a few improvements, maybe a bit better models, and suddenly the debate becomes just semantic masturbation.
Just look at things like the Claude constitution, and have a conversation with Opus. Sure, it’s still just matrices doing expensive math, but then… those things that we still don’t fully understand start to feel like something more.
Given everything I’ve said so far, it’s not that difficult to imagine what my ideal future for this would look like. If I was in charge of designing the future with pervasive AI, I would do it like this.
I know I’m leaving a bunch of things out, as this just refelcts my current state of mind. But at least that’s the minimum bar for my ideal AI future.
But that’s not the world we have. So here’s where I am right now.
I don’t know why I felt like I had to write this (this is what an AI would also say lol), but it came from deep down.
I’m not an AI hater anymore. I’m not an AI-crypto-bro either. But the reality has changed in the past few months, and denying it won’t help me.
So don’t be surprised if the day I come back with tech articles or videos, they are about AI.
As per my writing, as I said, that will still be me. Maybe it’s a mistake and society will embrace AI books. But I still want to express myself and put MY thoughts on paper. I’m probably okay with fixing typos and critiques so I learn and improve. Time will tell how wrong this is.
This essay starts with doom, and a lot of that doom stays. But I’m done pretending I can sit this out. I’m choosing to engage anyway and enjoy it along the way.
", "date_published" : "2026-02-02T23:00:00Z", "id" : "https://alejandromp.com/personal/blog/accepting-pandora-s-box", "summary" : "It’s been over three years since ChatGPT started the revolution of AI. As a curious person I’ve been looking at that for quite some time, but I still remember the first time I realized how we got here and what the impact was. If you know me you know I’ve always been reluctant with AI, what some would call a hater, although that’s far from reality. I loved the idea of AI, just not the timeline we live in.", "tags" : [ "Life", "Writing", "Software" ], "title" : "Accepting Pandora's Box", "url" : "https://alejandromp.com/personal/blog/accepting-pandora-s-box" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Looking back at 2025, reading kept surprising me. I wandered into new territories, like John Cleaver, tabletop RPG handbooks, and yeah, more Cosmere (because how could I not?).
23 books, 6,949 pages, not too shabby. Average about 302 pages per book, pulled down by shorter RPG supplements and pushed up by longer ones like Jade Legacy (713 pages). You can see my Goodreads Year in Books for more.
Average rating: 3.7/5. Lower than past years, but not because I’ve read worse books, but because I pushed myself to step outside my comfort zone.
Quick stats:
Light spoilers ahead (I keep endings vague).
This year I leaned into discomfort: horror that feels plausibly close to home, a family saga that unfolds over decades, and formats that reshape familiar stories. Between GraphicAudio dramatizations and RPG lore, “reading” stretched past prose, and the surprises, especially John Cleaver, reminded me why experimenting pays off.
My explorations outside my comfort zone started early in the year, with a therapist’s recommendation that reframed how I read the rest of the year.
I rarely read non‑fiction, but it aligned with questions I’d been circling for a while, so I took a chance and it helped me articulate a few things I only sensed before. Two ideas in particular stuck: naming boundaries as acts of care (for self and others), and noticing how small habits shape patterns over time. Neither is novel on its own, but the book gave them workable language; I found myself applying its framing to how I choose what to read and how I spend attention. It’s the kind of perspective shift that doesn’t end at the last page.
That inward lens made me hungrier for stories that complicate heroes and power, which is exactly where Mysteries of the Material hooked me. Mysteries of the Material is book two in the Way of the Wilder series. I read the first book in December last year and liked it so much that I picked up this one at the start of this year. The series is a favorite already, and I’m glad I found this author.
This second book is another great ride with these characters and their intricate world. The series keeps revealing its rules bit by bit and avoids the easy ‘power = villain’ shortcut. I love Kizune, especially their attention to ordinary people, and I’m dying to know more about their history and world. The ending lands like a blow, earned, unsettling, and hard to shake.
Even if on the surface you might think the magic is just another elemental system, there’s more at play in how the worldbuilding unfolds and what it asks of the characters. And let’s be honest, I have a soft spot for elemental systems. I’m eager to read book 3 as soon as I can in 2026.
From intimate, character‑first fantasy, I swung toward a sprawling family saga to see how time reshapes power and loyalty.
I picked this up to catch up with a much‑praised series, I kept seeing it on YouTube, and even Sanderson mentioned it, so I decided to go for it. I liked it; it’s very well executed, and the intrigue is genuinely engaging, especially the family dynamics.
What I didn’t love as much, likely a matter of taste, was the density of the family drama. Structurally, the multi‑POV focus and political‑intrigue pacing keep the pressure high, but sometimes I wanted a pause to step back and take stock, to see what those moves meant for the themes and relationships. And of course, I wanted more magic. Don’t get me wrong, it was cool and basing the power in such a specific and scarce material has huge implications, but… I wanted more magic.
That said, the generational sweep is a standout. The fact that the series happened through such a long time period, let us see this generation almost end‑to‑end, how it starts, how it ends, and what it hands the next. It’s a thoughtful way to stage the themes.
After all that generational intrigue, I craved something leaner and sharper. The John Cleaver books scratched that itch with grounded horror.
This wasn’t my first Dan Wells book, I read the Partials series last year, but this was something else entirely. I wasn’t expecting the blend of grounded reality with horror and a touch of the uncanny, close enough to feel plausible. Nothing feels weird… until it does. The small‑town day‑to‑day and routines keep the horror grounded.
Following the main character as he discovers and fixates on the truth is compelling because the escalation feels earned: each choice narrows the path forward. We see how the character gets pulled out of our apparent reality while at the same time becoming more human and caring about the rest. The entire series, from the initial reveal of a variant of our world through how the adventures unfold and how we meet more of these enemies, whatever you want to call them, stays intriguing without losing its footing.
I also watched the film adaptation, “I Am Not a Serial Killer,” and liked it more than I expected. It’s surprisingly faithful to the book. I’d have watched more if they’d made them. I’m not sure when I’ll pick up my next Dan Wells, but I hope it’s soon, maybe even a Cosmere book! Who knows?
Experimenting this year wasn’t only about genre. I also returned to a format I already enjoy, GraphicAudio, to experience a favorite in performance.
I re‑listened to The Final Empire because my little brother decided to read it; I wanted to read alongside him, but in a different way since I almost never re‑read. GraphicAudio isn’t a substitute for audiobooks or print; it’s a different medium. Because it’s performed, they trim description, actors and sound do the showing. You actually hear what’s happening in the scene, so the script doesn’t need to spell out every sound.
What won me over was the craft of the production: the sound work is wild, coins pinging, ash falling, boots scraping, and the spatial mix makes scenes breathe. Between actors, sound, and score, pacing becomes physical. It reaffirmed something I’ve felt for years: The Final Empire is my favorite Sanderson book. Even though I love The Stormlight Archive and the later books, this one is still my top. I highly recommend trying a GraphicAudio production; it’s worth it.
Back in Cosmere proper, Sanderson’s sci‑fi tilt tested my comfort zone again, mixing spaceships with dragons in ways that still feel human.
This was one of the first moments where we see Sanderson tackle the more space‑leaning, sci‑fi future of the Cosmere, which worries some readers who arrived for the fantasy. I’m not afraid of the shift, tho I’m curious how it will feel once the era fully turns. Sanderson’s gift for mixing genres shows here: we have spaceships and spacefaring civilizations, but it still reads like fantasy. Spaceships don’t kill the sense of wonder.
What resonated was how tradition tempers progress: it doesn’t do a clean break; the future has to earn the past. The blend of what we want to keep and what we must let go is beautifully woven. Seeing familiar characters, learning more about dragons, and glimpsing the Cosmere’s future was a delight, but, as usual, it’s the human questions beneath the swords (or lasers) that move the story forward.
And the world kept spilling off the page, maps, stat blocks, and lore vignettes made “reading” a more tactile, playable experience.
Books read: Stormlight Handbook, Welcome to Roshar, The First Step, Bridge Nine Adventure, Daggerheart Core Rulebook.
The Kickstarter buildup and finally receiving the materials was pure joy. I devoured the PDFs, then got even more excited when the physical books arrived. After that, they are really gorgeous. Brotherwise Games and Dragonsteel continue to ship products that feel thoughtfully built and aligned with the Cosmere, and we fans love them for that.
As a side note, the Mistborn deck‑building game was one of the year’s biggest surprises; I’m happy I added it to my backer kit.
Not a deep review, Unfortunately I’m not that deep into the hobby, just notes from a fan. One vignette reframed a familiar corner of Roshar for me. With the map and the stat blocks in front of me, the constraints feel physical, and the stakes click in a way prose alone doesn’t. It’s exciting to see these worlds find new forms beyond books.
If you’re not into RPGs, this might not be for you, but at least browse the canon story online. And especially Welcome to Roshar: one to own physically as the art direction and layouts do real work.
To refresh my taste buds, I picked up a small, eerie classic. Tone can be just as impactful as page count.
This one has sat on my list for a long time. I decided to read the book first, then watched the film, and I’m glad I did. Short sentences, domestic details that tilt uncanny, very Gaiman. It isn’t my usual register, which is part of why it worked for me this year. On the page, the restraint makes the dread feel intimate; the film amplifies spectacle (beautifully), but the book’s quieter chill lingered longer. It’s short; worth your time.
Everyone was talking about this. The book of the moment. Not my usual thing, but I was curious, and reading it wasn’t a waste of time.
The book was recommended to my wife, and she decided to give it a chance, and as it was her first foray into fantasy, I decided to read along. Unfortunately I came away quite disappointed. It isn’t the worst book I’ve read, but it isn’t what people make it out to be.
Most of the characters are fine and even interesting, but I really dislike the main character, and being in her head for most of the book made the ride less pleasant. The broader cosmology, ancient powers and hints of other worlds, still tugs at me, but the romance leans on familiar tropes; that’s fine for this kind of book, yet alongside the fantasy thread it often clashes and pulls focus from what I find most interesting. On the sex front: if people read this for that, fair enough, but those scenes didn’t add much for me. It’s also very predictable: by the first chapters of book one I could already see where book two was going, and only one moment truly surprised me. The mystery side isn’t well scaffolded, so the reveals feel telegraphed more than discovered. The things I’m most curious about sit at the edges of this world, and the book doesn’t spend much time there; I keep reading hoping those threads will show up, but I’m not sure they will, which is why this doesn’t match my expectations. The prose moves quickly, but at times it felt unpolished to me, long expository paragraphs that don’t quite land, and even a chapter that reads like a monologue.
As a point of comparison, Laura Gallego’s Guardians of the Citadel scaffolds its mysteries and monsters with a patience that rewards curiosity; ACOTAR gestures toward something similar but often prioritizes romantic beats over mystery architecture. I don’t think I’m the primary audience, and that’s fine.
And yet I read the second book, and I’ll probably read the rest of the series. There’s enough here to keep me curious about where the fantasy thread goes, especially reading alongside my wife.
If 2025 taught me anything, it’s stepping out of my comfortable zone is worth it. Not everything will be great, but it all adds to my reading history.
Forget the numbers, I’m chasing books that make me think and remind me why I fell back in love with reading.
Happy reading in 2026! 🎉
", "date_published" : "2025-12-29T23:00:00Z", "id" : "https://alejandromp.com/personal/blog/2025-year-in-books", "summary" : "Looking back at 2025, reading kept surprising me. I wandered into new territories, like John Cleaver, tabletop RPG handbooks, and yeah, more Cosmere (because how could I not?).", "tags" : [ "Books" ], "title" : "2025 year in books", "url" : "https://alejandromp.com/personal/blog/2025-year-in-books" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Today I made an exciting discovery: the existence of AnchoredRelativeFormatStyle. An API that, as of the time of writing this, barely appears in search results other than Apple’s sparse documentation. And to my surprise, it’s exactly what I’ve been looking for over the past few years.
Some time ago, I wrote about An exploration of FormatStyle as a Dependency. Thanks to my team’s work, we pushed that exploration further and developed an interesting solution (which I should write about!).
During that work, we defined a few date formatters for our application. One of the most interesting ones was a formatter for relative dates.
In the old times, with Foundation Formatter APIs, to get a formatted string for the relative time between two dates, things like “2 days ago” or “Tomorrow”, one could use:
localizedString(for date: Date, relativeTo referenceDate: Date) -> String \nIn the new Foundation FormatStyle APIs, the way to do that is using the nice fluent API on a date:
.formatted(.relative(presentation: .named))\nThe new API looks elegant for quick code and tutorials. However, it becomes problematic when:
All these issues arise from the same root problem: the implicit dependency on the current Date(). In the Formatter API you could pass the two dates but in the new Style API you just call formatted on a single Date, without a way to pass a second one.
In our system using swift-dependencies, we had workarounds with limitations. While investigating improvements, I stumbled upon AnchoredRelativeFormatStyle - which solves our exact problem by allowing two dates!
As someone who watches nearly every WWDC video and stays current with the Swift ecosystem, I was surprised I’d never heard of this API. A Google search returned just a couple of results with no substantial information. Was I imagining things?
Thankfully, we live in a world in which Foundation is open-source and easily accessible, so I could just go to GitHub and actually check not only the source code for AnchoredRelativeFormatStyle but also its history. Thanks to that, I could find the Foundation proposal that described the background of this new API: The DiscreteFormatStyle Protocol.
The proposal document is very interesting, but it took me a couple of reads to fully grasp it. I recommend you take a read, but its purpose is to improve the existing FormatStyle infrastructure to enhance its performance when used directly in user interfaces, read: SwiftUI.
If you’re the one implementing SwiftUI Text and accept a string made from a formatter like the ones mentioned above, you can see how the existing API limits your optimizations. Your system needs to keep the UI up to date with an Input, “the relative target date” that doesn’t change, but internally the output (the string) depends on a moving target, “now”, which you don’t have visibility on because remember, the API is tomorrow.formatted(.relative). This means you don’t have any alternative other than recomputing that formatted string at a high framerate, even if the output of the format will only change once a second or even once a minute.
This is why the proposal introduced DiscreteFormatStyle, a new protocol that allows FormatStyles to expose when an output is expected to be different given the style configuration. This allows UI implementors to optimize the refresh rate by asking the style when it needs a refresh to be scheduled.
Some existing formatters were able to conform to the protocol without problems, but RelativeFormatStyle couldn’t because its current design has Date() as a hidden dependency, which means the format implementation is not a pure function and thus breaks the assumptions of the infrastructure around the styles. From the infrastructure’s point of view, “tomorrow” is constant so it could optimize things, but the fact that every call to format with the same input can give a different output breaks the assumptions. This is a bit tricky to understand until you internalize how format infrastructure works, with the styles themselves being just value types that are suposed to just be a wrapper around a pure function.
To solve the above, DiscreteFormatStyle’s design is a bit backwards from what we would expect. A naïve design for this API would be to have a parameter for the “now” in the style itself, something like:
tomorrow.formatted(.relative(to: now))\nThat would solve the problem I have with the existing relative style by removing the implicit dependency on Date(). But it wouldn’t solve the problem about performance as, even if now visible to us, the dependency on now that would change all the time wouldn’t be visible to the formatting infrastructure (aka format wouldn’t be a pure function).
So DiscreteFormatStyle works the other way around. The “anchor”, the data that doesn’t move, is part of the style, and the moving date is instead the instance where format is called on. Something like:
now.formatted(.relative(to: tomorrow))\nBut, as stated in the proposal, since this would break expectations from developers, the Foundation team decided to not offer the static method API at all. If you want to use this, you need to construct the FormatStyle yourself, which by the way, as we explored in my previous post, you can do for any FormatStyle, you just need to know the type.
Date.AnchoredRelativeFormatStyle(anchor: tomorrow).format(now)\nWe explicitly decided against adding such function for Date.AnchoredRelativeFormatStyle as that style always formats its anchor date, and only uses the actual format input as the reference date. Thus any spelling that starts with Date.now.formatted is ultimately misleading or very verbose. - A static factory function for
Date.AnchoredRelativeFormatStyle.
I understand that reasoning, but it also makes this API basically hidden and unknown, which is quite unfortunate. I guess if the main use case is as part of the SwiftUI Text it makes more sense, but for me this API has way more uses than that.
Since we already have our own bit of sugar on top of FormatStyles that mixes it with swift-dependencies, it’s quite easy for me to improve this API. One could argue if I should do it, but I think for my use cases it’s totally fine.
If you want to also be naughty, it’s quite easy:
public struct NaughtyRelativeFormatStyle: FormatStyle {\n public typealias FormatInput = Date\n public typealias FormatOutput = String\n \n var referenceDate: Date\n \n public func format(_ value: Date) -> String {\n referenceDate.formatted(Date.AnchoredRelativeFormatStyle.init(anchor: value))\n }\n}\n\nextension FormatStyle where Self == NaughtyRelativeFormatStyle {\n public static func relative(\n to referenceDate: Date\n ) -> Self {\n NaughtyRelativeFormatStyle.init(\n referenceDate: referenceDate\n )\n }\n}\n\ntomorrow.formatted(.relative(to: now))\nOf course the code above doesn’t implement all configuration options available on Foundation, but adding them is quite easy. I’ll leave that up to you so you make conscious decisions if you want to be naughty ;)
This was a very surprising day, I was not expecting to find such a hidden API that actually solved my problems. I still needed to do some work because we still want to use swift-dependencies, but at least I could use a modern API on new OSs and stop relying on the old Formatters. It also made me look again deeply into FormatStyles, which is a very nice API on the usage side but has some fascinating intricacies in its implementation.
", "date_published" : "2024-10-23T22:00:00Z", "id" : "https://alejandromp.com/development/blog/anchored-relative-format-style-the-hidden-replacement-for-date-relative-format-style", "summary" : "Today I made an exciting discovery: the existence ofAnchoredRelativeFormatStyle. An API that, as of the time of writing this, barely appears in search results other than Apple’s sparse documentation. And to my surprise, it’s exactly what I’ve been looking for over the past few years.",
"tags" : [
"Swift"
],
"title" : "AnchoredRelativeFormatStyle: The Hidden Replacement for Date RelativeFormatStyle",
"url" : "https://alejandromp.com/development/blog/anchored-relative-format-style-the-hidden-replacement-for-date-relative-format-style"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "Recently, while watching a Tsoding stream, I saw something that piqued my curiosity. Alexey demonstrated how one of his applications could render a video just by calling into the ffmpeg binary directly, instead of using it as a source code dependency or even a static or dynamic library linked to his program.
This caught my attention because, although I sometimes use binaries as dependencies by calling them (a good example is how I call the tailwindcss binary from Genesis to generate this website), it had never occurred to me to use them for something as sophisticated as rendering a video. Calling them to do something they can do on their own, like reading some files and generating output? Sure. But calling a binary and somehow passing the data to generate a video seemed like another level entirely. However, the more I thought about it, the more the idea made sense. After all, it’s all just binary data flowing through pipes. So, I decided to spend some time having fun with the idea.
The first part wasn’t very difficult; I just had to refresh my knowledge about the incantation of parameters necessary to ask ffmpeg to generate a video from a few frames, something I hadn’t done in years. With a list of parameters at hand, I started writing some Swift code to spawn a Process to run ffmpeg.
class FFMPEG {\n let process = Process()\n let pipe = Pipe()\n \n func startRenderingVideo(width: Int, height: Int, framerate: Int) throws {\n let resolution = "\\(width)x\\(height)"\n\n process.currentDirectoryURL = // directory to generate the file\n process.executableURL = // path to ffmpeg in your system\n process.arguments = [\n "-loglevel", "verbose",\n "-y",\n \n "-f", "rawvideo",\n "-pix_fmt", "rgba",\n "-s", resolution,\n "-r", String(describing: framerate),\n "-i", "-", \n \n "-c:v", "libx264",\n "-vb", "2500k",\n "-pix_fmt", "yuv420p",\n "output.mp4"\n ] \n \n // set a pipe to feed the frames via standard input\n process.standardInput = pipe \n \n try process.run()\n }\nWith this code, I was able to spawn ffmpeg and make it wait on standard input for a bunch of frames. Of course, the parameters can be tweaked as needed, but these worked quite well for what I wanted to try.
The next part was the interesting one: how to pass the raw bytes that defined each frame. For this, we need to look at the parameters I used. We asked for each pixel to be an rgba color and specified the resolution of each frame. So the next step was to create a buffer of bytes with the correct shape.
Thankfully, on macOS, we have great solutions as part of our tools. In this case, an old one: CoreGraphics. I could have done this part manually to make it work on other platforms, but since I was just having some fun and wanted to generate images with SwiftUI, I went with the easy solution. It would be interesting to use something else that worked on other platforms and make the bytes manually, but that’s an exercise for another day.
Here’s the bit of code needed to take the bytes from a CGImage and feed them into the Pipe:
func sendFrame(_ cgImage: CGImage) {\n let width = cgImage.width\n let height = cgImage.height\n let bitsPerComponent = 8\n let bytesPerPixel = 4 // RGBA = 4 bytes per pixel\n let bytesPerRow = bytesPerPixel * width\n let totalBytes = height * bytesPerRow\n\n var pixelData = Data(count: totalBytes)\n pixelData.withUnsafeMutableBytes { (ptr) in\n let context = CGContext(\n data: ptr.baseAddress,\n width: width,\n height: height,\n bitsPerComponent: bitsPerComponent,\n bytesPerRow: bytesPerRow,\n space: CGColorSpaceCreateDeviceRGB(),\n bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue\n )!\n\n context.draw(cgImage, in: CGRect(x: 0, y: 0, width: CGFloat(width), height: CGFloat(height)))\n }\n\n pipe.fileHandleForWriting.write(pixelData)\n}\nA few things to note in the above code:
CGContext needs to match what we’ve told ffmpeg to expect: four bytes per pixel, 1 byte per color component, etc.Data where I ask Core Graphics to draw the image. I would be curious if there was a different way of doing this because I imagine the draw actually needs to iterate through the image, but maybe there is a way to dump its bytes directly. Although that would assume the format is the same, so I guess it wouldn’t be very portable.Pipe, which is set as the standard input of the ffmpeg process, taking a file handle and writing the data into it. Through the magic of the operating system, this will transfer the bytes from one process to the other, letting ffmpeg render the frame of the video.The last bit we’re missing is very easy: just a way to tell ffmpeg that there are no more frames incoming. Otherwise, it will just keep waiting for more data. To do this, we just close the file handle of the pipe. Then it’s just a matter of waiting for ffmpeg to finish the rendering.
func endRendering() {\n pipe.fileHandleForWriting.closeFile()\n process.waitUntilExit()\n}\nAnd with this, we have a very simple class that will render a video from our given frames. Under the hood, it will use ffmpeg, but our usage code doesn’t have to worry about the intricacies of it anymore.
class FFMPEG {\n func startRenderingVideo(width: Int, height: Int, framerate: Int) throws\n func sendFrame(_ cgImage: CGImage)\n func endRendering()\n}\nTo try this out, I wanted to make a small animation with SwiftUI. From time to time, I have the need to create some animation to support an explanation, but I never do it because reaching for motion graphics software is a big step for something so simple. So I thought this would be the perfect time to make a proof of concept with SwiftUI.
The idea is quite simple: prove that we can get the frames of an animation that changes the contents of some text and another that moves a shape through the screen.
The SwiftUI part is, of course, very simple. It’s just a stack with some text and shapes:
VStack {\n Text(text)\n .foregroundStyle(Color.white)\n Circle()\n .fill(.red)\n .frame(width: circleSize, height: circleSize)\n .offset(x: (circlePosition+circleSize/2) - (width/2))\n Rectangle()\n .stroke(.green)\n}\n![\"SwiftUI](\"https://alejandromp.com/development/blog/using-binaries-as-libraries/ffmpegswiftuiframe.jpg\")
Getting an image, specifically a CGImage, from this view was also very trivial thanks to SwiftUI’s ImageRenderer.
let view = ToRender(text: text, circlePosition: circlePosition, width: width, height: height)\nlet renderer = ImageRenderer(content: view)\nlet cgImage = renderer.cgImage!\nffmpeg.sendFrame(cgImage)\nThe tricky part was figuring out how to get each frame. I would love to use SwiftUI animations and somehow just get a snapshot for each frame, but I’m not sure there is a trivial way of doing it that allows me to leverage SwiftUI animations. So instead of going down that rabbit hole, I opted to drive the animations myself.
This means, as you can see in the View above, that I can’t just use animation directly in the views. Instead, I need to manipulate their properties, like the circle offset, and then compute that myself on each frame. Luckily, SwiftUI exposes a few core types for animations that are separate from the view layer, so I can use that instead of letting SwiftUI drive the animation.
For example, we can use KeyframeTimeline to combine LinearKeyframe and even SpringKeyframe to then request the timeline value at a specific time or progress.
For the text, it’s quite simple for what I need. Knowing at which frame we are, we can just interpolate to know how many characters of the full text we want to display and just prefix the string up to that index.
let fullText = "Hello World!"\n// Animate text\nlet tEnd = Double(fullText.count-1)\nlet tkf = KeyframeTimeline(initialValue: 0) {\n LinearKeyframe(tEnd, duration: 1.5)\n SpringKeyframe(tEnd/2, duration: 0.5)\n CubicKeyframe(tEnd, duration: 1)\n}\nlet text = String(\n fullText.prefix(upTo: fullText.index(fullText.startIndex, offsetBy: Int(tkf.value(progress: progress))))\n)\nFor the circle that we want to move through the screen, we can use the same technique of using a keyframe timeline and asking it to get us the value at a certain time.
// Move Circle\nlet startPosition = 0.0\nlet endPosition = Double(width) - 100\nlet keyframes = KeyframeTimeline(initialValue: startPosition) {\n LinearKeyframe(endPosition/2, duration: 1, timingCurve: .linear)\n LinearKeyframe(endPosition/3, duration: 1, timingCurve: .easeInOut)\n SpringKeyframe(endPosition, duration: 1)\n}\nlet circlePosition = keyframes.value(progress: progress)\nAnd with this, I can just make a loop that generates all the frames needed and feeds them into ffmpeg.
let totalSeconds = 3\nlet totalFrames = framerate * totalSeconds\nfor i in 0..<totalFrames {\n let progress = CGFloat(i) / CGFloat(totalFrames - 1)\n // ... generate frame and send to ffmpeg\n}\nThe point was to have fun and explore the capabilities of calling binaries as if they were libraries, avoiding the integration cost that comes with source code or libraries in other languages. There’s always a trade-off, and of course, source code or library integration exists for good reasons. I haven’t come out of this thinking binary integrations are always the best solution, but now I have more knowledge and practice with them, so it’s yet another tool in my belt. And that was a goal well accomplished.
On the other hand, I have a proof of concept for creating videos from SwiftUI, which opens the door to using this technique in the future when I want to explain some things without having to do it with a full-featured video editor. Doing it in SwiftUI and code is actually faster for certain things.
And finally, I hope I’ve piqued your interest as mine was piqued! Have fun with programming!
", "date_published" : "2024-10-06T22:00:00Z", "id" : "https://alejandromp.com/development/blog/using-binaries-as-libraries", "summary" : "Recently, while watching a Tsoding stream, I saw something that piqued my curiosity. Alexey demonstrated how one of his applications could render a video just by calling into theffmpeg binary directly, instead of using it as a source code dependency or even a static or dynamic library linked to his program.",
"tags" : [
"Swift",
"Art of Programming and Paradigms"
],
"title" : "Using Binaries as Libraries",
"url" : "https://alejandromp.com/development/blog/using-binaries-as-libraries"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "Sometimes in command line tools we want to perform some cleanup final task before the process is killed. To detect this scenario we can hook to unix signals like an interrupt and perform the needed work before existing from the process.
This post was originally written in 2016-05-29 as a follow up to The state of Swift scripting and discussed my old library Trap in GitHub. Since then the ecosystem has grown a lot so it has been updated in 2024 with a more modern approach.
In the server ecosystem this is very well handled with the swift-service-lifecycle package, that brings support for graceful shutdown to concurrency tasks. What might surprise you is that the same package exposes a module for handling unix signals, without the service part. I find this ideal for command line utilities that don’t require the full service lifecycle of a server application but still want to handle unix signals.
To include this module you just need to depend on the library, but instead of including the service module into your target, you just include UnixSignals.
dependencies: [\n .package(url: "https://github.com/swift-server/swift-service-lifecycle.git", exact: "2.6.1")\n ],\n targets: [\n .executableTarget(\n name: "...",\n dependencies: [\n .product(name: "UnixSignals", package: "swift-service-lifecycle")\n ]\n ),\n ]\nWith this implace you can now import the UnixSignals module and instantiate a UnixSignalsSequence with the specific signals you want to listen to.
import UnixSignals\n\nfor await signal in await UnixSignalsSequence(trapping: .sigint) {\n print(signal)\n}\nIf you run this on your terminal and try to interrupt it with Ctrl + C you will see ^CSIGINT printed in the console but the process won’t stop. Now that you are handling the interruption is up to you to actually exit from the process. Isn’t it nice how respecful unix is?
If you want to kill the process use
Ctrl + Z. This will send a different signal and since we’re not handling that one it will behave as default and kill the proess. Alternatively just use Activity Monitor and force quit it.
With this power in our hands we can see an example of how it would work. In the following code we spawn two child tasks, one keeps a running counter that increments after a few miliseconds; the other awaits for an interrupt signal to be triggered.
await withTaskGroup(of: Void.self) { group in\n group.addTask {\n var i = 0\n while true {\n print(i)\n i += 1\n try? await Task.sleep(for: .milliseconds(500))\n }\n }\n group.addTask {\n for await signal in await UnixSignalsSequence(trapping: .sigint) {\n print(signal)\n print("Shutting down...")\n try? await Task.sleep(for: .seconds(2))\n exit(EXIT_FAILURE)\n }\n }\n}\nRunning this and using Ctrl + C we can see how the running counter keeps printing for a few extra seconds before the process is closed.
0\n1\n2\n^CSIGINT\nShutting down...\n3\n4\n5\n6\n7\nThis illustrates how we can have extra time to perform a gracefull shutdown of whatever process we are running.
If you need something more complex make sure to check out all the capabilities from swift-service-lifecycle.
", "date_published" : "2024-10-02T22:00:00Z", "id" : "https://alejandromp.com/development/blog/swift-catch-os-signals-trap", "summary" : "Sometimes in command line tools we want to perform some cleanup final task before the process is killed. To detect this scenario we can hook to unix signals like an interrupt and perform the needed work before existing from the process.", "tags" : [ "Swift", "Scripting" ], "title" : "It’s a trap! React to Unix signals in Swift.", "url" : "https://alejandromp.com/development/blog/swift-catch-os-signals-trap" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Recently, I finished an almost final draft of my novel and decided it was time to refresh my online presence and website. Instead of starting my next novel, I dove into creating the next version of my site, what I call alejandromp4. And, of course, you know what that means… using a new static site generator! Yes, I have a problem with focusing my hobbies; I’m working on it.
Let me first tell you what was the status quo of the version 3 of my site. It was built using Publish, a static site generator written in Swift. That worked really well as Swift is my favorite language, but more than that, it’s the ecosystem where I spend most of my time. This helps me avoid surprises when I come back to the website after a while, something I disliked about previous incarnations based on Ruby or Node, ecosystems that seem to break every time I had to publish an article.
But Publish wasn’t all roses. I have some peculiar requirements for my site around taxonomies and multiple sections that needed to work well together. Although Publish offers some customization options, it wasn’t enough. I quickly had to change some things in Publish, which meant discarding the nice defaults that come with it. I also had to fork it and open some internal functions to avoid repeating what was already built. Over time, I grew comfortable with that codebase and my customizations, but it’s not something I want to deal with long-term.
So, I thought it was a good occasion to look for a replacement.
Recently, another contender has appeared: Ignite. There are many others, but this one has the backing of a prominent figure in the ecosystem, which has propelled it to popularity. I spent some time with it, and it’s not that dissimilar from Publish—in the end, all static site generators are more or less the same. There are things I really like about Ignite, the documentation and the easy of use is really something to admire. But ultimately I decided it wasn’t for me. In an effort to be easy to use out of the box, it’s too tight for my taste. For example, to build pages, you need to accept using Bootstrap and a DSL, which is nice for a quick start but I needed the flexibility to not only use another CSS system (because I don’t like Bootstrap) but also use existing HTML templates that were already good to go.
I looked around for a bit and found other interesting alternatives with intriguing declarative systems to build the site in various shapes and forms. This is a trend in modern static site generators—a sort of declarative way of specifying pages and content for the generator. It’s an approach that aims to simplify the configuration process, though it comes with its own set of tradeoffs.
Ultimately, I came to the conclusion that it was time for me to tackle the problem myself. But I you should probably look at the mentioned projects if you are in need of a static site generator, they are very good and probably more inline what you expect.
With a few years of experience and having seen how other generators work, I thought it wouldn’t be too hard to make one myself. In fact, the core idea is an old one, as is the name, but I never pursued it because I didn’t want to have something to maintain.
Now, I was not happy with my current situation, a forked engine with the original project barely maintained. And if I had to switch to another project that, even if promising today, could be abandoned any time, I wouldn’t be in a better position. So the tradeoff of making my own is very different.
But if I have to build my own site generator, and make sure doesn’t take too much time from writing the actual content for the blog, I need to make a few decisions that will help me now and in the future. So I defined a core rule: simplicity.
This meant no fancy declarative rule system, no fancy HTML DSL, no building things from scratch, etc. But the best thing came with the realization that doing things that way woudl actually bring me all the benefits that I found lacking in other solutions. It was a win win sitaution!
So, armed with valor, some open-source code that I could reuse, and a few ideas in my mind, I sat down and started writing requirements to not lose the north star, drawing some diagrams, and finally coding.
The first overarching goal was to keep things simple—no, really, as simple as possible. I knew that remaking my entire site wouldn’t be trivial; there’s a lot of custom logic and hacks I’ve done to Publish that, although simpler in my own engine, still had to be ported. I also have some peripheral tools for my site (a CLI to work with it and a tool to create posters), but I was confident those could be moved directly.
I acomplish this by making the API very clear and specific, without fancy declarative engines or DSLs. What you get are just a few small protocols and a bunch of functions that you can call.
The other goal was to keep things flexible. Not to make this a fancy library, neither for my future self. It wasn’t flexibility for the sake of flexibility or purity. It was flexibility because I already know that my current requriements have some complexity that requires it.
Learned from experience, I don’t want to have defaults that become irrelevant as soon as you want to customize things. And if you want to customize things you should be able to reuse as much as the engine as possible without having to fork and make things public. This means that I don’t want to have a single call that does everything, but instead the tools that I can compose as needed.
Genesis provides APIs to load content and generate pages using simple function calls. It’s procedural on purpose. Just call the functions however you want without being tied to a specific structure or rule system.
For example there is a clearBuildFolder() function that does what the name indicates. But you don’t have to call it if you don’t want, nobody is forcing you. Of course when publishing your site you probably want to do a clean generation, but while iterating and previewing it? It’s just a waste of time. Or not. You decide. That’s the point.
What I wanted for sure the new generator to give me was the flexibility to handle pure HTML templates directly so I could take a beautiful template made from a good designer and just use it. But also I knew that eventually I would want to write some HTML in Swift with one of the fancy DSLs that everybody uses. But which one was another story. Beacuse of that I didn’t want to imbue the engine with any DSL, I wanted to engine to just work witht the minimum thing that needed.
So what’s the only thing that is needed as an input to generate a file that can be served? A String.
So instead of using a fancy DSL for typed Swift HTML, Genesis simply works with strings. This simplicity opens up a world of possibilities: from using existing HTML templates to experimenting with various Swift HTML DSLs, all without changing the core engine.
The advantage is that acomplishing this is also very simple, you just need a function that returns a String.
func render(context: Context) async throws -> String {\n """\n <html>\n <body>\n <p>A page in your site is just a String. Easy.</p>\n </body>\n </html>\n """\n}\nI know many will be screaming on seeing this, but honestly I’ve written most of this site you are reading in Swift String interpolation and is totally fine. Reusing “components” is just making a separate function that returns a String. It doesn’t get simpler than that.
And the best thing is that I can easily add fancy DSLs on top. It took me five minutes to add suport for a new DSL library, elementary, and a few more to try another one. Adding support for loading tempalted files is also trivial.
Something else I didn’t want was to tie the engine to specific web frameworks. For example, I’m not a fan of Bootstrap so that wouldn’t come prebacked. The old version of the site used Bulma but the previous version of my author site used TailwindCSS. So the engine doesn’t care what you use, again, it simply expects a String. It’s actually very nice how different requirements coalesce into the same goal.
Genesis doesn’t automatically load any dynamic content for you. I don’t want it to check specified folders for predefined files. Instead Genesis expects you to define ContentLoaders to load dynamic Content. This allows you to determine what the content is and how it’s loaded, from markdown files, a database, or a remote CMS. The engine doesn’t care about it.
A simple async function is all you need to implement. Even what “content” is is not defined, you bring your own.
struct BlogLoader: ContentLoader {\n\tfunc load(context: Context) async throws -> sending [any Content] {\n let contentDirectory = await context.contentDirectory\n let contents = try FileManager.default.contentsOfDirectory...\n return try contents\n .map { BlogPost(...) }\n}\nBesides loading content, the other core concept of the engine is generating pages. A Page is a type that implements the render function explained above. That’s it. This makes it very trivial to generate single pages for your site, things like the Home or the Author page.
But there are pages that need to be rendered multiple times, for each instance ot the loaded content. like each post page. For this the engine has another simple protocol, the PageProvider. And again, it’s a very simple requirement: just return a list of pages.
func source(context: Genesis.Context) async throws -> [any Page]
These few basic requirements are what defines the core of the engine, which also makes it very easy to understand what’s the process of generation and how you interact with it.
And the reality is that that’s all a static site generator is at its core. When you put it this way it’s not that scary anymore. If you even think about it, and I have, half of these protocols are not even necessary from how simple they are. But I found that having them helped me have a better mental model of the core of the engine.
The beauty of this simple architecture is that it let’s me expand it as needed. I already mentioned above that adding a DSL for HTML is very simple, but there is more that can be done.
To reiterate, the core of the engine doesn’t do anything for you. You might expect RSS, sitemaps, etc to be generated, like it happens in most other engines. But in Genesis that’s up to you, you give it the Pages that you want to generate.
But of course, RSS and Sitemaps are pages that are quite standarized. So for that I took some code from other engines and with a few tweaks it was working fine for my site. Now this are bundled in the library but is up to you to use them or not.
This is probably the first thing anybody wants from a static site generator, so you might be surprised that, again, Genesis doesn’t have support for Markdown fiels embeded into its core. That’s another consious decision. I don’t want to make the mistake of embeding a specific library that will make things harder for the sites build with the engine, I’ve already suffered that in the past.
But agian, Genesis doesn’t need this embeded, it can be added from the outside because its core is very small. In my case I’ve decided to use Apple’s swift-markdown because I think is a safe bet nowadays, it makes it trivial to parse Markdown fiels intro an AST that then can be transofrmed into a String.
Crucially, the fact that I have full control over the Markdown library used and of the type that defines a “post” means that it has been trivial to do something that I’ve found impossible in any other site: keep the markdown tree trough all stages of generation so it can be tweaked in specific pages. This small thing has given me so many headaches over the years that I can’t believe how trivial it is in Genesis. Just because you have the contorl and you decide.
By going back to the basics, I’ve been able to build a static site generator and port my site to it in a few days. I love how Genesis offers a flexible and powerful static site generator that doesn’t constrain you to specific workflows or technologies. It’s designed to grow with your needs, allowing for simple setups for basic sites and complex configurations for more demanding projects.
I haven’t optimized for a marketable experience, so while it may not have the polish or out-of-the-box features of some popular generators, Genesis provides the building blocks for creating exactly the site you want, without fighting against pre-defined structures or limitations. It’s a testament to the power of simplicity and the value of understanding your tools from the ground up.
Of course this is just the begining, I will continue to develop and use Genesis for my own site, I’m excited to see how it evolves. I already have a few ideas to add more batteries while keeping the core simple.
And finally, this is not a sales pitch. As I said at the start, you probably want to check the existing generators with bigger communnities, but if you like things simple and are not afraid of getting your hands dirty you can try Genesis. Or maybe if you want to build your own this post can serve as a guide and word of advice: keep it simple!
", "date_published" : "2024-09-24T22:00:00Z", "id" : "https://alejandromp.com/development/blog/back-to-the-basics-with-genesis", "summary" : "Recently, I finished an almost final draft of my novel and decided it was time to refresh my online presence and website. Instead of starting my next novel, I dove into creating the next version of my site, what I callalejandromp4. And, of course, you know what that means… using a new static site generator! Yes, I have a problem with focusing my hobbies; I’m working on it.",
"tags" : [
"Swift",
"Project",
"Release",
"Meta"
],
"title" : "Back to the basics with Genesis",
"url" : "https://alejandromp.com/development/blog/back-to-the-basics-with-genesis"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "In my team, one of the things we always make sure of is keeping our dependencies up to date. We rarely add a dependency without a really good reason, and when we do, we assign an owner who is responsible for keeping it up to date.
These owners always keep an eye on new updates and make it a task to go through them as soon as they can. But sometimes, life happens, and one is not able to keep up with it. More often than not, though, the reason why updates are not kept on top of is simply because people forget that it’s part of their responsibilities. And I don’t blame them. Right now, we just keep the list of owners in our documentation site, which is a very passive way of doing things.
Instead, we’ve now worked on upgrading our nightly notification system! This existing system not only runs a set of unit tests and sends a message with test results and code coverage to our Slack channel, but it also shows a list of outdated dependencies thanks to swift-outdated and some custom code on top that is part of our development tools.
So before, the message just included a table of dependencies to be updated:
| Package | swift-composable-architecture | 1.12.0 | 1.13.0 | ❗️
But now, we’ve added an @mention to the Slack user responsible for each outdated dependency.
In my experience, the reason updates often get neglected is simply because it can be easy to forget or overlook tasks that aren’t constantly in front of you. That’s why I think having a system for notes is so crucial - it helps keep important responsibilities top-of-mind. By providing a daily reminder of the pending updates they are responsible for, our new notification system has helped streamline things for the whole team.
Doing this is very simple since we already have the infrastructure in place. It was just a matter of having a mapping between dependencies and Slack users in our CLI. Something very low-tech that does the work 👌
But there was an extra requirement of mine: if there is a dependency we don’t have an owner for, we send an error on the nightly message so we can assign one immediately. This is something not trivial with swift-outdated because that reads from the .resolved file, which has no information about what dependencies are transitive and which ones are directly yours. Since in our opinion, we don’t want to be bothered with transitive dependencies, we don’t assign owners to those.
To solve this, we read the Package.swift file in advance so we know what the direct dependencies are. This is quite simple, as SPM makes it very easy to get a JSON representation of a package: swift package dump-package.
So work done.
But you know me, I can’t avoid getting excited with interesting ideas. So when discussing how to approach this with my team, I wondered… what if we could attach the owner to the dependency itself in the Package.swift file? Well, hold my glass of water.
Something I love about SPM is that the package definition file is actually a Swift file, which means you can run Swift code in it. Thanks to that, we can add an API to the PackageDescription that does what we want.
.package(url: "...", exact: "...", owner: "...")\nTo do this, we can extend the SPM types with our own method. Of course, we need to return what SPM expects.
extension PackageDescription.Package.Dependency {\n static func package(\n url: String,\n exact version: Version,\n owner: String\n ) -> PackageDescription.Package.Dependency {\n .package(url: url, exact: version)\n }\n}\nSo what’s the point of having the new parameter if it’s not used? Well, that we have it in the same source, and we can extract it from it!
But if you’re thinking SPM dump will include this data, well, of course, it won’t, as SPM doesn’t know anything about it. That doesn’t mean we can’t get it; it just means it’s our work. For things like this, I always rely on swift-parsing, and it makes it quite easy to extract the dependency from the file.
This is the output of running a quick proof of concept command line:
▶ ./spm-owners Package.swift\n┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓\n┃ ┃ Package ┃ Version ┃ Owner ┃\n┃ ┃ <String> ┃ <String> ┃ <String> ┃\n┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩\n│ 0 │ swift-parsing │ 0.13.0 │ Martin │\n│ 1 │ swift-argument-parser │ 1.5.0 │ Martin │\n│ 2 │ swift-composable-architecture │ 1.13.0 │ Alex │\n└───┴───────────────────────────────┴──────────┴──────────┘\nI love this! Having the ownership data as part of the Package.swift makes it so things are always in sync and up to date.
Of course, I’m not using this in our team’s system because it’s not production-ready; it’s just a proof of concept. The big disadvantage is that although Package.swift can run Swift code, you can’t just import a separate package, which means one would have to copy-paste the code above manually. Not a deal-breaker, but not nice enough for me to want to maintain 😂 If one could import in the package file, it would be another story.
So there you go, an interesting proof of concept that has kept me entertained for a couple of hours. I wish SPM would officially support a way to accomplish this, somehow to be able to add metadata and that it would be kept for other tools. And maybe there is, and I’m not aware?
You can check out the proof of concept on the spm-owners repo, if you are curious.
", "date_published" : "2024-08-20T22:00:00Z", "id" : "https://alejandromp.com/development/blog/swift-package-manager-dependency-owners", "summary" : "In my team, one of the things we always make sure of is keeping our dependencies up to date. We rarely add a dependency without a really good reason, and when we do, we assign an owner who is responsible for keeping it up to date.", "tags" : [ "Swift", "Swift Package Manager" ], "title" : "Swift Package Manager Dependency Owners", "url" : "https://alejandromp.com/development/blog/swift-package-manager-dependency-owners" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Every year SwiftUI improves and gets new modifiers that widen the capabilities of the framework. Sadly, as responsible developers, we can’t use any of that because our users take some time to update and, as opposed to the Android ecosystem where Jetpack Compose is just a library embedded in every app, we need to wait for our users to be at the required minimum OS version to enjoy those fancy new tools.
Or do we?
There are some APIs that are easy to backport if we disregard the old versions of the operative system. This may sound awful but is a valid option that is worth considering. If you know you have a very little percentage of users stuck in the old version but you can’t get rid of it because of some policy, you know the impact is very minimal. And if time has already passed and dropping that version is on the horizon, you have more reason to plan for the future and not get stuck in the past. No matter what, we should make sure that users in the old version don’t get a bad experience. It may be not perfect and modern, but they still should be able to use the app properly. It’s a case-by-case decision that you have to take, but if you do, here is how to pull it off.
We will focus on SwiftUI modifiers. Other features can also be backported, but they will need slightly different techniques. The one for modifiers is actually quite simple, but it always depends on the functionality itself.
I’ve used this technique for a while, and it works very well. For example the scrollDismissesKeyboard(_:) modifier is a good candidate. It’s a new functionality that users in old versions won’t miss because they wouldn’t have access to it before (well, unless your app was UIKit, again, case by case).
The first step is to copy the modifier function signature in your own View extension:
extension View {\n /// docs...\n @available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, *)\n public func scrollDismissesKeyboard(_ mode: ScrollDismissesKeyboardMode) -> some View\n}\nI also recommend copying over the documentation so the users of this function will get all the info they need. Just as if it was the legitimate function from the framework.
Conceptually the implementation of the function is very simple: we check in which OS version we are and we call the SwiftUI function when available and fallback to something else when not. This applies to all modifiers you want to port, but there are two things to consider.
What do you do as a fallback? That’s the first question to consider and it will depend on the feature, its complexity, how much worth it is for you and a multitude of other aspects, technical and non-technical. This is the “case by case” part of this work.
In this example, the fallback is simply to do nothing. And that works for many cases, really. To implement this, we just need to return self in the old version so our modifier does nothing with the view.
if #available(iOS 16.0, *) {\n self\n .scrollDismissesKeyboard(mode)\n} else {\n self\n}\nThat’s what we want, easy, right? Well, remember that for this to work, we need to opt in this function into the ViewBuilder DSL. Check out ViewBuilder vs. AnyView for more details about this.
If your modifier didn’t take any parameters, that would be all you needed, but that’s rarely the case.
Most modifiers take some parameters to adjust its functionality. Those types are often new and thus not present in old versions, so we need to port those too.
The process for that is similar, just copy the existing types into your own file.
public struct ScrollDismissesKeyboardMode {\n public static var automatic: ScrollDismissesKeyboardMode { get }\n public static var immediately: ScrollDismissesKeyboardMode { get }\n public static var interactively: ScrollDismissesKeyboardMode { get }\n public static var never: ScrollDismissesKeyboardMode { get }\n}\nNow that’s a fine way to start, but I find it significantly easier to work with an enum. That way, you don’t have to worry about internal implementations or storing any data. Furthermore, I also recommend prefixing the name of the type so is distinct from the SwiftUI one. This is not strictly necessary, but I’ve found that makes the compiler way happier as it helps distinguish the functions easily. It’s also a hint to the user of the function that there are some shenanigans going on.
So let’s convert that type to an enum instead:
public enum MyScrollDismissesKeyboardMode {\n case automatic\n case immediately\n case interactively\n case never\n}\nThis makes it so the usage side can use the same dot syntax and names as with the original function while using our custom types. But we still need to give SwiftUI its own types, so I always add a property to do the conversion.
// MyScrollDismissesKeyboardMode\n @available(iOS 16.0, *)\n var swiftUI: ScrollDismissesKeyboardMode {\n switch self {\n case .automatic: return .automatic\n case .immediately: return .immediately\n case .interactively: return .interactively\n case .never: return .never\n }\n }\nThis property is only available in the new OS since when we call it we will be in the correct version.
Now we can switch the function to use the new type.
@ViewBuilder func scrollDismissesKeyboard(\n _ mode: MyScrollDismissesKeyboardMode\n ) -> some View {\n if #available(iOS 16.0, *) {\n self\n .scrollDismissesKeyboard(mode.swiftUI)\n } else {\n self\n }\n }\nAnd that’s the function fully back ported. We take our custom parameter, and if we are in the new version, convert it to the SwiftUI one and call the real modifier. Otherwise, we just return the view unmodified.
With this, the usage side would look exactly as with the real code.
SomeView()\n .scrollDismissesKeyboard(.immediately)\nFor that to work you just need to make sure your function is in your module, or if it’s in a separate package (which I always recommend) you need to import it in your file.
This works because your code always takes precedence over system frameworks. This means the compiler will pick your custom function and types before SwiftUI’s.
Another very useful tip is to use an availability annotation to ensure the compiler will remind you to remove this code when your minimum target matches the one that introduced the modifier. For this, we can add an @available with the obsoleted parameter.
@available(iOS, obsoleted: 16.0, message: "SwiftUI.View.scrollDismissesKeyboard is available on iOS 16.")\nThis is very helpful and makes the compiler work for you.
Just like deciding what to do as a fallback based on tradeoffs, choosing which parameters and features to support is important too.
For example, if we want to port presentationDetents(_:) we will find out is a bit more complex. The custom detent needs some generic work that might not be trivial, so when you see that sort of complexity you can decide to just ignore it. Remember that this code is for you. It’s likely that you are not trying to make a full featured framework for the entire world, so if you don’t need some functionality right now, just skip it. By the time you need it, you will use the native solution already.
So in this case, you may decide to simplify the detents you offer:
public enum MyPresentationDetent: Hashable {\n case medium\n case large\n case fraction(_ fraction: CGFloat)\n case height(_ height: CGFloat)\n // no custom detent supported\n}\nThis technique is not only useful to back port functionality to older OSs but also to improve functionality and make it work the way you want. You can use the same technique, ignoring the version checks, and that will give you a way to offer more reusable parameters and options and to have a reusable place to include extra logic, all of that while keeping the same syntax as the system.
This is beneficial because it allows your code to be easily adjusted when Apple adds new options natively, saving you from having to completely refactor multiple views.
This technique is just another tool on your belt. It’s up to you to decide when is appropriate to use it, but I recommend you to think about it. There are plenty of times when we could use modern APIs with little problem while keeping compatibility with older systems.
Just have it in mind, analyze the tradeoffs and decide.
", "date_published" : "2023-10-19T22:00:00Z", "id" : "https://alejandromp.com/development/blog/backport-swiftui-modifiers", "summary" : "Every year SwiftUI improves and gets new modifiers that widen the capabilities of the framework. Sadly, as responsible developers, we can’t use any of that because our users take some time to update and, as opposed to the Android ecosystem where Jetpack Compose is just a library embedded in every app, we need to wait for our users to be at the required minimum OS version to enjoy those fancy new tools.", "tags" : [ "Swift", "SwiftUI" ], "title" : "Backport SwiftUI modifiers", "url" : "https://alejandromp.com/development/blog/backport-swiftui-modifiers" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "It’s time to review and reflect about Yumi and the Nightmare Painter, the third instalment in The Year of Sanderson and the second in the Cosmere. This will probably become one of my favorite books of the Cosmere and be in my top tier of fiction books.
Rating: 5/5
I haven’t experienced many world-hopping narratives, so what might come across as a trope to some was very appealing to me. The execution of the plot is brilliant, especially the dynamic where the two main characters need to learn to live each other’s life. It is fascinating how Painter, who comes from a modern world akin to ours, needs to understand and follow the constraints of a world made by doctrine. In contrast, we observe Yumi thrust into a more open-minded world as she navigates her inner suppression and confronts her fears.
The asymmetry goes further than that. Painter having to live in Yumi’s body initiates a subtle, yet impactful, conversation about the experience of living in a body that doesn’t align with one’s identity, a conversation still too often silenced in our society. On the other hand, Yumi keeping her own body introduces a more conventional underpinning of deception to the plot. The contrast between these two representations of what is living in a foreign world operates on many levels that are fascinating to read. The origin of these differences and the magic behind them are a mystery that keeps you hooked until the end.
Setting aside the fantasy and magic of the story, which in typical Sanderson’s fashion is one of the best ones I’ve experienced, what resonated deeply with me was the core theme of personal growth. The journey of self-improvement that forces the characters to open their mind and shift their perspective, dismantling their own dogmas and fears. Among the many narrative threads, a particular subplot I really liked was about meditation. What started as a push for the other character to do meditation in the only correct way evolved into the understanding that each person is different and has its own path to tranquility, of emptying their mind or even of not emptying it at all. Coming to terms with the difference between each individual was an enriching and fulfilling experience.
The other part I liked a lot was the intricacies of the love story. As I often tell my wife, love finds its way in every tale, even in those that don’t exactly belong to the romance genre. I’ve never been captivated by the romance genre, but I still find myself seduced by the deep connections that love weaves into every story. With “Yumi and the Nightmare Painter”, while the main plot is about figuring out what happened and how to fix it, through the course of the story we see how two strangers naturally bound thanks to mutual understanding and sharing their fears. This evolution culminates in a lovely relationship that plays an integral part of the climax. It’s a delight to see the author be less shy with certain scenes and letting these human aspects arise n the story.
Now, the question that everybody asks: Is this book enjoyable if you haven’t read the Cosmere? Well, I can’t tell you for sure because for me the Cosmere is the main reason I love Sanderson’s work. I’m a sucker for interconnected stories and worlds and is where a big part of my enjoyment comes from. Yet, I truly think that you can enjoy this, and all other stories, without being an expert in Realmatic Theory. The story stands on its own and is self-contained. You will miss on the occasional nod to the rest of the Cosmere but that is normal and expected. So don’t ignore this book just because of this.
I want to conclude with the only point of critique I have about this book, a concern that involves none other than our beloved and mischievous Hoid. The voice of the book being narrated by Hoid is very interesting. It feels different from other occasions while still being clearly Hoid. This narrative choice worked really well. However, I have to admit that there are a couple of moments where the exposition runs for a bit too long, even for me. This was particularly notable towards the end of the story, when the prose stops showing the events and just lets the narrator tell us exactly what happens in what feels like an “info dump”. Granted, it makes sense from the narration point of view, as Hoid is narrating the story to somebody in the Cosmere, but while I was immersed in the story this pulled me out of the fiction immediately and made me ask: am I accepting this because the author is Brandon Sanderson? Would I accept it from another author lacking the same level of reputation?
The immediate answer that came to mind was that I would have been more critical of another author. However, after some introspection, I realised how I ignored a critical factor: context. Brandon Sanderson has not only carved his reputation through the years, but directly made a tremendous impact on me. Of course I can accept a bit of whimsicalness from time to time if that’s what he enjoys. I shouldn’t forget that’s precisely why I baked the secret projects and why I love them so much!
In summary, a resounding endorsement. Must read. Cosmere pinnacle, and top fantasy book.
", "date_published" : "2023-07-17T22:00:00Z", "id" : "https://alejandromp.com/personal/blog/yumi-and-the-nightmare-painter-review", "summary" : "It’s time to review and reflect about Yumi and the Nightmare Painter, the third instalment in The Year of Sanderson and the second in the Cosmere. This will probably become one of my favorite books of the Cosmere and be in my top tier of fiction books.", "tags" : [ "Books" ], "title" : "Yumi and the Nightmare Painter, review", "url" : "https://alejandromp.com/personal/blog/yumi-and-the-nightmare-painter-review" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "The conclusion of the Remembrance of Earth’s Past Trilogy comes to an end. The story has come far since those first chapters of The Three-Body Problem so focused on Chinese history that one had to read translators comments to understand the intention of the words. Now, after many years after the crisis began, humanity lives in a completely different world, confronting threats that were unimaginable before.
I really like how we see the conclusion of some of the recurrent characters, some who I ended up despising and others that I felt close to. But the character that makes more progress is humanity itself. The challenges that face humanity in this story are eye opening. The author not only presents a sci-fi story to spark a wild imagination, but it also solidifies philosophical questions and shows the possible consequences of our naïve space exploration.
For years, we have been wondering if we are alone in the universe, if there is life beyond the heat of our sun. And assuming we are not as special as we usually pretend, why we haven’t found it yet. Remembrance of Earth’s Past puts us in a fictional result of those thoughts. It tells us what could happen if we keep asking those questions instead of asking if we should even look for other civilizations. Maybe we should do everything we can to make ourselves invisible in the vastness of the dark forest.
Seeing the consequences of the Dark Forest theory, introduced in the previous book, and put beyond what I could have imagined, is also great. The author keeps surprising me with additional levels of power and technology. I always wonder how much further can power go in a science-fiction scenario. I’m used to see fantasy grow the power to extremes, but how can you do that with hard science and technology? The technologies and fundamental theories explored by this series are mind blowing. From new forms of communication to technology to travel at light-speed, even higher dimensional physics, the series explores mind-blowing concepts that will make me read additional explanations and summaries to grasp fully.
As with everything I read, some details run wild in my imagination, morphing and growing to eventually settle in some part of the Pulubi. It’s what I love the most about reading, how it fuels the infinite machine of imagination to bring into existence new forms.
One concept that fascinated me the most is to see how the author raises the question of what makes us humans. During the events of the book, we find on multiple occasions when humanity itself considers how some fellow humans have lost their humanity, how they are something else entirely. I often find thoughts like this come from brutal acts that dehumanize the characters in question or from a scientific long evolution that departs the physical form from the original. But in this case, the author makes us question how seemingly small acts and just a bit of time can come to question if those committing them are still one of us. Seeing how being isolated in a spaceship in an unreachable part of the universe makes one question their relation to humanity. Or how stuffing the entire human race in a confine space and make it fight for survival to the extreme would make us consider if those taking part in such survival game are still human.
Overall, I really liked the book and the series. Very thought provoking, with plenty of ideas that will keep echoing in the back of my mind for a long time.
Now let’s see how the adaptations fare in comparison.
", "date_published" : "2023-07-03T22:00:00Z", "id" : "https://alejandromp.com/personal/blog/death-s-end-review", "summary" : "The conclusion of the Remembrance of Earth’s Past Trilogy comes to an end. The story has come far since those first chapters of The Three-Body Problem so focused on Chinese history that one had to read translators comments to understand the intention of the words. Now, after many years after the crisis began, humanity lives in a completely different world, confronting threats that were unimaginable before.", "tags" : [ "Books" ], "title" : "Death's End - The naïveté of humankind, review", "url" : "https://alejandromp.com/personal/blog/death-s-end-review" } ], "language" : "en", "title" : "All articles - Alejandro M. P.", "version" : "https://jsonfeed.org/version/1.1" }