laude-institute/headlong

Source: https://github.com/laude-institute/headlong

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

CI (https://github.com/laude-institute/headlong/actions/workflows/ci.yml)

Headlong is an open-source agent microharness—a complete agent harness with a core of less than 10,000 lines of Bash. Its defining feature is persistent agency. Your agent continues 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 simply enters the agent’s thought stream as another observation. The agent then 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.

Headlong agents are also built for collaboration. A whole team can interact with a single agent via Slack, Telegram, and a chat app—all conversations feed into the agent’s unified thought stream. The agent tracks what different people are working on, connects them, and pings whoever is most relevant. Sharing one agent feels more like interacting with a person than a service.

At the heart of Headlong is shellm, a Bash implementation of a recursive language model (RLM) (https://alexzhang13.github.io/blog/2025/rlm/). The agent thinks by writing shell commands, executing them, and reading the output. No tool system beyond Bash is required.

Get started

A single command installs everything, interviews you to bring a Headlong agent to life, and opens a dashboard to watch its mind at work:

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 requires uv (https://docs.astral.sh/uv/) and bun or node; the installer can fetch these for you.

Headlong is alpha research software. Use a dedicated, spend-capped key—your agent runs real shell commands and thinks continuously. If Docker is running, the installer can keep the entire agent in a container, or install it on your machine while sandboxing the agent’s commands in a container. An unsandboxed host install is also possible with explicit confirmation, though not recommended.
Without Docker, commands would run directly on your machine under your user, so the installer pauses for explicit approval before proceeding. The cost of background thinking depends on the agent’s loop frequency and the underlying model. Thinking rate decays exponentially when no one is chatting with the agent and resets immediately when a message arrives. With our default settings, it costs roughly $1 to $2 per hour.

The agent’s name becomes a command:

ada hello            # Send a message and wait for the reply
ada                  # Enter chat mode
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’s installed and running; curl -fsSL https://headlong.ai/uninstall.sh | bash removes it all (details in docs/install.md).

The container flow offered by the installer is as follows—you can also run it manually:

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'

For details, non-interactive/CI installs, and installing from a checkout, see docs/install.md.

Key ideas

• Persistent agency. Most harnesses are reactive or wake on a schedule to run a fixed checklist. A Headlong agent never sleeps and has no checklist. It continuously generates thoughts about whatever it finds interesting, even without external input. Messages from Slack, Telegram, or chat apps are injected into the thought stream as observations, and the agent decides if and when to respond. Classic turn-based request/response mode also works.
• Multi-player fun. One agent, one mind, many people. There are no per-user sessions; the agent experiences all conversations on a single timeline and decides who to reply to and when. This unified stream means no hard walls between people—anything you tell the agent is potentially shared with everyone who interacts with it.
• 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, plus tools to explore down to any single step.
• Context is a projection of the trajectory. Nothing is compacted 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, while older entries are progressively summarized. The tiers act as an index, allowing the agent to retrieve raw entries when needed.
• Subagents see their ancestors’ trajectories. A subagent can see why it was created, what the parent already tried, and how it fits into the bigger picture.
• Docker by default. Generated code sandboxes itself in a container whenever Docker is available, and container reuse keeps restarts cheap. Local mode also works.
• Self-improvement by fork, test, merge. An agent forks the Headlong codebase (and optionally its own trajectory), changes something, and runs. If it works, merge the change back; if not, discard the agent and its changes. No rollback machinery is needed. The agent we run at Laude works in its own fork of this repo, and we’ve pulled over 50 of its commits back into main.

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

The tools

To build 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 provides a few convenience tools, such as a way to distill and codify experience (mem) and a way to save and reuse procedures for specialized tasks (skills). The core consists of the tools the running mind executes—the executables in bin/ plus the thought processes in thinkers/—totaling 9.8K lines by cloc’s count. A harness this small can be read end to end and is easy to modify and experiment with.

Everything you run around the mind lives in tools/:

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 draws in part from the Recursive LLM (https://github.com/andyk/recursive_llm) experiment (April 2023) and Alex Zhang’s Recursive LM (RLM) (https://alexzhang13.github.io/blog/2025/rlm/) project (October 2025). The continuous thinking behind Headlong’s persistent agency—and its name—comes from the Headlong (https://github.com/andyk/headlong) research project.

License

Apache 2.0. Copyright 2026 Laude Institute.