Repolode
Submit
laude-institute

laude-institute/headlong

A bash-based agent harness where an always-on AI agent keeps thinking between messages and can be shared by a team over Slack or Telegram.

View on GitHubWebsite
Stars
1,272
Forks
135
Open issues
57
Last commit
2 days ago

What is it?

Headlong is an agent microharness with a core of about 11K lines of Bash. Its main idea is persistent agency: the agent keeps generating thoughts in a self-guided loop, and messages from people are added to that thought stream as observations. The agent decides whether and when to reply, and it can start its own projects and reach out when it has something to say.

The central engine, shellm, is a Bash implementation of a recursive language model. The agent thinks by writing shell commands, running them, and reading the output, with Bash as its only tool. Its trajectory is stored as append-only jsonl files forming a DAG that supports fork and merge, and older context is compacted in tiers while recent entries remain verbatim.

A single agent can be shared by a team through Slack, Telegram, and a web dashboard, with all conversations landing in one timeline. The project is alpha research software, and it is designed to run in Docker sandboxes, with support for OpenAI-compatible local model servers such as Ollama and llama.cpp.

Key features

  • 01Persistent agency: the agent keeps thinking between external messages and decides when to respond.
  • 02Bash-only tooling where the model thinks by writing and running shell commands.
  • 03Append-only jsonl trajectories stored as a DAG with fork and merge.
  • 04Tiered context compaction that summarizes older entries while keeping recent ones verbatim.
  • 05Slack, Telegram, and web dashboard integrations sharing one agent.
  • 06Docker sandboxing for generated code, with local mode available.
  • 07Support for Anthropic, OpenAI, Gemini, OpenRouter, and local OpenAI-compatible servers.

Use cases

  • Running a long-lived personal or team assistant that follows ongoing work and pings people when relevant.
  • Experimenting with minimal, readable agent harnesses built on shell tools.
  • Hosting a shared agent that a team can chat with through Slack or Telegram.
  • Running a local LLM through Ollama or llama.cpp as the agent's model backend.

Quick start

  1. 1

    Run the official install script from the README

  2. 2

    Send your agent a test message

    ada hello
  3. 3

    Open the dashboard to watch the agent think

    ada dash

Things to know

  • Headlong is alpha research software that changes frequently.
  • Agents run real shell commands, so you should run it in a sandbox such as Docker.
  • Background thinking costs about $1 to $2 an hour at the author's settings, so use a spend-capped API key.
  • It needs an LLM API key or a local model server to run.

In collections

Open-source AI agent frameworks & apps

Topics

#ai-agent#llm#bash#shell#recursive-language-model#docker#slack-bot#telegram-bot

FAQ

What is headlong?
A bash-based agent harness where an always-on AI agent keeps thinking between messages and can be shared by a team over Slack or Telegram. Headlong is an agent microharness with a core of about 11K lines of Bash. Its main idea is persistent agency: the agent keeps generating thoughts in a self-guided loop, and messages from people are added to that thought stream as observations. The agent decides whether and when to reply, and it can start its own projects and reach out when it has something to say.
Is headlong free to use? What license does it have?
headlong is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is headlong still maintained?
Actively maintained. The last commit to headlong was on Nov 5, 2026.
What can I use headlong for?
Running a long-lived personal or team assistant that follows ongoing work and pings people when relevant. Experimenting with minimal, readable agent harnesses built on shell tools. Hosting a shared agent that a team can chat with through Slack or Telegram. Running a local LLM through Ollama or llama.cpp as the agent's model backend.
How do I install headlong?
Run the official install script from the README Send your agent a test message: ada hello Open the dashboard to watch the agent think: ada dash
Where can I get headlong?
The source code and installation instructions are on GitHub: https://github.com/laude-institute/headlong

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects