Headlong: a Bash microharness where the agent thinks between your messages
An open source agent microharness featuring persistent agency and recursive LLMs. Of bash, by bash, for bash; it's shells all the way down.
At a glance
- What is it?
- Headlong is an alpha research harness built from roughly 11K lines of Bash. Its defining claim is persistent agency: the agent keeps looping on its own thoughts, and your Slack message is just another observation in that stream. Here is what the repository actually specifies, and where the design puts the burden on you.
- Who is it for?
- Adopt Headlong if you want to read and modify the entire harness, you already live in a shell, and you can give it a sandbox plus a spend-capped key. Do not adopt it if you need per-user session isolation, a stable API, or an unattended production service, since the README labels it alpha research software and notes that anything told to the agent is shared with everyone who talks to it.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: most harnesses wait for a prompt, Headlong does not
A conventional agent harness is reactive. It sits idle until a request arrives, runs a turn, returns a result, and goes back to sleep. Scheduled variants wake on a timer and execute a fixed checklist. Headlong is built on the opposite assumption. According to the README, a Headlong agent is never asleep and there is no checklist. It keeps generating thoughts about whatever it decides is interesting, and an incoming message from a human is injected into that thought stream as one more observation rather than starting a session. The agent then decides whether and when to reply.
That reframing changes who the product is for. It is not aimed at teams who want a request/response endpoint with predictable latency. It is aimed at people who want something closer to a colleague: you give the agent a name and a personality, and per the README it sets its own interests and priorities, starts its own projects, and pings you when it has something to say. The README explicitly notes that classic turn-taking request/response mode still works, so the persistent loop is a default posture rather than a hard constraint. The intended audience is engineers comfortable reading Bash, since the whole harness is small enough to audit and modify.
shellm: thinking is writing shell commands and reading their output
The mechanism at the core is `shellm`, described in the README as a Bash implementation of a recursive language model. The agent thinks by writing shell commands, running them, and reading the output. There is no separate tool registry, no JSON schema of functions, no plugin manifest. The README states plainly that no tool system besides Bash is needed, and that because the model writes shell commands, `curl` serves as the HTTP client and `jq` as the JSON processor.
Around `shellm` sits a set of small executables the README names: `traj`, `llm`, `context`, `mem`, `skills`. The stated design principle is Ken Thompson's: each does one thing and composes through pipes, files, and environment variables. This is the part worth dwelling on if you are deciding whether to adopt it. A harness whose extension surface is the filesystem and the process table is trivially hackable and trivially breakable. There is no type system standing between your agent and a malformed command. The README's own warning follows from this: run it in a sandbox because Headlong agents run shell commands.
Two further mechanisms are documented. The agent's trajectory is a DAG of jsonl files with fork and merge, so an agent has access to everything it has thought and done, with tooling to explore it down to a single step. Context is a projection of that trajectory. Nothing is compacted away in place, which means the same files and tools serve both compaction and agent introspection. Subagents can see their ancestors' trajectories, so a subagent can determine why it was created and what the parent already tried.
Tiered compaction and the retrieval index it creates
The README describes tiered context compaction as keeping the entire trajectory in context at exponentially decaying resolution. Recent entries appear verbatim. Older entries are progressively summarized. The tiers act as an index, so the agent can retrieve raw entries when it needs them.
This is the most consequential design decision in the project and the one most likely to surprise you in practice. Because compaction operates on the trajectory files rather than replacing them, an agent that has been running for days does not lose the original record; it loses the cheap access path to it. Retrieval is then a shell operation the agent has to decide to perform. The quality of that decision depends on the model backing the loop. A weaker local model may summarize aggressively and never go back for the raw entry, at which point the decaying resolution is effectively permanent loss from the agent's point of view even though the bytes are still on disk. The README does not describe any automatic retrieval trigger, so I would treat the retrieval step as agent-discretionary until you confirm otherwise in the source.
Installing it: one curl, an interview, and a name that becomes a command
The README gives a single install line: `curl -fsSL https://headlong.ai/install.sh | bash`. That script installs everything, interviews you to configure an agent, and opens a dashboard. Prerequisites listed are bash 3.2 or later, git, curl, jq, Python 3, and an LLM API key from Anthropic, OpenAI, Gemini, or OpenRouter. A local model on any OpenAI-compatible server also works, and the README names llama.cpp, Ollama, vLLM, and LM Studio, with no key needed. The dashboard additionally needs `uv` and either bun or node; the installer offers to fetch those.
The agent's name becomes a command. The README's example uses `ada`: `ada hello` sends one message and waits for the reply, bare `ada` opens a chat, `ada stop` and `ada start` pause and resume its mind, `ada dash` opens the dashboard, and `ada bugreport` bundles logs plus trajectory with keys scrubbed. Two operational escape hatches are documented: `headlong-killall` stops every Headlong process on the machine, and `curl -fsSL https://headlong.ai/status.sh | bash` reports what is installed and running. Uninstall is `curl -fsSL https://headlong.ai/uninstall.sh | bash`.
For containerized installs the README supplies the command directly: `docker run -it --name headlong --restart unless-stopped -p 8080:8080 --add-host host.docker.internal:host-gateway buildpack-deps:curl bash -c 'curl -fsSL https://headlong.ai/install.sh | bash; exec bash'`. The README also points to docs/install.md for non-interactive and CI installs and for installing from a checkout.
Sandboxing, spend, and the two warnings that matter
Docker is the default posture. The README states that generated code sandboxes itself into a container whenever Docker is available, and that container reuse keeps restarts cheap. The installer offers three shapes: keep the whole agent in a container, install on your machine with the agent's commands sandboxed in a container, or an unsandboxed host install behind an explicit yes, which the README does not recommend. Without Docker, commands would run directly on your machine as you, so the installer stops and asks for an explicit yes before proceeding.
Cost is stated rather than estimated. The README says background thinking cost depends on how quickly the agent loops and which model backs it, that the rate of thinking backs off exponentially when nobody is talking to the agent and resets the moment a message arrives, and that at the authors' own settings it comes to $1 to $2 an hour. That is a continuous burn, not a per-request charge, and the exponential backoff is the only documented governor on it. The second warning is about secrets. The README instructs you to use a dedicated, spend-capped API key and not to give your agent sensitive secrets. It also notes that the installer offers to keep the whole agent in a container when Docker is running.
One shared mind is the feature and the failure mode
Headlong's multi-player model is unusual and worth stating precisely, because it is where the project will most often be the wrong tool. The README says there are no per-user sessions. The agent experiences all of its conversations in a single timeline and decides who to reply to and when. A whole team can talk to one agent over Slack, Telegram, and a chat app, and every conversation lands in the same stream of thoughts.
The README does not soften this. It states that the single stream means no hard walls between people, and that you should assume anything you tell the agent is shared with everyone who talks to it. If your use case involves HR questions, incident details under embargo, customer PII, or anything with a per-person confidentiality boundary, Headlong's architecture is actively opposed to what you need. You would be relying on the agent's judgement about who to tell what, which is the same judgement that decides when to reply. There is no documented access-control layer, no per-channel scoping, and no session isolation to configure. This is not a missing feature that a config key turns on. It is the design.
What it is not: the comparison that clarifies the trade
The obvious comparison is a conventional tool-calling agent framework, of the kind where you register typed functions and the runtime dispatches them, with a session object per conversation and a request/response contract. That approach gives you schema validation, per-user state, and a predictable cost profile tied to requests. It also constrains what the agent can do to the set of tools you registered in advance. Headlong takes the other branch on both counts. The agent's action space is the shell, which is unbounded, and its state is one shared trajectory, which is unpartitioned. You gain the ability to have the agent build its own tools mid-run and to inspect the full DAG of what it did. You give up the guardrails that make a framework safe to put in front of non-engineers.
The README also describes a self-improvement path: an agent forks the Headlong codebase, and optionally its own trajectory, changes something, and runs, with the change merged back if it worked or discarded if it did not. That is coherent with the fork-and-merge trajectory model, but it means the running agent can modify the code that is running it. Combined with the sandbox guidance, this is the strongest argument for the container install over the host install.
Maintenance, licensing, and what to check before you commit
Headlong is licensed Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements around preserving notices and stating changes. That is a permissive license, and it is the right one for a project whose stated model is fork, test, merge. It does not give legal advice and I am not giving any; if you plan to redistribute a modified harness, read the license text and the NOTICE requirements yourself.
On maintenance, the repository is not archived and the last push recorded is 2026-09-10. No releases were retrieved, so there is no versioned artifact to pin and no changelog to read. The README labels the project alpha research software and says to expect frequent changes. Practically, that means you should install from a checkout rather than the one-line installer if you need reproducibility, since docs/install.md documents that path. Upgrade cost is therefore not a version bump but a re-fork: your changes to `shellm`, `traj`, or the other executables sit against a moving main branch.
Two things are worth verifying before you commit. First, whether the installer's sandbox actually engages on your host: the README says sandboxing happens whenever Docker is available, so confirm Docker is running before you start, not after. Second, the real loop rate and model choice, because the $1 to $2 per hour figure is stated for the authors' settings and the README gives no other number. Run `ada stop` when you are not watching it.
Editorial conclusion
Adopt Headlong if you want to read and modify the entire harness, you already live in a shell, and you can give it a sandbox plus a spend-capped key. Do not adopt it if you need per-user session isolation, a stable API, or an unattended production service, since the README labels it alpha research software and notes that anything told to the agent is shared with everyone who talks to it. Before installing, verify three things: that Docker is running on the host, that your chosen provider key works with the model you intend to back the loop with, and that you accept the stated $1 to $2 per hour burn at the authors' own settings.
Community notes