Michael Rowe

Headless AI

note5 min read

Headless AI tools behave like command-line programs

A headless AI model runs non-interactively: no chat interface, no back and forth. You pass it text, it returns output, and it exits. That makes it composable with any script or scheduler that already knows how to move data between programs.

Headless AI

One-sentence definition: A headless AI model runs non-interactively, accepting input via standard input and returning output to standard output,1 with no persistent session or chat interface.

The term borrows from software architecture, where “headless” describes any system that runs without a user-facing interface. A headless model is a language model with the chat window taken away.

Most AI command-line tools, Claude Code among them, support this mode. You pipe text in,2 the model processes it, output comes back. From the operating system’s perspective, this is indistinguishable from cat, grep, or awk3 — a program that accepts input, does something with it, and returns output.

What it enables: composability. When AI behaves like a Unix tool,4 it inherits decades of infrastructure built on that assumption — pipes, redirects, cron jobs, systemd timers,5 shell scripts.6 None of that infrastructure needs to know it’s talking to a language model; it sees a program with defined inputs and outputs.

A script can query a knowledge base, pipe the results to a headless model for summarisation, and write the output to a file, on a schedule and without a human in the loop. The AI is doing one job, with clear inputs and predictable outputs.

A Friday timer, and a spreadsheet of module comments

Every Friday at 13:00 a timer on my machine runs one line: it calls the AI tool with the instruction “review week 38”. The tool gathers what changed in my notes that week, the papers I added to my library and the highlights from my reading, and writes a draft weekly review into my planning vault. I’m usually in a meeting. When I open the file later, I edit a draft rather than start from a blank page. The model wasn’t running as a chat; it ran once, wrote one file, and stopped.

The same shape fits an educator’s week. Module evaluation comments arrive as a spreadsheet export. A short script could take that file, pass the comments to a headless model with the instruction “group these by theme and quote one representative comment per theme”, and save the result as a document next to the export — every Friday, for every module, without anyone opening a chat window. The judgement about what the themes mean and what to do about them is still yours; the model has only done the sorting.

The rest of the pipeline is ordinary, deterministic software: a timer fires, a script reads a file, a file is written. Nothing there is new or uncertain, and none of it needs the model to explain itself. The model is one step in the chain, and the only one whose output isn’t fully predictable, which is a good reason to keep that step small and its instruction precise. Harness engineering is the same idea at a larger scale: build the checks around the model so its output doesn’t have to be trusted on its own.

The model cannot ask for clarification

Headless mode gives up the back-and-forth that makes interactive AI useful for complex or ambiguous tasks. The model can’t ask for clarification. It’s the right approach when the task is well-defined, the input is structured, and the output format is predictable. For anything that requires iteration, an interactive session is the better tool.

Notes

  • Related to the Unix philosophy: do one thing well, accept input from pipes, write output to pipes
  • Because it fits into ordinary scripts, AI-assisted automation doesn’t need specialised software for coordinating AI agents

Footnotes

  1. Standard input and standard output — the two default channels every command-line program has: one it reads from, one it writes to. Because every program uses the same two channels, the output of one can become the input of the next. Wikipedia ↩

  2. Pipe — the | character, which connects the output of one program to the input of another, so a | b sends whatever a produces straight into b. Wikipedia ↩

  3. cat, grep, awk — three standard command-line programs, each doing one small job: cat prints a file’s contents, grep finds lines matching a pattern, awk reshapes text one line at a time. They are the canonical examples of programs that read input, do one thing and write output. Wikipedia: cat, grep, AWK ↩

  4. Unix — the family of operating systems, dating from 1969, that established the convention of small programs that read text in and write text out. Linux and macOS descend from it; the design is why the command line works the way it does. Wikipedia ↩

  5. cron and systemd timers — the two common ways to have a computer run a command on a schedule (“every Friday at 13:00”) without anyone at the keyboard. Wikipedia: cron, systemd ↩

  6. Shell script — a plain-text file listing commands for the computer to run in order, so a sequence you would otherwise type by hand can be run with one instruction, or on a timer. Wikipedia ↩

Continue reading

  • Claude Code

    Anthropic's AI agent that works in a folder of files on your own machine, reading, editing, and checking them under your direction instead of answering in a chat window.

  • Agentic workflows

    The human role in agentic workflows: agents handle execution while humans decide what should be made, define what good looks like, and judge the results.

  • Harness engineering

    Harness engineering is the practice of building the full architectural scaffolding within which AI agents operate — structured documentation they can reason with, constraints that enforce invariants, and feedback loops that let them know when they've succeeded. It is distinct from prompt engineering, which shapes individual tasks, and from oversight, which monitors outputs after the fact. The harness is the infrastructure that makes delegation coherent at scale.