You can indeed have your very own agent in a matter of a few dozen (pretty-printed!) lines of Python plus API access to a tool-call-capable LLM, per Simon Willison’s definition: “an LLM agent runs tools in a loop to achieve a goal”.

Thomas illustrates this with a chat client for the OpenAI Responses API that lets GPT-5 get local ping times for a target, if that helps it reply to the user.

I built an agent too. I swapped OpenAI’s API and SDK out in favour of Ollama’s, in front of Qwen3 models. Now I, too, have a chat client that can run code on my computer and respond autonomously when an LLM needs some ping data. I’m a modern Prometheus!

It was simple to implement. But now I had a lot of questions. What’s happening on the other side of the API boundary, to make it so simple on this side of it? How does a model “make a tool call”? How do I design the best ping tool?

There was a lot of scenery in between me and a proper appreciation of how incredibly easy it was. I’m writing this to share the scenery.

Wait: are tools in a loop really agentic?

That question is backwards, isn’t it? It’s chasing AI buzzwords. But I’m suitably impressed by the fact that my little Python script, talking to qwen3:1.7b on my 16GB Mac, can answer how's my connectivity to google? without asking me to ping google myself.

So looking at it frontwards, agent seems like a perfectly serviceable word for this—this being the combination of the Python client, the API and backend, and the LLM. And tool use is the key.

…did you notice that we haven’t defined “tool”?

Tool use is an API feature

Here’s what I know after making a minimal agent with Ollama and Qwen3.

• I put into an API request payload: JSON schemas for my custom functions, a system prompt, and a list of messages.
• I get back a message with separate fields for natural language and tool calls.
• And the tool calls, if they come, always come in the same format and refer to one of the functions I described in a schema.

So in this setting, we’re talking about an API feature: a universal adapter to allow API customers to plumb in custom functions to their LLM clients for the model to invoke.

OpenAI announced “function calling”, the API feature, in June 2023. It was enough of a game changer that Anthropic had a beta version of its own (“tool use”) to go along with Claude 2.1 by November.

It’s all a bit shadows-on-the-cave-wall. I may need to know how this works if I want to do something more sophisticated than ping.

Apropos that: if you’ve been putting it off, I highly recommend taking the time to watch Andrej Karpathy’s primer, Deep Dive into LLMs like ChatGPT. It doesn’t demand deep concentration, and just doing the first half at 1.5x speed can save hours of wading through hype and slop.

Tool use is baked into model weights

Behind the API is a model that knows how, given a string of tokens—the context—that contains schemas, messages, and a system prompt, to emit—when it makes sense to!—a string of tokens containing a list of tool_calls that the backend can isolate and pass to my client. Which the client can, in turn, recognise as valid function calls.

A model gets good at following this pattern through training—specifically, “supervised fine tuning” (SFT)—on full examples of that behaviour.

It’s similar to how a base model—a “token-level internet document simulator”—can learn to role-play consistently as an assistant having a conversation with us, but with more rigorous constraints on the output structure.

The point is that if I’m using a tool-calling API feature, the ability to participate in this API feature is baked into the model weights. If I control the system end-to-end, I can fine-tune for different structured output, given different contextual clues.

For example, if my agent will have occasion to get information from the web a lot, I can consider fine-tuning for a specialised contract that kicks off some web-search machinery directly, rather than squeezing it through the generic tool-use interface first.

In the spirit of the tools-in-a-loop criterion for…agency? agenticness?, that would be a tool, too.

Tools are code an LLM can ask to run

LLMs are good at mimicking syntax conventions. Tools are code that an LLM can invoke by emitting structured output with a pre-agreed syntax.

Tools let us use something LLMs are good at to stop using them for things they suck at.

Clarifying the context

I still couldn’t picture how the context gets assembled from all the stuff in the API payload in order to elicit this tool-calling behaviour.

We can’t look at how OpenAI’s backend composes this final string, but we can see how Ollama does it: it processes the API request through a template (here’s the one for qwen3:1.7b) based on what Ollama contributors know about what the model expects—e.g. from docs.

The Qwen3 template uses everything to add structure: JSON, Markdown headings, and XML tags, plus dedicated tokens (for, e.g. <|im_start|> and <|im_end|>) that encode the conversation format unambiguously.

If the user supplies schemas in a tools field, they’re included as part of the system prompt, along with instructions for their use, including the format to use for a function call:

<tool_call> {"name": <function-name>, "arguments": <args-json-object>} </tool_call>

The model reliably follows this pattern, so the backend can package the tool_calls into a list, inside a message, in an API response.

Unix utilities are not tool-shaped

A cool ping demo tool notwithstanding, The Platonic ideal of an LLM tool call doesn’t map 1:1 to the Platonic ideal of a Unix shell utility. Nobody told me it did! I bring it up because I might have missed the mismatch if I hadn’t tried to give my agent a ps tool.

In contrast to utilities running in a Unix shell, LLM tools, the implementation we’re talking about here, don’t compose. The model can call multiple tools in one turn, but they don’t feed into one another. Each tool does its own thing, and then we can tell the model about everything that happened.

ps is confident that it’s not alone: that, as a human trying not to drown in hundreds of lines of ps aux output, I can pipe it into head or grep or awk. If I want my ps LLM tool to return the first 10 lines of ps output, I need to build truncation into it—there’s no pipeline operator to connect it to a head tool. And with that, my tool ceases to be ps-shaped.

That’s all I’m saying. Good LLM tools are analogous to the whole shell command when you hit Enter, whether that’s a single Unix utility or a pipeline, and whether you use existing binaries under the hood or write all new code.

But are they good inside tools?

Too many variables! What I know is that LLMs are really good at them. It’s enough to tell a model, “here’s a tool that runs BSD ps with the args you provide” for the model to (a) know when to call that tool, and (b) rummage around in its weights and pull out ps -o pid,pcpu,etime,user,command -r fully formed.

I gave my ps tool a single parameter that’s an array of args, and let the model freestyle them all. My agent can accept a function call with name='ps', arguments={'args': ['-o', 'pid,pcpu,etime,user,command', '-r']}. The model has to work backward from the complete command to fit it into my tool, but even the 600-million-parameter Qwen3 model does that part fine.

I like this a lot! I don’t have to clutter my context with a lot of individual ps options. They’re already trained-in. I bet I could add an option to truncate the output, without losing the advantage of LLMs being able to spit out whole Unixy incantations.

But maybe it’s actually more efficient if every tool is semantically named, like get_topk_processes, with, in turn, well-defined and semantic options. (Built with Unix binaries, or not.)

And that’s not to mention the great-power/great-responsibility option: making the tool a shell and letting the model straight-up propose any pipeline it wants.

Prompt engineering is real, or at least stuck to the wall

No training corpus has my custom functions in it, obviously.

The model knows the tool-calling pattern. For success with a given custom function, it depends on my schema, my system prompt, and my other prompts to figure out when to use it, which args to use, and how to interpret the output.

Claude and GPT-5 deal very well with sloppy contexts, but the less overpowered the model, the more prompt engineering matters. qwen3:0.6b can get a ping tool to run, but needs me to add the .com to google. With a pointed system prompt, it can get past that hurdle. Some of the time.

