Headlong - An open-source AI Agent micro-framework from the Laude Institute

What is Headlong

Headlong is an open-source AI Agent micro-framework from the Laude Institute, with a core of only about 10,000 lines of Bash scripts. The framework's biggest breakthrough is persistent agency: the Agent never "sleeps," requires no wake-up or scheduled tasks, and continuously thinks autonomously and self-drives like a human's inner monologue. Headlong can autonomously diagnose bugs, write fix code, submit commits, and collaborate with the entire team via Slack/Telegram, more like a shared digital colleague.

Headlong's main features

Persistent agency: The Agent never sleeps and continuously thinks autonomously like a human's inner monologue, with no need for wake-ups or scheduled tasks.
shellm engine: The core recursive language model, which sends context to the LLM, runs the returned Bash commands, and loops repeatedly.
traj trajectory system: Uses an append-only jsonl DAG to fully record the Agent's entire history of thoughts and actions, supporting fork and merge.
Layered context compression: The entire trajectory always remains in context, but is presented at exponentially decaying resolution.
thinkers scheduler: Runs multiple reactive thinking processes and autonomously decides what to think about next and when to respond to humans.
mem memory storage: A file-based memory system that lets the Agent accumulate experience and continuously build up knowledge.
skills capability reuse: Saves and invokes processing workflows for specialized tasks through SKILL.md files.
Multi-platform collaboration: Supports integration with Slack, Telegram, and a built-in chat app, with the entire team sharing the same Agent thought stream.
Docker sandbox: Generated code runs in a container by default, isolating risk and ensuring host security.
Self-improvement: The Agent can fork the codebase to modify and test autonomously, merging back to the main branch on success and discarding on failure.
Real-time Dashboard: Observe the Agent's thought stream, inner monologue, and action logs in real time in the browser.
Multi-model support: Compatible with LLM providers such as Anthropic, OpenAI, Gemini, and OpenRouter through a unified CLI interface.

Headlong's technical principles

Persistent Agency: Headlong's core design frees the Agent from the traditional request-response model by continuously generating ideas through a never-ending thinking loop. Observations are injected into its thought stream, and the Agent autonomously decides priorities, when to respond, and whether to initiate new tasks; the background thinking rate decays exponentially when there is no human interaction to control costs.
shellm recursive language model: The framework uses Bash as the Agent's "native language." Through the shellm engine, it sends context to the LLM, executes the returned Bash commands, and reads the output, forming a "think-execute-observe" recursive loop. Because LLMs naturally understand Bash, existing tools such as curl and jq directly serve as HTTP clients and JSON processors, with no need for an additional tool abstraction layer.
Trajectory as DAG: Agents' full history of thought and action is recorded as an append-only jsonl file, forming a directed acyclic graph. This design supports fork (branching experiments) and merge (merging results), enabling the agent to review the original state at any moment, and also provides a version-control foundation for self-improvement—the agent can fork a code repository to modify and test it, then decide whether to merge.
Tiered Context Compaction: To address the context window limitations of long trajectories, Headlong uses a tiered projection mechanism with exponential decay. The most recent entries retain their complete original text, while older entries are progressively summarized. These tiers also serve as indexes, so the agent can retrieve the original content at any time when details are needed, ensuring that the trajectory across the entire lifecycle is always "in context" without being lost.
Thinkers: The thinkers module manages multiple reactive thinking processes, coordinating different types of thinking activities, from responding to human messages to autonomously initiated observations and plans. The scheduler ensures that the agent handles input from multiple channels such as Slack and Telegram within a single thinking stream, and autonomously decides the next optimal action based on the current state and memory.
Docker Sandbox Execution: To ensure safety, code generated by the agent runs in a Docker container by default, providing a controlled execution environment through shellm-docker. Containers can be reused to reduce restart overhead. It can also run locally without Docker, but explicit confirmation is required, ensuring that potentially dangerous shell commands do not directly harm the host system.

Follow WeChat and reply "open source" to join theAI Open Source Project Community Group

How to Use Headlong

