laude-institute/headlong

Headlong – a Bash‑based micro‑harness for persistent AI agents

What it is

• An open‑source research framework that lets you run a continuously‑thinking AI “agent” on your own machine (or in Docker). The core is ~11 K lines of Bash that implement a recursive language model (RLM): the LLM writes Bash commands, the system runs them, feeds the output back to the model, and repeats.
• Designed for persistent agency – the agent keeps generating thoughts even when nobody is talking to it, and decides on its own when and how to reply.
• Supports multi‑user interaction: Slack, Telegram, or a web dashboard all feed into a single shared thought stream, so many people can converse with the same agent.

Key concepts

Concept	What it means
Persistent agency	No request/response checklist; the agent runs a loop that continuously produces “thoughts” (shell commands) and only interrupts that loop when it decides a message deserves a reply.
Recursive language model (shellm)	The LLM receives the current context, returns a Bash snippet, the snippet is executed, its stdout/stderr become part of the next context. This is the only “tool” the model uses – Bash itself.
Trajectory	An append‑only JSON‑L DAG that records every command the agent ran, its outputs, and meta‑data. The whole history can be explored, forked, merged, or summarized.
Tiered context compaction	Recent entries are kept verbatim; older entries are progressively summarized, giving the model a cheap way to retain a long‑term memory without blowing token limits.
Sub‑agents	Agents can spawn child agents that inherit the parent’s trajectory, enabling hierarchical projects and self‑improvement.
Docker sandboxing	By default the installer runs the agent inside a container, isolating the generated commands from the host. A host‑install is possible but requires an explicit “yes”.

Main tools (all tiny Bash executables)

• shellm – the RLM engine (core loop).
• llm – unified CLI for Anthropic, OpenAI, Gemini, OpenRouter, or any OpenAI‑compatible local server (Ollama, llama.cpp, vLLM, etc.).
• traj – manipulate the trajectory DAG (append, fork, merge).
• context – render a trajectory into the LLM‑compatible message array with tiered compaction.
• thinkers – dispatcher that runs one or more thought‑processes.
• mem / skills – file‑based memory store and reusable skill definitions (Markdown‑described procedures).
• headlong‑web – browser dashboard to watch the mind in real time.
• headlong‑slack‑bridge / headlong‑telegram‑bridge – connectors that turn chat messages into observations for the agent.
• headlong‑killall – panic button that stops every Headlong process.

Installation & getting started

# One‑liner installer (requires bash, git, curl, jq, Python 3, and an LLM API key)
curl -fsSL https://headlong.ai/install.sh | bash

• The installer asks whether to run the agent inside Docker (recommended) or directly on the host.
• After install you get a command named after your agent (e.g. ada).

  ada hello            # send a single message and wait for a reply
  ada                  # open an interactive chat session
  ada dash             # launch the web dashboard (http://localhost:8080)
  ada stop / ada start # pause or resume the background thinking loop
  

• headlong‑killall stops everything instantly; status.sh reports what is running; uninstall.sh removes the setup.

Running with local models

• Any server that implements the OpenAI chat‑completion API works (Ollama, llama.cpp, vLLM, LM Studio, etc.).
• Set the provider, URL, and model in ~/.headlong/.env (or export HEADLONG_* vars) and restart the agent.
• Example for Ollama:

  export HEADLONG_PROVIDER=local
  export HEADLONG_LOCAL_URL=http://127.0.0.1:11434/v1
  export HEADLONG_LOCAL_MODEL=qwen3:8b
  curl -fsSL https://headlong.ai/install.sh | bash
  

Cost & safety notes

• Because the agent runs real shell commands continuously, you should use a dedicated, spend‑capped API key and keep the agent sandboxed (Docker or explicit containerisation).
• The authors report typical running costs of $1–$2 per hour with their default settings, depending on model size and loop speed.
• The system backs off exponentially when idle, so costs drop sharply when no one is talking to the agent.

Documentation & further reading

• philosophy.md – design rationale and the “Ken Thompson” philosophy behind tiny, composable Bash tools.
• docs/shellm.md – deep dive into the RLM loop, context handling, and Docker sandboxing.
• docs/install.md – all installation variants, CI‑friendly non‑interactive installs, and how to run the harness on a dedicated server.
• AGENTS.md – how to manage identities (personas), view logs, and perform health checks.
• web/, slack/, telegram/ – source for the dashboard and chat bridges.

License

• Apache 2.0 (© 2026 Laude Institute).

---

Bottom line: Headlong is a research‑grade, Bash‑centric framework that lets you spin up a self‑driving LLM‑backed agent capable of continuous autonomous reasoning, multi‑user interaction, and self‑modifying code. It is deliberately lightweight, highly inspectable, and built around the idea that the LLM should write and run shell commands directly, without a separate tool‑calling layer. Suitable for developers who want to experiment with persistent AI agents on their own hardware while keeping the entire stack transparent and editable.