I’m definitely not attached to the term “prompt engineering”. “Context engineering” is massively important, but, I think, too broad a term. I’m talking about the part of that that’s just trying different wordings to nudge an LLM to emit the magic tokens. The very nature of that activity strikes me as more absurd than the name.

In any case, the “prompt engineering” farfalle flew across the room years ago and the wall is studded with petrified bowties. It’ll be a job to scrape them all off now.

Complicated > mysterious

Tool use is the key to self-service reality checks for LLMs, and stochastic spice for automations.

If that’s at all spooky to you, like it was to me, I agree: build an agent! Just know, going in, that it’s hard to do ping and walk away.

Once you’ve seen how to manage a simple message history, and got one tool call to work, a lot of other stuff comes into view. You start having neat ideas for more specialised, parsimonious, autonomous, secure agents. Some of those ideas are chores, like validation and error handling. Incredibly easy becomes more complicated when you dot your i‘s and cross your t‘s, but even the tedium feels compelling when all there was before was mystery.

• Wait for the user to input a prompt
• Add a message to chat history containing the user input
• Send any system prompt (or none) + full chat history to the model (via API)
• Add the completion from the model to chat history
• Repeat

Here’s mine in a gist.

To transform that into an agent:

• Write a schema for each tool, to tell the model what it’s good for and which arguments it takes
• Write the function that runs when the model asks for a given tool
• Send all the tool schemas in the API request payload along with the message history
• Add an “agent” loop that checks for a list of tool calls in the API response, and
  • runs each tool call’s function, tacking a message containing each function’s output onto the chat history
  • makes the next API call containing the snowballing history

When the model produces a tool call, it’s the client that turns the crank on the next inference run. When there’s no tool call, we pop out of the loop, display the output, and wait for the user to prompt again.

Here’s my ping-enabled agent for a local Ollama-hosted model.

I have a personal TUI text-editor app thingy that runs in a terminal emulator.

One of my main ambitions for this program was that it should be intuitive to use, for my personal value of intuitive. Ideally, the editor should work like this on my Mac:

• Ctrl-Enter or Cmd-Enter to “submit” a thing
• Ctrl-X/C/V or Cmd-X/C/V to copy/cut/paste text
• Arrow keys to move the cursor
• Option-Left/Right Arrow to move by a word (where Option is AKA Alt)
• <Some modifier>-Left/Right Arrow for Home and End

Some of this fights terminal-emulator norms.

Because I put the cart before the horse (vibe coding), I bumped up against constraints by trial and error, which left me with only a vague understanding and a bunch of superfluous code.

I am back to nail down what’s copacetic and what needs a workaround. This stuff is fascinating to me because there’s so much of it that I’ve never really thought about, which means there may be errors.

Why are there any constraints?

Because terminal emulation isn’t skin deep; it’s the outcome of continuous evolution from the 1960s and ‘70s when hardware terminals and computers communicated by a limited set of character codes.

In 1971, it was possible to type commands like ls, cat, chmod, and rm on a Teletype Model 33 to execute them on a DEC PDP-7 minicomputer running the first edition of Unix.

Somehow, after decades of nerdery and market forces, the fingerprints of that Teletype remain all over the terminal emulator you use to SSH into a Linux VM and run ls, cat, chmod, and rm.

And, somehow, Unix paradigms underlie most of our OSes, including MacOS, where I’m running my program.

Unix’s TTY subsystem let programs trade ASCII bytestreams with a Teletype or video terminal. The kernel would interface with your user-space program (the sh command interpreter; the ed editor) at one “end”, and at the other end it would drive hardware to shuttle ASCII to and from serial current or voltage signals.

4.2BSD (a Unixy OS) introduced the pseudoterminal (PTY) driver in 1983 to let user-space programs interface with both ends of the TTY subsystem. Now you could replace your hardware terminal with a software terminal emulator, running on the same computer as your shell.

And that’s basically what happens under MacOS in 2025. My terminal emulator and my shell (or my TUI blogging program) communicate by passing bytes back and forth through the kernel TTY subsystem, via PTY pseudo-devices.

As a regular GUI program, the emulator can decide which bytes, if any, to push when it receives an input event from the OS. By default, it’ll map key events the way that my shell, SSH, and that remote Linux VM expect, and that won’t match my GUI-centric keybinding preferences.

My TUI program squats in the terminal emulator because I like a text-based interface. Because it’ll reconstitute my little bit of logic into a whole lightweight UI, no platform-specific development required. The fastidiously tended compatibility is something I sometimes have to work around.

Ctrl-Enter doesn’t work

The 7-bit ASCII character set took most of the 1960s to stabilise. The initial standard, ASA X3.4-1963, had some unassigned codes. By 1968, they’d given in and used most of them for lowercase letters.

Of the 128 ASCII codes, 95 represent printable, or “graphic”, characters—“text”. The other 33 are control codes for stuff like coordinating communication and manoeuvring print heads and paper.

The ASCII table was painstakingly arranged so that you could get to 32 of the control codes by zeroing the 6th and 7th bits on 32 of the printable characters. Which is what the CTRL modifier key did on the Teletype 33, and on video terminals like DEC’s VT series (starting with the 1970 VT05) and the 1976 Lear Siegler ADM-3A.

For completeness: the 33rd control code, DEL, lives in the last slot on the 7-bit ASCII chart, which is 1111111—good for deleting a character on paper tape by going back to its position and punching all the holes.

Back to Ctrl-Enter.

There were a few control codes you’d commonly want to send from the terminal, and it became normal on video terminals to have keys for them: HT (horizontal tab), BS (backspace), LF (line feed), DEL (delete), and CR (carriage return), emitted by the RETURN or ENTER key (or both, as the case may be).

So ENTER is already a control code; CTRL-ENTER would be like CTRL-CTRL-M, which is not, historically, a thing. If you mask the top two bits of CR you get CR again, which is how Ctrl-Enter acts in iTerm2 by default.

Again, in 2025 we’re allowed way more key events than just ASCII codes, and I can get around this by setting a custom keybinding on an iTerm2 profile; I checked. I’m still loath to do it.

Cmd-Enter doesn’t work either

Or, I should say: Cmd-Return doesn’t work either.

In principle it could, since it generates a key event and the command key on my Apple computer isn’t mentioned in any ANSI standard from 45 years ago.

But equally, combinations that aren’t spoken for by any ASCII code are in danger of being claimed by MacOS and terminal emulator programs.

Cmd-Return‘s default behaviour in both GhosTTY and iTerm2 is to toggle full-screen mode, so I’d have to change that setting (if possible) and then add the custom keybinding.

I admitted defeat and set Ctrl-S as my shortcut for submitting changes to a text entry.

Arrow keys work fine, thanks to escape sequences

All the ASCII control codes were used up by the time video terminals needed a way to move a cursor around on a screen.

The VT05 “solved” this by just commandeering some control codes for arrow keys.

If your terminal and your program agreed, this worked. These codes weren’t otherwise relevant to the VT05.

I had a quick look on the webs, and I’m not sure what this was actually good for (aside from BACKSPACE). It seems there wasn’t a lot of software that used this kind of cursor movement in the very early 1970s, and you’d have to write your software specifically to understand the control codes in this custom way.

You couldn’t really standardise on this approach, because other devices still existed that did use the canonical meanings.

