██  ██ █████  ████  █████  ██     ████  ██  ██  ████               ██
██  ██ ██    ██  ██ ██  ██ ██    ██  ██ ███ ██ ██           ██   ██
██▀▀██ ████  ██████ ██  ██ ██    ██  ██ ██▀███ ██ ███     ██   ██
██  ██ ██    ██  ██ ██  ██ ██    ██  ██ ██ ▀██ ██  ██   ██   ██
██  ██ █████ ██  ██ █████  █████  ████  ██  ██  █████      ██

Headlong is an open source agent microharness, a complete agent harness with a core of less than 10K lines of Bash. Headlong's defining feature is persistent agency. Your agent keeps thinking between external interactions in a self-guided loop inspired by human inner monologue. A message from a human doesn't start a session. It lands in the agent's thought stream as one more observation, and the agent decides if and when to respond. You give your agent a name and a personality, and it sets its own interests and priorities, starts its own projects, and pings you when it has something to say.

At the heart of Headlong is shellm, a Bash implementation of a recursive language model (RLM). The agent thinks by writing shell commands, running them, and reading the output. No tool system besides Bash is needed.

Get started

One line installs everything, interviews you to bring a Headlong agent to life, and opens a dashboard where you can watch its mind run:

curl -fsSL https://headlong.ai/install.sh | bash

You'll need bash 3.2+, git, curl, jq, and an LLM API key (Anthropic, OpenAI, Gemini, or OpenRouter); the dashboard also needs uv and bun or node, and the installer offers to fetch those. Use a dedicated, spend-capped key, because your agent runs real shell commands and thinks around the clock. With Docker installed the commands run in a container; without it they run directly on your machine as you. How much the background thinking costs depends on how quickly the agent loops and which model backs it. At the settings we run our agent with, it comes to $1 to $2 an hour.

The agent's name becomes a command:

ada hello            # one message, wait for the reply
ada                  # chat
ada stop / ada start # pause / resume its mind
ada dash             # open the dashboard
ada bugreport        # bundle logs + trajectory (keys scrubbed) for a bug report

headlong-killall stops every Headlong process on the machine if you need a panic button. curl -fsSL https://headlong.ai/status.sh | bash shows what is installed and running; curl -fsSL https://headlong.ai/uninstall.sh | bash removes it all (details in docs/install.md).

You can also run the same flow inside a long-lived Docker container:

docker run -it --name headlong --restart unless-stopped -p 8080:8080 buildpack-deps:curl \
  bash -c 'curl -fsSL https://headlong.ai/install.sh | bash; exec bash'

Details, non-interactive/CI installs, and installing from a checkout are in docs/install.md.

Key ideas

• Persistent agency. The agent runs a continuous loop that generates its next thought. Messages from Slack, Telegram, or the chat app are injected into the thought stream as observations, and the agent decides if and when to respond. Classic turn-taking request/response mode works too.
• Built around Ken Thompson's philosophy. The core tooling is a handful of small Bash executables (shellm, traj, llm, context, mem, skills, ...), each doing one thing well and composing through pipes, files, and environment variables. The model writes shell commands, so curl is the HTTP client and jq is the JSON processor.
• An agent's trajectory is a DAG of jsonl files with fork and merge. An agent has access to everything it has thought and done, and the tooling to explore it down to any single step.
• Context is a projection of the trajectory. Nothing is compacted away in place. Compaction and agent introspection operate on the same files with the same tools.
• Tiered context compaction. The entire trajectory stays in context at exponentially decaying resolution. Recent entries appear verbatim, and older entries are progressively summarized. The tiers act as an index, so the agent can retrieve raw entries when it needs them.
• Subagents see their ancestors' trajectories. A subagent can see why it was created, what the parent already tried, and how it fits into the big picture.
• Docker by default. Generated code sandboxes itself into a container whenever Docker is available, and container reuse keeps restarts cheap. Local mode works too.
• Self-improvement by fork, test, merge. An agent forks the Headlong codebase (and optionally its own trajectory), changes something, and runs. Merge the change back if it worked, or discard the agent and its changes if it didn't. No rollback machinery is needed.

The full backstory and design philosophy are in philosophy.md.

The tools

To make a minimal agent, you need:

• a loop that repeatedly generates the next thought (thinkers, which calls llm),
• a way for a thought to reason and act (shellm, with Bash as the only tool),
• a way to record the agent's trajectory, its life so far (traj), and
• a way to turn that trajectory into the context for the next call into the LLM (context).

Headlong also gives an agent a few convenience tools, such as a way to distill and codify its experience (mem) and a way to save and reuse procedures for specialized tasks (skills). The core is the tools the running mind executes, the executables in bin/ plus the thought processes in thinkers/, and it comes to 9.6K lines by cloc's count. A harness this small can be read end to end, and it is easy to modify and experiment with.

Tool	What it does
shellm	The RLM core. It sends context to an LLM, runs the bash the LLM writes back, and repeats
llm	Multi-provider LLM CLI. Anthropic, OpenAI, Gemini, and OpenRouter behind one interface
traj	Trajectory operations on append-only jsonl DAGs with fork and merge
context	Renders a trajectory into an LLM messages array with tiered compaction
thinkers	The mind. Reactive thought processes run by a dispatcher
chat / focus	Messages and goals on an identity's trajectory
mem / skills	File-based memory store and SKILL.md-based abilities
recap	Summarizes a trajectory into themes and episodes
shellm-docker	Constrained docker facade staged into sandbox containers for generated code
glob / view / put / sub	Small file tools the agent uses instead of the sharp edges of coreutils

Everything you run around the mind lives in tools/:

Tool	What it does
shellm-docker-broker	Host-side policy server for brokered Docker, never present in the mind's environment
identity	Creates and manages identities (persona, memories, activate script)
persona	Talks to and manages an identity by name, from anywhere
headlong-init	One-time bootstrap: interview, first identity, first thoughts
shellm-explore	Visualizes run trees and writes LLM-powered reports on what happened and why
headlong-web	The dashboard, where you watch a mind think in the browser
headlong-slack-bridge / headlong-telegram-bridge	Slack and Telegram connectors into the same inner experience
headlong-killall	Panic button that stops every Headlong-related process
pr-committee	Multi-model pull request review, used on this repo

Learn more

• philosophy.md — the case for applying Ken Thompson's philosophy to agent microharnesses, and the full design story
• docs/shellm.md — the shellm engine reference: the loop, context passing, Docker sandboxing, envs, the llm tool, options
• docs/install.md — every install variant, including CI/non-interactive and long-lived Docker
• AGENTS.md — operating a running identity (for humans and coding agents): paths, logs, health checks, sharp edges
• web/, slack/, telegram/ — the dashboard and the chat bridges
• deploy/ — running an agent on a dedicated box (systemd units, terraform, operations)

Acknowledgements

The recursive language model idea in shellm comes in part from the Recursive LLM experiment (April 2023) and from Alex Zhang's Recursive LM (RLM) project (October 2025). The continuous thinking behind Headlong's persistent agency — and its name — come from the Headlong research project.

License

Apache 2.0. Copyright 2026 Laude Institute.