Who headlong is for#
AI researchers prototyping persistent agency
Headlong was built to prototype persistent agency and to surface design challenges that only emerge when an agent runs continuously for weeks. Researchers studying autonomous AI behavior, inner monologue models, or recursive language models can run a live instance and observe real behavior from the full DAG trajectory log.
Skip if:
You need production-ready, audited, compliant software. Headlong is alpha research software and the Laude team explicitly recommends against sharing sensitive secrets with the agent.
Developer teams sharing one agent over Slack and Telegram
Headlong connects to Slack and Telegram simultaneously, with every conversation landing in one thought stream. Teams that want an AI collaborator that follows multiple projects, connects different team members, and pings whoever is most relevant can self-host one shared agent on their own server.
Skip if:
Your team requires per-user session isolation or private conversations. The single-stream model means anything shared with the agent is accessible to all team members who talk to it.
Engineers studying or modifying agent internals
The harness is fewer than 10,000 lines of Bash and the trajectory is a full auditable log of every thought and action. Engineers who want to understand why an agent made a specific decision, modify the compaction algorithm, or experiment with the thought loop can do so without fighting an opaque framework.
Skip if:
You need a visual workflow builder or point-and-click agent configuration. Headlong requires Bash familiarity and comfort operating alpha software with no GUI.
The problem it solves#
Reactive agent harnesses are the default because they are simple: give the agent a task, wait for it to complete, let it sleep. Some harnesses add cron jobs that wake the agent on a schedule to run a fixed checklist. Neither model produces an agent that acts on its own initiative, maintains ongoing projects, or pings team members with unprompted updates.
The deeper pain is that agents with no continuous inner life make poor collaborators. They cannot notice something worth mentioning if nobody asked. They cannot decide an old task needs revisiting. They cannot catch a colleague's mistake while nobody is watching. For teams who want AI that behaves less like a service and more like a participant, the reactive model is a structural limitation, not just an inconvenience.
How it solves it#
Persistent Agency Loop
A Thinker process runs an infinite loop, calling an LLM to generate the next thought. A thought can be part of the agent's inner monologue or trigger a shell command that runs immediately. The loop continues even when nobody is talking to the agent, backing off exponentially when idle and resetting as soon as a message arrives.
Shellm: Bash Recursive Language Model
shellm is a Bash implementation of a recursive language model. The LLM writes Bash scripts; shellm runs them and feeds the output back as context. No custom tool system is needed: curl handles HTTP, jq handles JSON, and any installed binary is available. The entire core is fewer than 10,000 lines of Bash.
Multi-Player Single Thought Stream
One agent, one mind, many people. There are no per-user sessions; every message from every team member lands as one more observation in the agent's single thought stream. The agent decides who to reply to and when, following multiple ongoing conversations from a single timeline. Supported channels include Slack and Telegram.
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, giving a persistent agent effective long-term memory across continuous multi-week operation.
Docker Sandboxing by Default
When Docker is available, generated code is sandboxed into a container with container reuse to keep restarts cheap. Local host mode works too, but Docker is recommended because the agent runs real shell commands. A brokered Docker setup keeps the policy server outside the agent's own environment.
Strengths and trade-offs#
Strengths
- Readable and Modifiable CoreThe entire harness is fewer than 10,000 lines of Bash, small enough to read end to end and modify with confidence. Every component (thinkers, shellm, trajectory, context) is a plain executable the agent itself can inspect and change. Unlike agent frameworks that hide complexity behind SDK abstractions, the harness is transparent by design.
- Apache 2.0 with Full Self-HostingApache 2.0 means you can run headlong on your own infrastructure, fork it, modify it, and use it commercially with no licensing fees. Compared to commercial platforms like Relevance AI or Microsoft Copilot Studio, there are no per-seat charges, no managed service fees, and no dependency on a vendor's continued operation.
- Demonstrated Agent Self-ModificationThe Laude team's agent (Audel) has contributed over 50 commits back to the main headlong repository by working in its own fork and merging successful changes. Audel autonomously diagnosed a broken recall process, rewrote the code, verified the fix end to end, and committed the result, which was merged as commit 80cbb1e.
- Multi-Provider LLM SupportThe llm tool supports Anthropic, OpenAI, Gemini, and OpenRouter behind a single interface. Switching providers or adding a new one does not require changes to the agent's Bash core. A spend-capped dedicated API key is recommended since the agent consumes tokens continuously.
Trade-offs
- -Alpha Software with Real Shell Access RiskHeadlong is explicitly alpha research software. The agent runs real shell commands on your machine or in a container, and the README recommends a dedicated, spend-capped API key and Docker sandboxing. An unsandboxed host install means the agent has full access to your machine as your own user account.
- -Continuous API CostBecause the agent thinks around the clock, API costs accumulate continuously. At the settings the Laude team uses, this runs $1 to $2 per hour. Cost backs off exponentially when nobody is conversing with the agent, but there is no zero-cost pause state without explicitly stopping it via the stop command.
- -Recursive Sub-Runs Are FragileThe recursive shellm sub-run feature (spawning copies of itself for sub-problems) is the most complex capability and also the most fragile. The Laude team's own agent mostly stopped using it after the 30-second inactivity watchdog killed silent sub-runs during early experiments. The watchdog has since been revised but the behavior remains experimental.
- -No Per-User Session IsolationOne shared agent means no hard walls between people. Anything told to the agent can surface in conversations with other team members. The Laude team explicitly notes that their agent Audel is bad at keeping secrets, and that all information shared with it should be treated as shared with everyone who talks to it.
headlong vs alternatives#
headlong vs Relevance AI
Relevance AI is a managed, no-code platform for building AI agents that run tasks on demand. Headlong takes the opposite approach: a self-hosted, code-native harness where the agent runs continuously, not on demand.
| Feature | headlong | Relevance AI |
|---|---|---|
| Hosting | Self-hosted | Managed cloud |
| License | Apache 2.0 | Proprietary |
| Agent model | Persistent, continuous | Reactive, task-triggered |
| Setup | Bash familiarity required | No-code |
| LLM providers | Anthropic, OpenAI, Gemini, OpenRouter | Managed selection |
| Cost | LLM API cost only | Platform fees plus LLM cost |
Headlong wins when you want an agent that operates without being triggered, can modify its own tooling, and must run on your own infrastructure for privacy or cost control. The no-code accessibility of Relevance AI is a genuine advantage for teams who want agents without engineering overhead. Relevance AI is the better choice if you need visual workflow design, managed infrastructure, and a polished multi-agent collaboration layer without writing Bash.
headlong vs Microsoft Copilot Studio
Microsoft Copilot Studio is an enterprise agent-building platform that connects to Microsoft 365, Teams, and the Power Platform. Headlong has no enterprise integrations, no GUI, and full Apache 2.0 freedom.
| Feature | headlong | Microsoft Copilot Studio |
|---|---|---|
| Hosting | Self-hosted | Microsoft cloud |
| License | Apache 2.0 | Proprietary |
| Agent model | Persistent, self-guided | Reactive, topic-driven |
| Microsoft 365 integration | None | Native |
| Setup | Bash familiarity required | Low-code GUI |
| Target user | Researchers, engineers | Enterprise IT, business users |
Headlong is the right choice for teams that need full infrastructure control, want to study or modify agent internals, and do not depend on Microsoft cloud services. Copilot Studio is the right choice for enterprises already in the Microsoft 365 ecosystem who need managed compliance, Teams integration, and a support contract. The two tools address fundamentally different deployment contexts rather than competing directly on features.
Install and self-host#
Install headlong with the one-line curl installer; Docker is recommended to sandbox the agent's shell commands.
```bash
curl -fsSL https://headlong.ai/install.sh | bash
```What it's built on#
- Languages
- PythonRustSwiftTypeScript
- Frameworks
- FastAPIReact
FAQ#
Is headlong suitable for production use?
No, not yet. The README explicitly labels headlong alpha research software. The Laude team recommends running it in a Docker sandbox with a dedicated, spend-capped API key, and advises against sharing sensitive secrets with the agent. It is suited for research, prototyping, and exploration of persistent agency rather than production workloads.
What LLM providers does headlong support?
Headlong supports Anthropic, OpenAI, Gemini, and OpenRouter through its llm CLI tool, which provides one interface across all four providers. You can switch or mix providers without changing the agent's core Bash executables. A dedicated, spend-capped key is recommended since the agent uses tokens continuously.
How much does running headlong cost?
The software is free (Apache 2.0 licensed) to self-host. The ongoing cost is LLM API usage, which accumulates continuously since the agent thinks around the clock. At the settings the Laude team uses with their agent, this comes to $1 to $2 per hour. Idle cost backs off exponentially when nobody is conversing with the agent.
How is headlong different from workflow automation tools like Zapier or n8n?
Workflow tools are reactive: they execute a defined step sequence when a trigger fires. Headlong runs a continuous inner loop with no predefined checklist. The agent decides what to think about, starts its own projects, and takes action without any external trigger. It replaces scheduled task runners and workflow graphs with an agent that behaves more like a participant than a pipeline.
Can multiple people share one headlong agent?
Yes, and this is a deliberate design. One agent, one thought stream, many people. Every conversation from every team member lands as an observation in the agent's single thought stream, and the agent decides who to reply to and when. There is no per-user session isolation: treat anything you tell the agent as shared with everyone who talks to it.
Similar open-source tools#
OpenMausBot
Your AI agent team in a chat app, local-first and MIT licensed
rakazo
AI teammates you own: your keys, your model, your machine.
Hermes Agent
Self-hosted AI agent with persistent memory, multi-channel chat, and model choice across OpenAI, OpenRouter, and custom endpoints.
Open Agents
Spawn coding agents that run infinitely in parallel cloud VMs
vexa
Self-hosted meeting bot API for Meet, Teams, Zoom, and Jitsi
LiveCaptions-Translator
Real-time audio translation for Windows, powered by LLMs