But ESC, sitting in one of those 128 precious ASCII slots, offers a more elegant option: it’s a prefix affecting the interpretation of a limited number of contiguously following characters. That is, it starts an escape sequence. Escape sequences vastly increase the number of possible signals by letting us bundle multiple ASCII codes together.

There was a standard for the purpose and general form of escape sequences in 1971, but which sequence of codes to use for what was still freeform.

The 1975 VT52 used ESC A to move up one line; ESC C to move right one position, and so on.

A standard for specific escape sequences appeared in 1976: ECMA-48; followed in 1979 by a second edition and the nearly identical ANSI X3.64.

It seems the VT52 guessed wrong.

In 1978, the DEC VT100 was released: the first terminal compatible with the upcoming ANSI standard. Its arrow keys emitted standard escape codes:

ESC [ is the Control Sequence Introducer for 7-bit ASCII.

If I do cat -v in a terminal emulator today and press arrow keys, I get the same things, albeit in a different notation: ^[[A, ^[[B, ^[[C, ^[[D.

^[ for Ctrl-[ reflects that ESC is itself a control code.

I can rebind Ctrl-X/C/V. Why?

These are all control codes with canonical meanings: CTRL-X is CAN (cancel), CTRL-C is ETX (end of text), and CTRL-V is SYN (synchronous idle). I want to use them for “cut”, “copy”, and “paste”—and this works fine.

We told video terminals they couldn’t repurpose control codes, but this is just a contract between a single program and its users; not nearly as big a deal, as long as the connected device doesn’t need these control codes for something.

The device is a terminal emulator, and it doesn’t absolutely need any of them.

There is another slightly more modern question, though: doesn’t Ctrl-C cause a SIGINT on Unix-like systems?

When I talked about the kernel TTY subsystem earlier, I didn’t mention the line discipline layer. The line discipline used to be really handy for buffering your command until you hit ENTER, and providing basic editing to fix typos.

At some point the line discipline started taking Ctrl-C to mean “send a SIGINT“.

That’s its behaviour in its default mode, called the canonical or cooked mode. But the line discipline also has a raw mode. In raw mode it passes the ASCII/UTF-8 codes along to the program, and the program decides whether Ctrl-C means it should exit, or copy selected characters, or something else. A user-space program can specify which mode to use.

In other words, it’s condoned for a program to repurpose control codes away from the standards, so that’s what I do.

What about Cmd-X/C/V?

I already know I can’t rely on Cmd-<anything> in a CLI or TUI program, and I don’t generally want to use Ctrl for some things and Cmd for others. But I might make an exception for clipboard operations. I often want to copy and paste things between applications, so I’m switching between shortcuts there for what my muscles think is the same thing.

I notice that both iTerm2 and GhosTTY use Cmd-C and Cmd-V to copy and paste out of the box. Cmd-X seems unclaimed. This may work!

As far as my specific app is concerned, I have to tease out where I’m using tui-textarea’s internal yank buffer vs. Arboard for interacting with the system clipboard (vibe coding), but the Cmd shortcuts may actually be fine.

Option-Left/Right Arrow to jump by a word

Option-Left/Right Arrow to jump the cursor by one word has been a thing on Macs since MacWrite (1985).

My stubbornness about changing terminal profiles has hit a snag: my emulators don’t have matching defaults.

In both Terminal.app and GhosTTY, Option-Left Arrow / Option-Right Arrow send ^[b and ^[f: the Emacs shortcuts ESC b and ESC f in disguise. Zsh and tui-textarea both happily agree that these are for moving back or forward by one word.

iTerm2 sends xterm-style escape sequences instead.

ANSI X3.64 and friends don’t know about the Alt modifier, which is what iTerm2 is identifying the Option key as. xterm added support for modifier-key parameters in “function-key” escape sequences in 1999, so that Option-Right Arrow can emit ^[[1;3C, a modified CURSOR FORWARD where the parameter 3 flags that the Alt key is depressed.

Sounds reasonable! xterm established a lot of de facto standards in terminal-emulator land, including escape sequences for 256 text colours, and mouse events.

But empirically, no program I’ve met seems to be interpreting ^[[1;3C as “hop by a word” or anything else.

My easy way out is to go into iTerm2’s Settings -> Keys -> Key Bindings -> Presets and choose “Natural Text Editing” or “Terminal.app Compatibility”.

This made line editing in my shell and Claude Code a lot nicer too, so I could argue that I’m not doing anything to my terminal profile specifically for one program.

Just to check that I’m not bending over too far backward to avoid the happy path here, let’s check out oldey-timey terminalish ways to do jumping by a word.

There’s the Vim way: get into (checks notes) Normal mode and hit b or w (or e). I’m just not ready to embrace modal editing.

There’s the Emacs way: M-b or M-f (where M is Meta, which can map to the Alt modifier or Esc prefix). Esc b and Esc f work in just this way on all the terminals I tried!

It’s a bit inconvenient to hit this combination repeatedly, though, and while Option-Left Arrow / Option-Right Arrow are available to my program, MacOS snags a lot of Option combinations, including Option-b and Option-f, to print special characters.

I haven’t dug around to find out how Emacs users on Mac deal with this, but I’m reassured that “switch to Emacs keybindings” is not a superior solution to slapping a popular preset on my iTerm2 profile.

Cmd-Left/Right Arrow for Home and End

In other apps on my Mac I’m seeing Home and End functionality provided by either fn-Left/Right Arrow or Cmd-Left/Right Arrow (or both). The Cmd-<arrow> shortcut again dates back to MacWrite of 40 years ago.

iTerm2 claims Cmd-Left/Right Arrow for switching tabs. But with the “Natural Text Editing” keybinding preset and only one iTerm2 tab, it’ll emit the same as Terminal.app and GhosTTY: ^A and ^E. More Emacs conventions in the shell! And they’re the right ones for Home and End.

Funny story, though, iTerm settings aside: in my application code, I treat Ctrl-A as “select all text in the editor”.

fn-Left/Right Arrow for Home and End

fn-Left Arrow and fn-Right Arrow in both GhosTTY and iTerm2 give ^[[H and ^[[F, escape sequences now understood reliably as “go to the start of the line” and “go to the end of the line”.

Those aren’t the ANSI x3.64 / ECMA-48 meanings of these escape sequences; the convention seems to have grown out of DEC’s 1993 VT510 terminal having a mode to emulate a console for SCO Unix.

The xterm changelog has an entry for a patch in 2000 with the text “add logic to implement SCO function-keys.”

Terminal.app doesn’t pass anything along that I can see in cat -v, and the effect in zsh or bash looks like a true home and end here; but within my TUI app, for whatever reason either (app code or tui-textarea) is giving my desired behaviour.

So I’m treating this one as reliable.

Roundup

I know. This is a long post. Here’s a barebones look at the various key combos and their practical quirks:

Ctrl-Enter

Enter is, itself, an ASCII control code, so there’s no standardised way to handle Ctrl-Enter (Ctrl-Ctrl-M). Might get it to work with terminal emulator options.

I substituted Ctrl-S.

Cmd-Enter

Inconveniently claimed for toggling fullscreen mode in iTerm2 and GhosTTY.

Ctrl-X/C/V

OK! With the TTY line discipline in raw mode, ASCII control codes are passed in and the program can interpret them as needed.

Cmd-X/C/V

May be fine for cut/copy/paste! Cmd-C and Cmd-V copy and paste out of the box in iTerm2 and GhosTTY.

My particular app has to decide how it’s interacting with the system clipboard and tui-textarea’s internal buffer.

Option-Left Arrow/Option-Right Arrow

These do what I expect—jump by one word—by default in Terminal.app and GhosTTY.

iTerm2 needs custom keybindings to enable this.

Cmd-Left Arrow/Cmd-Right Arrow

In Terminal.app and GhosTTY: ^A and ^E. Emacs keybindings for “go to the start of the line” and “go to the end of the line”; understood as such by zsh and tui-textarea.

iTerm2 uses these to switch tabs by default.

Bigger conundrum: a clash in my app, which binds Ctrl-A to “select all text in my editor”.

fn-Left/Right Arrow

These do what I expect in my TUI editor.

In iTerm2 and GhosTTY: ^[[H and ^[[F. Escape sequences understood by zsh and tui-textarea as “go to the start of the line” and “go to the end of the line”.

Terminal.app is doing something different, but in my app it’s working as desired.

I think I haven’t discovered maximum copacetic…ity…in keybindings for editing text in a TUI on Mac. That being said, my app is now reasonably intuitive, and I use it.

There’s one thing, though. It hurts my little finger.

All shortcuts with the control key are bad on Mac

Apple likes Cmd for most of the things I’d use a shortcut for in an editor, so they’ve happily squished Ctrl over by one spot, where no finger can easily reach it, to fit a fn key at the start of the row. And because Cmd isn’t a 1970s terminal modifier, the OS and the terminal emulator frequently claim it for their own shortcuts.

You know when you go against the flow and it kicks your ass repeatedly onto the rocky riverbed until you start to understand the attraction of Vim?

Yeah.

Writing is hard. I usually overthink it.

Late one night, after mindlessly feeding the highlights of a day hike into a Slack thread, I had a punch-drunk inspiration: writing under similar constraints and conveniences, could I barf out a blog post almost as easily?

Rather than compose my next article in Slack DMs with myself, I went for the second-most-practical proof of principle: creating a new tiny writing app that emulates the microblogging experience.

I already had a gaggle of unfinished projects. But I was feeling good about Claude Code, and easily sniped by what looked like a quick vibe-coding side quest. So off I went!

Initial spec

I had a pretty clear set of basic requirements, as a user:

• A basic editor for composing short entries. Entries should drop into a “thread” that I can spit out into a single Markdown file when I’m ready to call it a draft.
• A hard character limit per entry, complete with colour-changing character counter to ratchet up anxiety in inverse proportion to conciseness.
• Some stupid-simple way to add a single image to an entry. Ideally: paste from the OS clipboard. With LLM help, it’ll be easy to add resizing and conversion to WebP, or whatever makes it easier to get from train-of-thought to published on my blog.

Scheming

For a break from the browser, and to satisfy my craving for novelty, I decided on a text-based user interface (TUI).

A quick web search turned up strong TUI libraries for Go, Python, and Rust (Bubble Tea, Textual, and Ratatui, for respective example).

The novelty factor tipped the balance to Rust. Bonus: that means this can be a Rust client and Elixir/Phoenix storage API backed by SQLite, a Bizarro twin for the Phoenix-app-with-state-in-a-Rust-program that I bumped to the back burner to work on this.

For the record: Claude assured me that this was a brilliant design.

Fast-forward

I started by working out, with Claude, design docs for the TUI and the Elixir storage app.

From there I tried to let Claude generate the code, with appropriate interactive planning and feedback. Vibing was particularly easy at first when there was nothing but a green field, Claude Code, and a language I couldn’t so much as read a function signature in.

I don’t have anything new to say about the process. Any specific observations will be stale by…well, by now, probably. So let’s skip forward.

So, it worked

A few days later, there was a working (if buggy) blogging application that compromises very little on my original spec. It’s nice to use!

Ratatui, tui-textarea, Ratatui-image, Arboard, and Textwrap do most of the lifting.

The main twist was that tui-textarea doesn’t do word wrap, and it was easier to fork it to use the Textwrap library than to do text wrapping on top of it. I’ll put up some notes on that part later.

After the vibes fade away

Was “vibe coding” a smart way to go about this?

(Trick question.)

Smart? No. The land of Rust and Ratatui has a really good map! Ratatui and friends are well documented, with abundant examples to crib from. But I’m a tourist, and Claude can’t think about the whole map at once.

If I wanted to do this effectively, and I really wanted to use Rust, I should have used the map myself, and let LLMs accelerate my learning.

But what did I really want?

I wanted the app. I wanted to touch Rust (but not too much).

And…I wanted to see what Claude could do. I wanted to test the machine. Which was particularly easy when there was nothing but a green field, Claude Code, and a language I couldn’t so much as read a function signature in.

I really did get the best one could hope for:

• A usable app, without understanding everything that was going into it
• A candy-coated dose of Rust
• An imaginary trophy for me and Claude and all the libraries I used. We did it, yay.

Here’s a side effect: now there’s this neat progam full of bugs and antipatterns that I have only the merest inkling about, and I couldn’t in good conscience suggest anyone use it or fork it.

Worse, I forked one of my dependencies to overcome the longest-standing GitHub issue on that project, and haven’t got anything good to offer back upstream. Who knows what nonsense is in there, and which other features I broke? Not me.

What about the Elixir backing app?

Looks like I vibed that one for real. Claude is so comfy with Phoenix and Ecto that I’ve hardly had to look at the storage app. No human brain cell has been bothered about a SQLite schema here.

But can you barf out a blog post now?

Of course not. Writing is hard. This article alone took days of vibe coding.

Are my constraints and conveniences good for anything? So far, I’m encouraged. I used the new app to bootstrap this post. It helps me keep track of the shape of a thread without showing it all to me at once. I can start new entries to add words, but the per-entry character limit actively reminds me to encapsulate my point.

It can still be tempting to organise a single thread into sections and move entries between them, which is a danger sign.

The convenience of pasting images is gratifying, but I haven’t really had occasion to put it through its paces, and there’s still a bug or two around removing them. I still think it’ll be cool.

If I use this to write another post after this one, I’ll say I was on to something.

Appendix: A smattering of Summer 2025 souvenirs (coding-with-LLMs-wise)

I’d now trust Claude.ai or Claude Code to generate a one-off API client in a language I can read (thus test and debug), without the buffer of getting it to write a program to do the conversion.

What I wasn’t appreciating in March of this year is that these interfaces are not simple wrappers for an LLM—while I’m not sure if Claude.ai was unequivocally agentic at that point, it is now.

Miscellany:

• Lazy cheat code: ask “why.” When debugging, Claude sometimes gets fixated on the first possibility it sees from wherever its attention is, and goes ahead with useless changes. When Claude seems to be having a bad day, asking it to explain why the program is behaving like that, before asking it to solve anything, can help keep it out of that rut. I haven’t added this to my CLAUDE.md yet, but I probably should.

• Alternate lazy cheat for bad days: ask “how does the module handle $WHATEVER“ when you know it’s doing $WHATEVER wrong, and sometimes it’ll figure it out without you having to complain about symptoms.

• Claude likes to add diagnostic logs. I’m glad it doesn’t spontaneously remove logging, I guess, but I wonder if noisy logging makes a material difference to token usage or can pollute the context meaningfully. So I try to keep those from getting too wild. Similar for compilation warnings, which I otherwise have a tendency to let build up.

You push the button. It makes an API call. A new virtual machine pops up on some Fly.io metal in the data centre nearest to you.

Once the new VM is up, the LiveView redirects your browser to it. Your very own Fly Machine serves you some content, then shuts itself down and gets destroyed forever.

The whole schtick collapses if I don’t ensure any button-pusher can interact only with the Machine they launched.

This looks like a type of session affinity, or sticky sessions, problem.

The key to sticky sessions within a Fly app is fly-replay

Backing up: the Fly.io load balancer is a Rust program called fly-proxy. When you visit an app’s public URL, fly-proxy relays your request from the edge to a Machine with a service configured on the right port and the concurrency headroom to fulfil it. In the simplest case, that’s the closest such Machine in the app. Machine state and autostart config also factor in, when they’re relevant.

There’s no way to tell fly-proxy beforehand that it should deliver an HTTP request to Machine B with a service exposed on port 80, and not the nearer Machine A in the same app with a service on port 80. But it does provide for application code to examine the request and respond with a fly-replay header, telling it to deliver the request again; to a different app, to a specific region, or to not-this-Machine, and fly-proxy applies its load-balancing logic within those constraints. Or we can pin the replay down to a specific Machine.

This makes the proxy sort-of programmable without actually making it programmable.

An app per customer may be better than fly-replay

If the Closest Machine is frequently the Wrong Machine, and you’re constantly replaying requests, it may be worth putting each distinct Machine into its own Fly app with its own .fly.dev URL.

If you’re isolating workloads/users on their own VMs for security reasons, putting them into their own apps too is even better, because you can wall apps off into separate custom IPv6 private networks.

In my case, though, fly-replay is just the ticket. fly-proxy has a high chance of hitting the correct Machine on the first try. The whole visitor experience is short and I don’t want to bog it down with more API operations and waiting for DNS. (And while I could generate disposable app names with a vanishing likelihood of collision, burning globally unique app names just feels stinky.)

So from here I just have to implement the logic in my LiveView app to issue a fly-replay for every request that needs one. It’s not quite straightforward.

Peter Ullrich solved this exact thing already

As it happens, Peter Ullrich wrote an article on using fly-replay for sticky sessions on Fly.io with a Phoenix/LiveView application. It’s pretty neat, and he explains both the why and the how; I’ll recap what stood out to me, but you should read his version for the good stuff.

Ullrich wrote a module plug that checks each incoming request for a query parameter, or failing that, a cookie, matching the ID of the current Machine. If the query parameter matches, it puts that into a session cookie so that it’s passed in with all subsequent requests from that client (until that cookie gets changed). If there’s a parameter or a cookie, but it doesn’t match, the plug responds with a fly-replay header and a redirect status (307).

The tricky part in a LiveView application is getting every request to go through that plug. WebSocket connection requests don’t go through the router, nor through the regular plugs in the endpoint, so just adding a plug in either of those modules doesn’t cut it.

To ensure everything, everything, goes through a particular plug, you can override the definition of the endpoint’s Plug.call/2 callback to run through that plug first.

The plug either issues a fly-replay or dumps the conn into the front end of the stock endpoint to be handled in the usual way.

Again, I didn’t figure this out myself; go read the original post.

I tried to squirm out of it

When I first read Ullrich’s article, I refused to believe that my use case wasn’t simpler.

I thought I should be able to start with something like a vanilla LiveView authentication/authorization setup and simplify that down to some path-based logic with a live_session and an on_mount hook to gate access to the LiveView and fly-replay any requests for a path indicating a different Machine.

This almost worked!

Just kidding; of course it didn’t.

An on_mount hook can’t manipulate connections the way a plug can, and it can’t send a fly-replay header. It can do a redirect to a route in the router module, though.

For a moment I thought it would be clever to get the on_mount callback to check the path against the FLY_MACHINE_ID environment variable (this part is fine) and if needed, cycle the connection back to the router and through a plug, which can set headers and respond.

If it’s not obvious, what this accomplishes, when you hit the wrong Machine, is an infinite loop of fly-replay “redirects”.

Getting a LiveView rendered and connected involves two requests, running its mount function twice. The first on_mount catches a request meant for another Machine, and replays to that Machine. But the WebSocket upgrade needs one more HTTP request.

If fly-proxy thought the wrong Machine was a good choice the first time, it probably thinks the same thing this time too, and sends the upgrade request there, where the on_mount callback sends it back to the router on the right Machine, where we start all over again.

Tweaks

I used Ullrich’s solution wholesale, with two adjustments to the plug:

• I added a condition to let requests to /health pass; localhost needs to reach it. A plug in the router pipeline blocks non-localhost connections.
• Instead of passing all connections that don’t match one of the conditions, I block them. There’s no resource that you should be looking for on this Machine if it’s not the Machine you created.

My adaptation is in this gist.

Push the button at https://where.fly.dev. See if it works for you.

I was exploring the options for structuring such a module, more out of curiosity than any urgent need, and asked Claude on a whim if it could produce functions for all the endpoints. It did. Forty-odd functions, complete with typespecs and detailed docstrings. It hit its message-length limit and I had to ask it to carry on in a new message. It picked up and finished without incident.

The output looks solid. It looks consistent. Claude doesn’t seem to have so much as supplemented the request parameters with a popular one from some other API.

I was really impressed that Claude sustained such an uncanny impersonation of a dumb but reliable Python script for that long—despite the Vaudeville hook dragging it offstage partway through the act.

Also: this is terrible. Now I can sneeze and a nondeterministic black box barfs out a thousand lines of independent functions and docs oozing respectability and discipline? I’m going to be so tempted to trust this!

If I’d planned an exhaustive client for this API, I’d have asked my machine buddy for help writing a boring Python script (or Mix task) to convert the OpenAPI spec directly, reproducibly, and with a lot less electricity.

I should note that the docstrings I ended up with are richer than what’s in the spec. Some of the example material identifiably originated in Fly.io developer docs. So, there’s that.

Now that I have all that code

This may be the first time an LLM tool has bitten off more than I can chew without losing its own bearings. The vibes were practically telepathic.

I don’t approve of using an LLM for tasks that need repeatability and can be done in seconds on a CPU. I can’t be sure there are no surprises until I’ve checked every function, and if I ask again, there’s no guarantee any deficiencies will be the same ones.

But here’s the module, fully formed. What to do?

I do want to talk to a subset of this API from my Elixir apps, and this gives me a starting point for incorporating the schema validation I’ve been playing with.

I could “ship” it and fix it if I ever find out it’s broken—the stakes couldn’t be lower. But all those untried functions, all that unexamined documentation in my module—it was stressing me out.

I took the easy way out: the reusable moving parts and a couple endpoint functions go into a module and the rest get banished into a slush file outside my project. I don’t have to look at them, but I can grab them as needed, if they ever are. Instant relief.

More things I think about LLMs, March 2025 edition

As always, the quality of the output of an LLM chat tool is entangled with the quality of my side of the conversation. It’s all moving targets and YMMV.

• The Elixir ecosystem abounds with high-signal, well-structured documentation. Claude’s grounding in Elixir has improved immensely in the past year. In my opinion, between the two we’ve hit a tipping point for a coding-while-learning momentum boost.
• Once the shiny, clean module appeared, I immediately got Claude to start messing it up by asking it a question about Req options. I think questions like “do I have to do X in order for Y to happen?” can be leading if there’s a weakness around Y in the model or the context. Claude is a bit too much of a people pleaser, and my lightweight attempts to counter that with project instructions and preferences haven’t cured that.
• It has happened, though, with both Claude and ChatGPT, that I’ve proposed one thing and the tool has correctly advised me to use a different approach.
• I do still wade into boggy ground with Claude 3.7, ask it to bite off more than it can chew and end up in a cycle of ineffectual “corrections”, or ask it something it doesn’t have a good grounding in and end up trying to find docs for nonexistent functions to help me implement some antipattern.
• At the end of February, I was surprised when Claude 3.5 Sonnet and I managed a very similar failure of attention navigating a bureaucracy of pattern-matching function heads. We both missed that the salient clause returned a value instead of handing it off to the next one in line. For all I know, this wouldn’t happen with 3.7. Claude can be so ultra-agreeable that I almost think I planted that blind spot by telling it what I couldn’t find.

One day, it started to bug me unreasonably much that I didn’t really understand how this command causes that to happen. Perhaps culpable: a touch of delirium, downstream of the flu.

There were a lot of reasons for my mystification (i.e. a lot of basic things I hadn’t thought much about before), so below you’ll find, if you want to, ~2700 words about some things that happen and how. I don’t expect even one whole person to read the entirety. It’s not that kind of blog post.

There may be inaccuracies.

Interacting scripts

Before getting fancy, I want to know what my basic everyday Elixir commands do.

The elixir, iex, and mix commands are all scripts.

elixir, the script

The elixir shell script constructs a string of arguments based on the arguments you supply, plus some information about your Elixir installation, and tacks that onto an erl command.

The elixir script ends with

if [ -n "$ELIXIR_CLI_DRY_RUN" ]; then echo "$@" else exec "$@" fi

It’s assembled the erl invocation, with all its arguments, into "$@", and all that’s left is to execute that command.

But look! By setting the ELIXIR_CLI_DRY_RUN env var, you can view the whole assembly instead of running it! I didn’t know that; I’m going to use it in a minute.

mix, the script

The mix script is exactly this:

#!/usr/bin/env elixir Mix.CLI.main()

This is an Elixir script! The shebang makes mix a (much) shorter way to write (in my case, with runtime installations managed by asdf):

elixir /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/mix

So mix invokes elixir and we end up, again, with an erl command.

This felt circular to me, because the elixir script doesn’t do anything with the contents of the mix script. But that’s just the way it works; rest assured that something eventually reads the file. We’ll see what, later.

iex, the script

The iex shell script ends with

exec "$SCRIPT_PATH"/elixir --no-halt --erl "-user elixir" +iex "$@"

Which is to say: it calls the elixir command with a specific set of arguments, followed by any arguments it was called with ("$@").

Another erl command.

elixir --help has entries for --no-halt (“[do] not halt the Erlang VM after execution”) and --erl (“[s]witches to be passed down to Erlang”). That +iex option isn’t in the help, but the elixir script does notice it, and omit -s elixir start_cli from its erl arguments.

But we don’t have to work out the final set of arguments by reading the scripts. We can just print them out by setting the ELIXIR_CLI_DRY_RUN environment variable.

Pause to appreciate coolness

My Erlang/OTP installation doesn’t know anything about my Elixir installation.

The arguments in these human-readable erl commands will have to tell it, or point it at, everything it needs to know in order to do whatever Elixir-land thing I wanted. This is not trivial or banal. It is very cool.

How to read erl arguments

So: elixir runs erl with a collection of arguments. And iex and mix both go through elixir. That is, each of these commands generates an erl command.

The erl docs do a pretty good job of explaining the different kinds of argument that erl accepts, and what it does with each kind.

It can be a bit hairy to categorise them in practice. The following paraphrases info that’s in the docs, with some emphasis on “subtleties” that I missed in my first reading, and that would have saved me some casting about in source code.

• Emulator flags are for VM settings. Emulator flags start with a plus sign, except when they start with a hyphen like all the other flags. We won’t run into any emulator flags in this exercise.

• Many, but not all, other defined flags are marked as init flags: flags that are interpreted and used by Erlang’s init and not stored for later use.

• -- and -extra are init flags that indicate that what follows is one or more plain_arguments: values that the init stores in a list that you can get later with init:get_plain_arguments/0.

• You, the user, can create user flags to suit your needs. The init stores user flags as key-value pairs, where the flag becomes an atom key for a value that’s a list of the items that follow (up until the next flag). To get this list, use init:get_arguments/0. If an argument starts with a hyphen, and it’s not an init flag, an emulator flag or a plain argument, it’s a user flag.

• Some code that comes with the Erlang distribution looks for arguments stored with specific user flags. Some of these user flags are documented alongside the init flags.

• Case in point: there’s an important special-case user flag documented as -Application Par Val; when/if the OTP application named Application is started, Application‘s Par configuration option is set to Val. We see this shape of user flag in the elixir command. This one tripped me up; I could see the apparent intent but missed it in the docs.

elixir, mix, iex: the erl angle

Armed with the above clues to how erl statements work, let’s look at minimal examples of each of our Elixir commands.

elixir

If I don’t put something after elixir, it just prints its help at me, so I’ll tell it to print hi instead.

ELIXIR_CLI_DRY_RUN=1 elixir -e 'IO.puts("hi")'

Here’s what that spits out:

erl -noshell \ -elixir_root /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib \ -pa /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib/elixir/ebin \ -elixir ansi_enabled true \ -s elixir start_cli \ -extra -e IO.puts("hi")

That’s an eyeful, but it’s mostly because paths are long and messy. Flag by flag:

-noshell

Skips starting the Erlang shell. We want this init flag if we’re working in Elixir and not Erlang. Either we don’t want a shell, or we want IEx.

-elixir_root /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib

-elixir_root is a user flag. We’re telling the init to store the path to our installed Elixir lib dir under the key :elixir_root.

Spoiler: The start/2 function of the elixir module uses this stored value to set paths to ebin directories, where .beam files are.

-pa /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib/elixir/ebin

-pa is an init flag. Adds the path to the Elixir .beam files to Erlang’s code path.

-elixir ansi_enabled true

This is that special -<application> <parameter> <value> user-flag format. Sets :ansi_enabled to true in the :elixir OTP application’s config when it starts.

-s elixir start_cli

-s is another init flag. Run function start_cli/0 of the elixir module.

This function starts the elixir OTP application (and starts the logger application) and finally passes our list of stored plain arguments to Elixir.Kernel.CLI.main/1, “the API invoked by [the] Elixir boot process” with this line:

 'Elixir.Kernel.CLI':main(init:get_plain_arguments()).

(Good thing we told Erlang where to find Elixir with the -pa flag.)

-extra -e IO.puts("hi")

Each thing after -extra in an erl expression is a plain argument, so -e and 'IO.puts("hi")' are stored by the init as such.

My 'IO.puts("hi")' came out without its single quotes. I can roll with that; I had to type it in a way that would be parsed unambiguously in the shell, and now it’s in the shape it has to be in for the next thing to parse.

On that topic, we can quickly check how the init stores plain arguments:

erl -extra -e 'IO.puts("hi")' 

Erlang/OTP 27 [erts-15.2.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit] Eshell V15.2.1 (press Ctrl+G to abort, type help(). for help) 1> init:get_plain_arguments(). ["-e","IO.puts(\"hi\")"]

(Plain arguments keep their order in the list, which is important when it comes to parsing and using them.)

Recapping what’s explicit in the erl expression: typing elixir -e 'IO.puts("hi")' into my system shell starts an Erlang VM (BEAM) instance in which the Erlang init process:

• doesn’t start an Erlang shell
• prepares the Erlang runtime environment, including:
  • setting the path to Elixir .beam files
  • storing some arguments, which in this case are for setting up the elixir OTP application
  • storing some plain_arguments that correspond to the arguments I passed to the elixir command
• invokes the start_cli/0 function of the elixir module

That’s the end of what we can read on the face of the erl expression.

Then, elixir:start_cli/0 configures and starts the elixir and logger OTP applications, yoinks the list of plain arguments from the Erlang init, and passes that to our first Elixir function, Elixir.Kernel.CLI.main/1.

So I want to know what Elixir does with these arguments.

So that’s what “the API invoked by [the] Elixir boot process” meant. The options you pass to the elixir CLI command, telling it what you want “Elixir” to do, go to the Kernel.CLI Elixir module, which makes it happen.

My request to evaluate the Elixir syntax IO.puts("hi") is executed. The VM prints hi to stdout. I see it in my terminal. Elixir has done what I asked and halts the system.

mix

ELIXIR_CLI_DRY_RUN=1 mix 

erl -noshell \ -elixir_root /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib \ -pa /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib/elixir/ebin \ -elixir ansi_enabled true \ -s elixir start_cli \ -extra /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/mix

This is identical to the elixir -e 'IO.puts("hi")' example, but with different plain arguments after the -extra flag.

Elixir.Kernel.CLI will recognise the path to the mix script as the path to a file, read it, and call the function inside: Mix.CLI.main().

iex

ELIXIR_CLI_DRY_RUN=1 iex 

erl -noshell \ -elixir_root /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib \ -pa /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib/elixir/ebin \ -elixir ansi_enabled true \ -user elixir \ -extra --no-halt +iex

In the not-IEx commands, -s elixir start_cli started Elixir, but the -s flag doesn’t show up here.

-user elixir

ELUSIVE. But important! -user is a user flag, and isn’t in the docs, but it’s a special one; the Erlang user_sup module looks in the init arguments for the key user.

The user is the process that deals with the Erlang VM’s I/O; to interact with IEx, we need input and output to go through it.

The best resource I’ve found for this Erlang user concept: REPL? A bit more (and less) than that by Fred Hebert. (“If you want to change where the IO takes place, change the user process, and everything gets redirected.”)

It looks like passing -user elixir means user_sup:start_user/3 calls apply(elixir, start, []).

In turn, elixir:start/0 passes user_drv:start/2 iex:shell/0 for its initial_shell argument and iex:shell/0, finally, calls elixir:start_cli/0, which feeds our plain arguments to Kernel.CLI to be acted on.

-extra --no-halt +iex

The plain arguments are --no-halt and +iex.

We can find their significance in the Elixir Kernel.CLI source:

• --no-halt results in a no_halt: true entry in the config map, which results in the decision not to emit System.halt(status) after executing commands.
• +iex sets mode: :iex in config; this seems to be mainly used to decide how to deal with other flags like -v or --version, and --dbg.

Differences from the elixir command:

• start the iex application after elixir
• send all VM I/O through iex
• don’t halt the system once Kernel.CLI has processed the plain arguments and taken any actions they ask for

As we know, the end result is that I’m dropped into an IEx shell once all that’s done, and I can ask IEx to run moar Elixir.

What’s running in the VM?

Bare minimum, that is.

Here are the started applications in my bare IEX shell.

iex -e "IO.inspect(Application.started_applications)"

Erlang/OTP 27 [erts-15.2.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit] [ {:logger, ~c"logger", ~c"1.17.3"}, {:iex, ~c"iex", ~c"1.17.3"}, {:elixir, ~c"elixir", ~c"1.17.3"}, {:compiler, ~c"ERTS CXC 138 10", ~c"8.5.4"}, {:stdlib, ~c"ERTS CXC 138 10", ~c"6.2"}, {:kernel, ~c"ERTS CXC 138 10", ~c"10.2.1"} ] Interactive Elixir (1.17.3) - press Ctrl+C to exit (type h() ENTER for help) iex(1)> 

I haven’t run into the place that starts the compiler application, but I can wave my hands and say it makes sense that we’d need it; I might ask the VM to run something that hasn’t been compiled yet.

I can compare the applications started in a VM that I spun up to run an Elixir function to list the applications started in it:

elixir -e "IO.inspect(Application.started_applications)"

[ {:logger, ~c"logger", ~c"1.17.3"}, {:elixir, ~c"elixir", ~c"1.17.3"}, {:compiler, ~c"ERTS CXC 138 10", ~c"8.5.4"}, {:stdlib, ~c"ERTS CXC 138 10", ~c"6.2"}, {:kernel, ~c"ERTS CXC 138 10", ~c"10.2"} ]

For fun, here’s one just for erl. Just kernel and stdlib in this VM:

erl -eval 'io:format("~p~n", [application:which_applications()]).'

Erlang/OTP 27 [erts-15.2.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit] [{stdlib,"ERTS CXC 138 10","6.2"},{kernel,"ERTS CXC 138 10","10.2.1"}] Eshell V15.2.1 (press Ctrl+G to abort, type help(). for help) 1> 

Putting the pieces together

When we start the BEAM with an iex command, all the VM’s I/O goes through IEx, and IEx implements the interactivity, including taking care of interpretation of Elixir expressions, or compilation of code, as necessary.

All that’s left is to add -S mix phx.server:

ELIXIR_CLI_DRY_RUN=1 iex -S mix phx.server 

erl -noshell \ -elixir_root /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib \ -pa /Users/chris/.asdf/installs/elixir/1.17.3-otp-27/bin/../lib/elixir/ebin \ -elixir ansi_enabled true \ -user elixir \ -extra --no-halt +iex -S mix phx.server

No surprises. Just like iex, but with an additional -S mix phx.server after -extra.

Check on the plain arguments:

iex(1)> :init.get_plain_arguments() [~c"--no-halt", ~c"+iex", ~c"-S", ~c"mix", ~c"phx.server"]

How does Mix get its arguments?

We already talked about how the ["-S", "mix"] part of the arguments list means Elixir.Kernel.CLI will execute the mix script.

And we kinda know that Mix has to see the "phx.server" argument, since that’s the Mix Task we’re trying to run. Let’s just put a tidy bow on how that happens:

As soon as Kernel.CLI.parse_argv/2 matches "-S", it stashes the next argument as a :script into its list of commands to run, and quits looking for things to parse. Everything that’s left in the original arguments list stays in the system command-line arguments list (System.argv/0). In this case, "phx.server" is what’s left.

On the Mix side, the contents of the mix script calls Mix.CLI.main/1, which defaults to getting its argument list from System.argv/0. Voilà: Mix.CLI.main(["phx.server"]).

An analogous thing happens, also via Kernel.CLI, if we run mix phx.server, or elixir -S mix phx.server.

The first thing that Mix.CLI.main/1 does is start the Mix application with Mix.start/0—but I could go on like this forever. Let’s just agree that Mix is now going to run the phx.server task.

Why is it shaped like this?

I now truly believe that iex -S mix phx.server starts my Phoenix dev server on a fresh Erlang VM and drops me into an Elixir shell in that VM.

I’ve had the chance to admire the effort and ingenuity that goes into letting users run programs—no—start up VMs and run programs on them—with simple one-liners.

I still go back and forth between “this is an obvious command that’s really explicit about what it does” and “something about this feels magical and weird.” That -S just sits kinda funny.

If I were in the habit of using elixir -S mix phx.server to run the phx.server Mix task (which works): look, symmetry! iex -S mix phx.server is the same thing but through IEx!

But I don’t do that, because mix phx.server works, thanks to mix being an Elixir script you can also invoke from a system shell. It all makes sense! Not so symmetric, though.

In the end, it’s a balance between elegance and power. I see a lot more elegance in it than I did before.

Trivia: Some history of iex -S mix

Early on, it seems there was some tension between the conciseness of mix iex (possible when mix is a plain shell script) and the flexibility of iex -S mix (possible when mix is an Elixir script); bin/mix went back and forth between shell script and Elixir script in 2012-2013:

• 2012/07/16: “Add mix file executables” (a shell script)
• 2012/07/31: “Make mix an Elixir script” (an Elixir script)
• 2012/11/30: “Fix mix iex” (a shell script again)
• 2012/12/05: J. Valim: “I believe we need to remove support for mix iex as it needs to be iex -S mix.” (v0.7.2 breaks mix #692; some discussion here.)
• 2013/01/20: “Provide iex -S mix instead of mix iex” (an Elixir script again)

OTP design principles - Supervision trees, behaviours, applications, releases, release handling

Learn you some Erlang for great good - the classic by Fred Hebert

The OTP team blog - good resource on how some things work

1. Observer’s graphical interface depends on both the wxWidgets cross-platform GUI library and the OTP application wx, which supplies Erlang bindings for it. My system had neither.
2. Once I’d sorted out the system problems in 1., I was able to run Observer from a plain IEx prompt, but not from the prompt opened with iex -S mix phx.server. To understand this, I had to learn that Elixir “prunes unused code paths.” More about this later.

Getting past these roadblocks turned out pretty straightforward with the latest Erlang/OTP and a newish Elixir on my M2 Macbook in January 2025. I say turned out, because past discussions on issues around asdf, Erlang and wxWidgets had me ready for a big mess, and it took me a bit to isolate what was relevant to me.

Incidentally, I think everything here also applies to Erlang’s debugger application, which also uses wxWidgets.

Sorting out my system

Install wxWidgets

To begin with, I didn’t even have wxWidgets installed on my computer. I installed it with Homebrew:

brew install wxwidgets

Install Erlang with wx enabled

I was still missing the wx OTP application; it had been disabled in my existing Erlang installation.

I manage runtimes on my Mac with asdf. I suspect that I could have simply uninstalled and reinstalled Erlang after putting wxWidgets on my system, but I included wx explicitly, as follows:

export KERL_CONFIGURE_OPTIONS="--with-wx" asdf install erlang 27.2

The conservative thing would have been to uninstall the current Erlang and reinstall the same version but with wx enabled, but I went ahead and updated from 26.0.1 to 27.2.

Because I changed versions, I put the correct version in my project’s .tool-versions file with asdf local. Because I changed major versions, I also had to install an Elixir compiled with the right Erlang/OTP, and set the local version of that as well.

Check that wx and Observer work

At this point I was able to fire up IEx with iex and type

iex(1)> :observer.start()

and the Observer GUI popped up. Under the Applications tab were listed just elixir, iex, kernel, and logger.

There’s also the wx demo. Since I’d seen Observer working in IEx, I didn’t need to check wx by itself, but it’s a thing if you do need it or want to try it. Start up the Erlang shell:

erl

And run the demo:

> wx:demo().

A demo GUI should open, proving that wxWidgets and its Erlang bindings are present and working.

The deal with code-path pruning

As of Elixir 1.15, before a Mix project gets compiled, “unused code paths” are pruned, including for applications that ship with Elixir or Erlang, like Observer.

Translation: the Erlang runtime will look for modules in only directories containing the project’s dependencies. This makes compilation faster.

So, a general-purpose IEx prompt has access to all the stuff that comes with your Elixir and Erlang installations, but use iex -S to run a Mix task, and any module that is not used in that Mix project becomes invisible.

Including Observer and its dependencies

You can declare a dependency on an OTP application in mix.exs by including it in an application/0 function, under :extra_applications. My understanding is that this is meant for applications shipped with Erlang/OTP or Elixir—everything else you’d just put in your deps definition.

If you don’t always need a given application in the project, you can instead make it available from the prompt on a one-off basis. Without putting anything into my :extra_applications, under OTP 27, I can start my dev server:

iex -S mix phx.server

Then restore the code path to Observer in IEX with Mix.ensure_application!(app):

iex(1)> Mix.ensure_application!(:observer)

Finally, start Observer:

iex(2)> :observer.start()

Up pops the Observer GUI. A quick check of the Applications tab shows the application supervision tree for my running project.

Other notes

It looks like the way dependencies, and thus “unused code paths” to be pruned, are decided has been streamlined between OTP 26 and OTP 27.

Under Erlang/OTP 26, I had to explicitly require :wx and :runtime_tools as well as :observer in order to run Observer. With OTP 27 I only had to ensure :observer, even after removing the :extra_applications keyword entirely from the application definition in my mix.exs.

I see that :observer_backend is part of :runtime_tools. I’m keeping that in mind in case I need to understand this when I try to look at production nodes from my laptop.

We manage runtimes with asdf. In this example we’re using Elixir 1.17.3 in a project and want to switch from OTP 26.2.5.6 to OTP 27.2.

Steps

0. Check the status quo

See which versions of any installed runtimes, including Elixir and Erlang/OTP, are set for the current directory, and see if that’s through the global .tool-versions config file or a local one:

asdf current

See which versions of Erlang/OTP are installed on the system with asdf:

asdf list elixir

asdf list erlang

1. Install the new Erlang/OTP

asdf install erlang 27.2

2. Install an Elixir version compiled with the right OTP major version

Even if we don’t want to upgrade Elixir versions per se, we do need to match the Elixir installation with our OTP major version.

asdf install elixir 1.17.3-otp-27 

3. Set the project to use the newly installed versions of both

asdf local elixir 1.17.3-otp-27

asdf local erlang 27.2

Now asdf is configured to point to the newly installed version of Erlang/OTP and the Elixir version that’s compatible with it.

References

• asdf guide introduction
• asdf configuration (.tool-versions)
• asdf Erlang plugin