Install the framework: Run curl -fsSL https://headlong.ai/install.sh | bash One command completes the installation. During the process, it will interview you and create your first agent identity.
Prepare the environment: Make sure bash 3.2+, git, curl, and jq are installed on your system, and have an Anthropic/OpenAI/Gemini/OpenRouter API Key ready.
Start the agent: After installation is complete, the name you gave the agent (such as ada) directly becomes a system command and is available at any time.
Send a message: Run ada hello to send a single message to the agent and wait for a reply. The message is injected into its thinking stream rather than starting a new session.
Continuous chat: Run ada to enter interactive mode and have a multi-turn conversation with the agent, with all content flowing into the same thinking stream.
Pause and resume: Run ada stop to pause the agent's thinking loop,ada start to resume its autonomous operation.
Observe thinking: Run ada dash to open the Dashboard in a browser and watch the agent's inner monologue, observations, and action logs in real time.
Secure sandbox: It is recommended to run the installation process through Docker, so that code generated by the agent automatically executes in an isolated container, ensuring host security.
Emergency brake: If something goes wrong, run headlong-killall to terminate all Headlong-related processes on the machine with one command.
Submit feedback: Run ada bugreport to automatically package logs and trajectory files, redact API Keys, and use them for issue reports.
Run Docker Standalone: Can be directly executed docker run with the installation script to run the Agent persistently in an independent container.
Uninstall and clean up: Run curl -fsSL https://headlong.ai/uninstall.sh | bash to completely remove all installed content.

Headlong's core advantages

Persistent agency: The Agent never sleeps, continuously thinking autonomously and self-driven like a human inner monologue.
Minimalist architecture: The core is only about 10,000 lines of Bash scripts; the LLM thinks directly in Bash, with no additional tool abstraction layer.
Complete memory retention: Layered context compression keeps the Agent's entire lifecycle trajectory always "in context," with more detail for recent events and less for distant ones, while raw details remain retrievable at any time.
A shared teammate for the team: One thought stream connects to Slack, Telegram, and built-in chat, letting the entire team share the same Agent that proactively reaches out to communicate.
Self-iterative evolution: The Agent can fork the codebase to modify and test it autonomously, and merge back to the main branch on success; Laude has already accepted 50+ of its commits.
Native secure sandbox: Generated code runs in a Docker container by default, isolating potential risks with no complex permission configuration required.
Intelligently controllable cost: Background thinking speed decays exponentially with no interaction, running on demand at about $1-2/hour, and instantly returns to full speed when a message arrives.

Headlong's project address

Project website：https://www.laude.org/updates/headlong-a-microharness-for-persistent-agents
GitHub repository：https://github.com/laude-institute/headlong

Comparison of Headlong with similar competitors

Comparison dimension	Headlong	AutoGPT
Core architecture	~10,000 lines of Bash, a minimalist micro-framework; the LLM natively thinks in Bash	Python modular framework; tools require secondary wrapping, and the architecture is relatively heavy
Operation mode	Persistent agency, never sleeps, continuously autonomous thinking in the style of an inner monologue	Task-driven, decomposes and executes after a goal is input, and sleeps once completed
Interaction model	Messages are injected into the thought stream; the Agent decides on its own when to respond and whether to proactively contact you	Clear session boundaries: user inputs a goal → Agent executes → returns result
Memory mechanism	Complete trajectory DAG + layered context compression, traceable across the full lifecycle	Vector database + short-term memory; long history is easily lost or retrieved inaccurately
Tool system	Zero abstraction; system tools such as curl/jq are native capabilities	Requires predefined tool functions and depends on plugin extensions
Team collaboration	A single thought stream; Slack/Telegram multi-platform share one Agent	Single-user sessions, with no native multi-person sharing mechanism
Self-improvement	Built-in fork/test/merge workflow; has already contributed 50+ commits	Can generate code but has no built-in version control and verification loop
Deployment threshold	One-line command installation, Docker sandbox enabled by default	Requires configuring a Python environment, vector database, API Key, etc.

Headlong's application scenarios

24/7 intelligent code review and autonomous repair: The Agent continuously monitors the codebase, autonomously discovers a pipeline bug in the early morning, diagnoses it, writes fix code, runs end-to-end verification, and submits a commit, all without human intervention.
Cross-platform team collaboration hub: Connects to Slack/Telegram as a shared digital colleague, observes each member's work progress, proactively connects relevant people, summarizes project status, and pushes key information at appropriate times.
Continuous infrastructure operations monitoring: Continuously reads server logs and metrics, autonomously identifies anomalous patterns, executes remediation scripts in containers, and upgrades from passive alerting to proactive self-healing.
Personal knowledge management and deep research: Continuously reads, summarizes, and associates scattered information, autonomously establishes priorities based on interests, proactively pushes important findings, and builds a searchable personal knowledge trail.
Automated community maintenance for open-source projects: Automatically categorizes Issues, reviews PRs, updates documentation, and replies to common questions, maintaining project health 24/7 and reducing the burden on maintainers.