Skip to content
Back to search

headlong

An open source agent microharness featuring persistent agency and recursive LLMs. Of bash, by bash, for bash; it's shells all the way down.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/laude-institute/headlong with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/laude-institute/headlong'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/laude-institute--headlong/badge.svg)](/listings/laude-institute--headlong)

HTML

<a href="/listings/laude-institute--headlong"><img src="/api/listings/laude-institute--headlong/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 317 lines · 6 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ```
  2. ██ ██ █████ ████ █████ ██ ████ ██ ██ ████ ██
  3. ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██
  4. ██▀▀██ ████ ██████ ██ ██ ██ ██ ██ ██▀███ ██ ███ ██ ██
  5. ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ▀██ ██ ██ ██ ██
  6. ██ ██ █████ ██ ██ █████ █████ ████ ██ ██ █████ ██
  7. ```
  8. [![CI](https://github.com/laude-institute/headlong/actions/workflows/ci.yml/badge.svg)](https://github.com/laude-institute/headlong/actions/workflows/ci.yml)
  9. **Headlong** is an open source agent microharness, a complete agent harness
  10. with a core of about 11K lines of Bash.
  11. [Launch post](https://www.laude.org/updates/headlong-a-microharness-for-persistent-agents) |
  12. [Announcement](https://x.com/andykonwinski/status/2091990178638496195)
  13. > [!IMPORTANT]
  14. > Headlong is alpha research software. Expect frequent changes. Run it in a
  15. > sandbox because Headlong agents run shell commands. Use a dedicated,
  16. > spend-capped API key, and do not give your agent sensitive secrets.
  17. Headlong's defining feature is **persistent
  18. agency**. Your agent keeps thinking between external interactions in a
  19. self-guided loop inspired by human inner monologue. A message from a human
  20. doesn't start a session. It lands in the agent's thought stream as one more
  21. observation, and the agent decides if and when to respond. You give your agent
  22. a name and a personality, and it sets its own interests and priorities, starts
  23. its own projects, and pings you when it has something to say.
  24. A Headlong agent is also built to be shared. A whole team can talk to one
  25. agent over Slack, Telegram, and a chat app, and every conversation lands
  26. in the agent's single stream of thoughts. The agent follows what different
  27. people are working on, connects them, and pings whoever seems most
  28. relevant. Sharing one agent is fun, because it behaves more like a person
  29. than a service.
  30. At the heart of Headlong is `shellm`, a Bash implementation of a
  31. [recursive language model (RLM)](https://alexzhang13.github.io/blog/2025/rlm/).
  32. The agent thinks by writing shell commands, running them, and reading the
  33. output. No tool system besides Bash is needed.
  34. ## Get started
  35. One line installs everything, interviews you to bring a Headlong agent to
  36. life, and opens a dashboard where you can watch its mind run:
  37. ```bash
  38. curl -fsSL https://headlong.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 48 on GitHub
  39. ```
  40. You'll need bash 3.2+, git, curl, jq, Python 3, and an LLM API key (Anthropic,
  41. OpenAI, Gemini, or OpenRouter) — or a local model on any
  42. OpenAI-compatible server (llama.cpp, Ollama, vLLM, LM Studio; see
  43. [Local models](#local-models) below, no key needed); the dashboard also
  44. needs [uv](https://docs.astral.sh/uv/) and bun or node, and the installer
  45. offers to fetch those.
  46. Headlong is alpha research software. Use a dedicated, spend-capped key, because
  47. your agent runs real shell commands and thinks around the clock. With Docker
  48. running, the installer offers to keep the whole agent in a container, or to
  49. install on your machine with the agent's commands sandboxed in a container
  50. (an unsandboxed host install exists too, behind an explicit yes, and is not
  51. recommended).
  52. Without Docker the commands would run directly on your machine as you, so the
  53. installer stops and asks for an explicit yes before setting that up. How much
  54. the background thinking costs depends on how quickly
  55. the agent loops and which model backs it. The rate of thinking backs off
  56. exponentially when nobody is talking to the agent and resets the moment a
  57. message arrives. At the settings we run our agent with, it comes to $1 to $2
  58. an hour.
  59. The agent's name becomes a command:
  60. ```bash
  61. ada hello # one message, wait for the reply
  62. ada # chat
  63. ada stop / ada start # pause / resume its mind
  64. ada dash # open the dashboard
  65. ada bugreport # bundle logs + trajectory (keys scrubbed) for a bug report
  66. ```
  67. `headlong-killall` stops every Headlong process on the machine if you need a
  68. panic button. `curl -fsSL https://headlong.ai/status.sh | bash` shows what is
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 83 on GitHub
  69. installed and running; `curl -fsSL https://headlong.ai/uninstall.sh | bash`
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 84 on GitHub
  70. removes it all (details in
  71. [docs/install.md](docs/install.md#stopping-and-uninstalling)).
  72. The container flow the installer offers is this, and you can also run it
  73. yourself:
  74. ```bash
  75. docker run -it --name headlong --restart unless-stopped -p 8080:8080 \
  76. --add-host host.docker.internal:host-gateway buildpack-deps:curl \
  77. bash -c 'curl -fsSL https://headlong.ai/install.sh | bash; exec bash'
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 94 on GitHub
  78. ```
  79. Details, non-interactive/CI installs, and installing from a checkout are
  80. in [docs/install.md](docs/install.md).
  81. ## Key ideas
  82. - **Persistent agency.** Most harnesses are reactive, or wake on a
  83. schedule to run a fixed checklist. A Headlong agent is never asleep and
  84. there is no checklist. It keeps generating thoughts about whatever it
  85. decides is interesting, even when there is no external input. Messages
  86. from Slack, Telegram, or the chat app are injected into the thought
  87. stream as observations, and the agent decides if and when to respond.
  88. Classic turn-taking request/response mode works too.
  89. - **Multi-player fun.** One agent, one mind, many people. There are no
  90. per-user sessions; the agent experiences all of its conversations in a
  91. single timeline and decides who to reply to and when. That single
  92. stream also means no hard walls between people: assume anything you
  93. tell the agent is shared with everyone who talks to it.
  94. - **Built around Ken Thompson's philosophy.** The core tooling is a
  95. handful of small Bash executables (`shellm`, `traj`, `llm`, `context`,
  96. `mem`, `skills`, ...), each doing one thing well and composing through
  97. pipes, files, and environment variables. The model writes shell
  98. commands, so `curl` is the HTTP client and `jq` is the JSON processor.
  99. - **An agent's trajectory is a DAG of jsonl files** with fork and merge.
  100. An agent has access to everything it has thought and done, and the
  101. tooling to explore it down to any single step.
  102. - **Context is a projection of the trajectory.** Nothing is compacted
  103. away in place. Compaction and agent introspection operate on the same
  104. files with the same tools.
  105. - **Tiered context compaction.** The entire trajectory stays in context
  106. at exponentially decaying resolution. Recent entries appear verbatim,
  107. and older entries are progressively summarized. The tiers act as an
  108. index, so the agent can retrieve raw entries when it needs them.
  109. - **Subagents see their ancestors' trajectories.** A subagent can see why
  110. it was created, what the parent already tried, and how it fits into the
  111. big picture.
  112. - **Docker by default.** Generated code sandboxes itself into a container
  113. whenever Docker is available, and container reuse keeps restarts cheap.
  114. Local mode works too.
  115. - **Self-improvement by fork, test, merge.** An agent forks the Headlong
  116. codebase (and optionally its own trajectory), changes something, and
  117. runs. Merge the change back if it worked, or discard the agent and its
  118. changes if it didn't. No rollback machinery is needed. The agent we run
  119. at Laude works in its own fork of this repo, and we have pulled over 50
  120. of its commits back into main.
  121. The full backstory and design philosophy are in
  122. [philosophy.md](philosophy.md).
  123. ## The tools
  124. To make a minimal agent, you need:
  125. - a loop that repeatedly generates the next thought (`thinkers`, which
  126. calls `llm`),
  127. - a way for a thought to reason and act (`shellm`, with Bash as the only
  128. tool),
  129. - a way to record the agent's trajectory, its life so far (`traj`), and
  130. - a way to turn that trajectory into the context for the next call into
  131. the LLM (`context`).
  132. Headlong also gives an agent a few convenience tools, such as a way to
  133. distill and codify its experience (`mem`) and a way to save and reuse
  134. procedures for specialized tasks (`skills`). The core is the tools the
  135. running mind executes, the executables in `bin/` plus the thought
  136. processes in `thinkers/`, and it comes to about 11K lines by cloc's count (capped at 11.5K). A
  137. harness this small can be read end to end, and it is easy to modify and
  138. experiment with.
  139. | Tool | What it does |
  140. |------|-------------|
  141. | **shellm** | The RLM core. It sends context to an LLM, runs the bash the LLM writes back, and repeats |
  142. | **llm** | Multi-provider LLM CLI. Anthropic, OpenAI, Gemini, OpenRouter, and any local OpenAI-compatible server (llama.cpp, Ollama, vLLM, ...) behind one interface |
  143. | **traj** | Trajectory operations on append-only jsonl DAGs with fork and merge |
  144. | **context** | Renders a trajectory into an LLM messages array with tiered compaction |
  145. | **thinkers** | The mind. Reactive thought processes run by a dispatcher |
  146. | **chat** / **focus** | Messages and goals on an identity's trajectory |
  147. | **mem** / **skills** | File-based memory store and SKILL.md-based abilities |
  148. | **recap** | Summarizes a trajectory into themes and episodes |
  149. | **shellm-docker** | Constrained docker facade staged into sandbox containers for generated code |
  150. | **glob** / **view** / **put** / **sub** | Small file tools the agent uses instead of the sharp edges of coreutils |
  151. Optional integrations live in [contrib](contrib/README.md), including the opt-in [OpenCode coding experiment](contrib/opencode/README.md).
  152. Everything you run *around* the mind lives in `tools/`:
  153. | Tool | What it does |
  154. |------|-------------|
  155. | **shellm-docker-broker** | Host-side policy server for brokered Docker, never present in the mind's environment |
  156. | **identity** | Creates and manages identities (persona, memories, activate script) |
  157. | **persona** | Talks to and manages an identity by name, from anywhere |
  158. | **headlong-init** | One-time bootstrap: interview, first identity, first thoughts |
  159. | **shellm-explore** | Visualizes run trees and writes LLM-powered reports on what happened and why |
  160. | **headlong-web** | The dashboard, where you watch a mind think in the browser |
  161. | **headlong-slack-bridge** / **headlong-telegram-bridge** | Slack and Telegram connectors into the same inner experience |
  162. | **headlong-killall** | Panic button that stops every Headlong-related process |
  163. | **pr-committee** | Multi-model pull request review, used on this repo |
  164. ## Local models
  165. Headlong can use any server that supports the OpenAI chat completions API,
  166. including llama.cpp, Ollama, vLLM, and LM Studio. A local server does not
  167. need an API key unless you configured the server to require one.
  168. For llama.cpp, start the server with an alias that Headlong can use as the
  169. model name:
  170. ```bash
  171. llama-server \
  172. -m qwen3-8b-instruct.gguf \
  173. --alias qwen3-8b-instruct \
  174. -c 32768
  175. ```
  176. Then check the connection:
  177. ```bash
  178. LLM_PROVIDER=openai-compatible \
  179. LLM_API_URL=http://127.0.0.1:8080/v1/chat/completions \
  180. llm -m qwen3-8b-instruct "hello"
  181. ```
  182. For Ollama, start the server if it is not already running:
  183. ```bash
  184. ollama serve
  185. ```
  186. With the server running, download a model and check the connection:
  187. ```bash
  188. ollama pull qwen3:8b
  189. LLM_PROVIDER=openai-compatible \
  190. LLM_API_URL=http://127.0.0.1:11434/v1/chat/completions \
  191. llm -m qwen3:8b "hello"
  192. ```
  193. To configure an existing Headlong agent without running the installer again,
  194. add the provider, server address, and model to `~/.headlong/.env`:
  195. ```bash
  196. LLM_PROVIDER='openai-compatible'
  197. SHELLM_API_URL='http://127.0.0.1:11434/v1/chat/completions'
  198. SHELLM_MODEL='qwen3:8b'
  199. ```
  200. The example uses Ollama. For the llama.cpp example above, use port 8080 and
  201. the `qwen3-8b-instruct` model alias instead. If the server requires a bearer
  202. token, add `LLM_API_KEY` to the same file.
  203. Restart the agent after changing an existing configuration. Replace `ada`
  204. with your agent's name:
  205. ```bash
  206. ada stop
  207. ada start
  208. ```
  209. To let the installer write the same settings, run it and choose the local
  210. model server when asked:
  211. ```bash
  212. curl -fsSL https://headlong.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 258 on GitHub
  213. ```
  214. A local server can also be selected without a terminal:
  215. ```bash
  216. export HEADLONG_PROVIDER=local
  217. export HEADLONG_LOCAL_URL=http://127.0.0.1:11434/v1
  218. export HEADLONG_LOCAL_MODEL=qwen3:8b
  219. curl -fsSL https://headlong.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 267 on GitHub
  220. ```
  221. For a host installation, keep a local server address such as `127.0.0.1`
  222. or `localhost`. Headlong changes the address only when `shellm` runs code
  223. inside its Docker sandbox. A full Headlong container uses
  224. `host.docker.internal` to reach a server on the Docker host.
  225. On Linux, the model server must listen on an address that Docker can reach.
  226. For example, llama.cpp can use `--host 0.0.0.0`, and Ollama can use
  227. `OLLAMA_HOST=0.0.0.0:11434`. Use the machine firewall to keep the model
  228. server off untrusted networks.
  229. Be aware that `host.docker.internal` gives agent code access to other
  230. services running on the host. Do not rely on loopback binding alone to
  231. protect a sensitive service when this route is enabled. See
  232. [the installation guide](docs/install.md#the-one-liner) for the full
  233. networking and security details.
  234. For direct `llm` configuration, thinking options, and provider behavior,
  235. see [the shellm guide](docs/shellm.md#the-llm-tool). The provider policy is
  236. in [design/providers.md](design/providers.md).
  237. ## Learn more
  238. - [philosophy.md](philosophy.md) — the case for applying Ken Thompson's
  239. philosophy to agent microharnesses, and the full design story
  240. - [docs/shellm.md](docs/shellm.md) — the shellm engine reference: the
  241. loop, context passing, Docker sandboxing, envs, the `llm` tool, options
  242. - [docs/install.md](docs/install.md) — every install variant, including
  243. CI/non-interactive and long-lived Docker
  244. - [AGENTS.md](AGENTS.md) — operating a running identity (for humans and
  245. coding agents): paths, logs, health checks, sharp edges
  246. - [web/](web/README.md), [slack/](slack/README.md),
  247. [telegram/](telegram/README.md) — the dashboard and the chat bridges
  248. - [deploy/](deploy/README.md) — running an agent on a dedicated box
  249. (systemd units, terraform, operations)
  250. ## Acknowledgements
  251. The recursive language model idea in `shellm` comes in part from the
  252. [Recursive LLM](https://github.com/andyk/recursive_llm) experiment (April
  253. 2023) and from Alex Zhang's [Recursive LM
  254. (RLM)](https://alexzhang13.github.io/blog/2025/rlm/) project (October
  255. 2025). The continuous thinking behind Headlong's persistent agency — and
  256. its name — come from the [Headlong](https://github.com/andyk/headlong)
  257. research project.
  258. ## License
  259. [Apache 2.0](LICENSE). Copyright 2026 Laude Institute.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.