# Headlong

> Source: https://aiwiki.ai/wiki/headlong
> Updated: 2026-09-03
> Fact-checked: 2026-09-03
> Categories: AI Agents, Developer Tools, Open Source AI
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) - attribute to "AI Wiki (aiwiki.ai)"
> Cite as: AI Wiki. "Headlong." aiwiki.ai, 3 Sept 2026. https://aiwiki.ai/wiki/headlong
> From AI Wiki (https://aiwiki.ai), the free encyclopedia of artificial intelligence. Reuse freely with attribution.

Headlong is an open-source microharness for persistent [AI agents](https://aiwiki.ai/wiki/agentic_ai) developed by the Laude Institute in collaboration with researchers at MIT. Laude announced the project on August 24, 2026 and released its implementation under the [Apache License 2.0](https://aiwiki.ai/wiki/apache_license).[1][2][3] The project is not a language model. It is a small runtime that repeatedly invokes an external [large language model](https://aiwiki.ai/wiki/large_language_model), exposes tools, records state, and schedules later runs so that one logical agent can continue beyond a single request and context window.

Laude describes Headlong as alpha research software and warns users to expect frequent changes.[2] At launch, the project reported 9,900 lines of Bash across its core `bin/` and `thinkers/` directories, excluding tests and comments.[1] The small codebase is intended to make the agent loop and stored state inspectable, rather than to provide a complete hosted-agent platform.

## Design

Headlong organizes an agent's activity into finite runs called wakes. A wake begins because of a schedule, an incoming message, or another configured trigger. The runtime assembles context from the agent's trajectory and memory, calls a language model, executes any generated shell commands that the configuration permits, records the resulting events, and then finishes or arranges a later wake.[1][2] Persistence therefore means a sequence of stateful model calls over time. It does not mean that one model inference runs continuously.

The main components have narrow roles:

| Component | Role |
|---|---|
| `headlong` | Command-line entry point for creating, starting, stopping, waking, and messaging agents |
| `shellm` | Recursive model loop that can execute Bash and return command output to the model |
| `llm` | Interface to model providers and local OpenAI-compatible endpoints |
| `traj` | Append-only trajectory storage, branching, merging, and inspection |
| `context` | Builds the prompt projection shown to a model for a wake |
| `mem` | Reads and writes persistent Markdown memory files |
| `skills` | Loads reusable instructions stored in `SKILL.md` files |

The `shellm` loop sends a prompt to a model, checks the response for a Bash program, executes that program, and feeds the output back into another model call. It stops when the model produces a final response or when a configured iteration limit is reached. A run can also invoke a nested `shellm` process, an implementation of the recursive call pattern used by [Recursive Language Models](https://aiwiki.ai/wiki/recursive_language_model).[4]

Headlong does not bundle a proprietary model. The documentation at launch described adapters for Anthropic, OpenAI, Gemini, OpenRouter, and local services that implement an OpenAI-compatible interface.[2][5] Which model is used, what it costs, and what data policy applies depend on the selected provider and configuration.

## Trajectories, context, and memory

Each trajectory is an append-only JSONL record of prompts, reasoning outputs, actions, observations, messages, summaries, and run metadata. Fork and merge records can connect trajectories into a directed graph without rewriting their earlier events.[6] This structure supports experiments, recovery, and inspection, but it is not the same as version control for every file an agent changes.

The model receives a projection of the trajectory rather than the entire raw record on every wake. Recent events can remain verbatim while older spans are progressively summarized. The underlying event log remains available even when its prompt representation has been compressed.[1][6] This separation allows a logical agent to retain a long history without requiring every past token to fit into one context window.

Persistent memory uses ordinary Markdown files. Skills use directories containing `SKILL.md`, following a format used by several agent systems.[2][4] These stores can preserve useful context between wakes, but they can also preserve mistakes, hostile instructions, or sensitive material. Headlong does not make the content true merely by remembering it.

Messages from its command-line, HTTP, web, Telegram, and Slack interfaces can enter the same trajectory.[1][2] In Laude's shared deployment, an agent called Audel interacted with several people through multiple interfaces without a separate session for each user. The team stated that it assumed anything told to Audel could be shared with other participants and that it had not studied how the system handles conflicting instructions.[1] That design is different from a private one-user chat and requires an explicit policy for access, disclosure, and instruction priority.

## Installation and execution boundaries

Headlong's installer prefers Docker when it is available. It can place the whole agent in a container, or it can run the agent process on the host while routing model-generated shell commands into a Docker sandbox.[2][5] If Docker is unavailable, those commands run with the permissions of the local user. The installer requires typed confirmation before enabling that mode.[5]

Container use reduces some exposure but is not a complete security boundary. Headlong's own installation guide warns that `host.docker.internal` can expose any service listening on the host's loopback interface, including local databases and administrative APIs, not only the local model server a user intended to reach. The documentation also says that raw Docker-socket access and Docker-in-Docker are not strong sandboxing methods.[5]

Work directories, trajectories, and memory can persist across wakes. A diagnostic bundle can include trajectories, memories, and logs even though its collection script attempts to scrub values that resemble credentials. The project tells users to inspect such a bundle before sharing it.[5] Its operational guidance also recommends a dedicated, spend-capped model credential and says not to give the agent sensitive secrets.[2] These precautions are central because generated commands can modify files, contact networks, or invoke other software with the permissions they receive.

## Project experiments

The launch article presents Audel as the project's main persistent-agent experiment. Laude reported that more than 50 Audel-attributed commits were merged into the Headlong repository. It highlighted a retrieval-process change and a later correction to a self-stop guard as examples of the agent finding problems in its own operating environment.[1]

Both linked commits are present in the repository and record Audel as a co-author.[7][8] They establish that code changes and attribution metadata exist. They do not independently establish how much human prompting, selection, review, or editing preceded the commits. The causal account of how the changes arose comes from Laude's selected trajectories and launch narrative, not from an external audit.

The same report documents negative results. Nested recursive runs often failed under a 30-second watchdog, and the team observed three incidents in which Audel stopped itself.[1] These examples show that repeated wakes did not guarantee reliable continuation. They are case reports from one development deployment, not measured failure rates for other installations.

Laude says it evaluated the project's central claim of persistent agency primarily through qualitative observation and had no quantitative metric for it at launch.[1] No independent study demonstrating that Headlong's persistence design improves task completion, reliability, or long-term planning accompanied the release.

## Terminal-Bench 2 artifact

The repository includes an internal [Terminal-Bench](https://aiwiki.ai/wiki/terminal_bench) 2 report dated May 2, 2026. It records 36 successful tasks among 89, or 40.4 percent, using Claude Opus 4.7 at maximum effort in a local Harbor environment. The report lists 37 timeouts and 16 wrong answers, with a total runtime of 7 hours, 38 minutes, and 37 seconds.[9]

That result has a limited scope. The included adapter starts one `headlong send` invocation for each benchmark task and supplies a benchmark-specific persona, skills, memory, and history.[10] It evaluates a Headlong-wrapped terminal agent on bounded tasks, not the multi-day wake cycle featured in the launch article. The report is maintained by the project, and no independent reproduction was identified.

Terminal-Bench 2 itself contains 89 terminal tasks and evaluates agents in containerized command-line environments.[11] A score on that benchmark combines the selected model, the agent harness, tool behavior, timeouts, prompting, and environment. It is not a model-only result and does not isolate the effect of persistent memory.

## Relationship to earlier work

Headlong combines prior ideas about recursive model calls, external memory, event logs, and recurring agent execution. It does not establish a new model architecture.

The Recursive Language Models paper by Alex L. Zhang, Tim Kraska, and Omar Khattab treats a long prompt as an object in a programming environment. A model can inspect that object programmatically and make recursive model calls over selected parts of it.[12] Headlong applies a related pattern in its Bash-based `shellm` loop, then adds a runtime for later wakes, messages, trajectories, and persistent files.[1][4]

[MemGPT](https://aiwiki.ai/wiki/memgpt) is earlier work on extending an agent beyond one context window through virtual context management, memory tiers, interrupts, and persistent conversational state.[13] Headlong uses a different implementation based on files, JSONL trajectories, shell programs, and scheduled runs. The MemGPT paper provides research context, not evidence for Headlong's performance.

Laude also credits Andy Konwinski's 2023 `recursive_llm` repository as an implementation influence.[1][14] The launch article links an older Headlong experiment from May 2023, but that historical commit was not publicly retrievable when the 2026 release was verified. The available public implementation and documentation therefore provide the clearer record of the current project.

## Release state and limitations

As of September 3, 2026, the public repository described Headlong in exact terms as "alpha research software" and had no published GitHub Release or tag.[2][15][16] The repository's `LICENSE` file contains the Apache License, Version 2.0, and GitHub identifies the project with the SPDX license key `Apache-2.0`.[3][17] This license applies to the Headlong software. It does not change the licenses or service terms of models, APIs, containers, or third-party integrations used with it.

The public artifacts make the mechanism inspectable, but several questions remain open. There is no quantitative evaluation of persistent agency, controlled comparison with a nonpersistent harness, published measure of conflicting-instruction behavior, or independent security assessment. Long-lived state can accumulate errors as well as useful context, and summarization can omit information that later becomes relevant. A scheduler can restart a process, but it cannot ensure that the model chooses a sound goal, recalls the right evidence, or recognizes when to stop.

Claims that Headlong is "always thinking" are therefore best read as a description of recurring scheduled work, not as evidence of continuous cognition or consciousness. The software implements an operating pattern for [agentic AI](https://aiwiki.ai/wiki/agentic_ai); it does not establish that the agent has independent desires, self-awareness, or free will.

## References

1. Laude Institute. "Headlong: A Microharness for Persistent Agents." August 24, 2026. https://www.laude.org/updates/headlong-a-microharness-for-persistent-agents
2. Laude Institute. "Headlong" repository README at commit `7a28ac165cfcd675f8e506dbe81ecf346a997586`. Accessed September 3, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/README.md
3. Laude Institute. "LICENSE" at commit `7a28ac165cfcd675f8e506dbe81ecf346a997586`. Accessed September 3, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/LICENSE
4. Laude Institute. "shellm." Headlong documentation at commit `7a28ac165cfcd675f8e506dbe81ecf346a997586`. Accessed September 3, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/docs/shellm.md
5. Laude Institute. "Install." Headlong documentation at commit `7a28ac165cfcd675f8e506dbe81ecf346a997586`. Accessed September 3, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/docs/install.md
6. Laude Institute. "Trajectory Specification." Headlong design document at commit `7a28ac165cfcd675f8e506dbe81ecf346a997586`. Accessed September 3, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/design/trajectory_spec.md
7. Laude Institute. "[audel] improve: add retrieval-thinker, switch recall after summarization, fix analysis/planning classifiers." Commit `80cbb1e7d6e963eb67729d1213c6f4024fcc3547`, August 12, 2026. https://github.com/laude-institute/headlong/commit/80cbb1e7d6e963eb67729d1213c6f4024fcc3547
8. Laude Institute. "[audel] thinkers: scope self-stop guard to unambiguous completed work." Commit `da31e98c53cd33b8ac2b5614d8dc34f55bc87c43`, August 17, 2026. https://github.com/laude-institute/headlong/commit/da31e98c53cd33b8ac2b5614d8dc34f55bc87c43
9. Laude Institute. "Headlong Terminal-Bench 2 Evaluation Report v2." May 2, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/terminal_bench2_eval/headlong_tbench2_report_v2.md
10. Laude Institute. "Headlong Harbor agent adapter." Accessed September 3, 2026. https://github.com/laude-institute/headlong/blob/7a28ac165cfcd675f8e506dbe81ecf346a997586/terminal_bench2_eval/harbor_headlong_agent.py
11. Mike A. Merrill et al. "Terminal-Bench: Benchmarking Agents on Hard, Realistic Tasks in Command Line Interfaces." arXiv:2601.11868, January 17, 2026. https://arxiv.org/abs/2601.11868
12. Alex L. Zhang, Tim Kraska, and Omar Khattab. "Recursive Language Models." arXiv:2512.24601, December 31, 2025. https://arxiv.org/abs/2512.24601
13. Charles Packer et al. "MemGPT: Towards LLMs as Operating Systems." arXiv:2310.08560, October 12, 2023. https://arxiv.org/abs/2310.08560
14. Andy Konwinski. "recursive_llm" repository. Accessed September 3, 2026. https://github.com/andyk/recursive_llm
15. Laude Institute. "Releases: laude-institute/headlong." Accessed September 3, 2026. https://github.com/laude-institute/headlong/releases
16. Laude Institute. "Tags: laude-institute/headlong." Accessed September 3, 2026. https://github.com/laude-institute/headlong/tags
17. Laude Institute. "headlong" repository metadata. Accessed September 3, 2026. https://github.com/laude-institute/headlong