headlong

Persistent-agency agent harness in ~10K lines of Bash: it keeps thinking between messages, thinks by writing shell commands, and one shared mind serves a whole team over Slack or Telegram.

1,005 95 Shell Apache-2.0updated today

agents memory

View on GitHubDispute this mapping →

Curator's take

Read this if you think harnesses have converged. Headlong drops the tool system entirely — the agent thinks by writing Bash, so `curl` is the HTTP client and `jq` the JSON parser — and it never stops: your message lands in an ongoing thought stream as one more observation, and the agent decides whether to answer. The trajectory is a fork/merge DAG of jsonl files, and context is a projection of it at exponentially decaying resolution, so nothing is compacted away in place. Laude Institute research alpha: it runs real shell commands around the clock at $1-2/hour, so use a spend-capped key and let the installer put it in Docker. Not the pick if you want a reactive, per-user, request/response coding agent — that mode exists but the whole design is aimed elsewhere.

Mapped by ShipWithAI editors · links verified

README.md

██  ██ █████  ████  █████  ██     ████  ██  ██  ████               ██
██  ██ ██    ██  ██ ██  ██ ██    ██  ██ ███ ██ ██           ██   ██
██▀▀██ ████  ██████ ██  ██ ██    ██  ██ ██▀███ ██ ███     ██   ██
██  ██ ██    ██  ██ ██  ██ ██    ██  ██ ██ ▀██ ██  ██   ██   ██
██  ██ █████ ██  ██ █████  █████  ████  ██  ██  █████      ██

Headlong is an open source agent microharness, a complete agent harness with a core of about 10K lines of Bash. Headlong's defining feature is persistent agency. Your agent keeps thinking between external interactions in a self-guided loop inspired by human inner monologue. A message from a human doesn't start a session. It lands in the agent's thought stream as one more observation, and the agent decides if and when to respond. You give your agent a name and a personality, and it sets its own interests and priorities, starts its own projects, and pings you when it has something to say.

A Headlong agent is also built to be shared. A whole team can talk to one agent over Slack, Telegram, and a chat app, and every conversation lands in the agent's single stream of thoughts. The agent follows what different people are working on, connects them, and pings whoever seems most relevant. Sharing one agent is fun, because it behaves more like a person than a service.

At the heart of Headlong is shellm, a Bash implementation of a recursive language model (RLM). The agent thinks by writing shell commands, running them, and reading the output. No tool system besides Bash is needed.

Get started

One line installs everything, interviews you to bring a Headlong agent to life, and opens a dashboard where you can watch its mind run:

curl -fsSL https://headlong.ai/install.sh | bash

You'll need bash 3.2+, git, curl, jq, and an LLM API key (Anthropic, OpenAI, Gemini, or OpenRouter); the dashboard also needs uv and bun or node, and the installer offers to fetch those.

Headlong is alpha research software. Use a dedicated, spend-capped key, because your agent runs real shell commands and thinks around the clock. With Docker running, the installer offers to keep the whole agent in a container, or to install on your machine with the agent's commands sandboxed in a container (an unsandboxed host install exists too, behind an explicit yes, and is not recommended). Without Docker the commands would run directly on your machine as you, so the installer stops and asks for an explicit yes before setting that up. How much the background thinking costs depends on how quickly the agent loops and which model backs it. The rate of thinking backs off exponentially when nobody is talking to the agent and resets the moment a message arrives. At the settings we run our agent with, it comes to $1 to $2 an hour.

The agent's name becomes a command:

ada hello            # one message, wait for the reply
ada                  # chat
ada stop / ada start # pause / resume its mind
ada dash             # open the dashboard
ada bugreport        # bundle logs + trajectory (keys scrubbed) for a bug report

headlong-killall stops every Headlong process on the machine if you need a panic button. curl -fsSL https://headlong.ai/status.sh | bash shows what is installed and running; curl -fsSL https://headlong.ai/uninstall.sh | bash removes it all (details in docs/install.md).

The container flow the installer offers is this, and you can also run it yourself:

docker run -it --name headlong --restart unless-stopped -p 8080:8080 buildpack-deps:curl \
  bash -c 'curl -fsSL https://headlong.ai/install.sh | bash; exec bash'

Details, no

Continue your stack

What teams reach for next — and why each earns a place beside headlong. Ranked by curator confidence.

Pairs well with

mirage

Unified virtual filesystem for AI agents — mounts S3, Slack, Gmail, Postgres and ~50 backends as one tree so any bash-speaking LLM can grep and pipe across services. Snapshotable, embeddable.

Why it fitsHeadlong's agent has no tools besides the shell, so anything you can mount is instantly usable. Mirage mounts S3, Slack, Gmail, Postgres and ~50 backends as one filesystem tree — every service becomes something the agent can already `ls`, `grep` and pipe.

rtk

Rust CLI proxy compressing dev-command output 60-90% before your agent reads it — git, tests, linters, docker, 100+ commands; hooks auto-rewrite bash calls. Single binary, <10ms overhead.

Why it fitsEvery thought is a shell command, so raw command output is the dominant context cost. RTK compresses git/test/lint/docker output 60-90% before it lands in the trajectory — a direct saving on a mind that loops around the clock.

spec-ptc

Speculative programmatic tool calling: while the model is still streaming a code block, the harness launches the tool and sub-LLM calls it is about to make, so blocking calls overlap generation.

Why it fitsSame lineage: Headlong's `shellm` core is a Bash implementation of a Recursive Language Model, and sPTC is the speculation technique built for RLM-shaped harnesses by the author of the RLM writeup Headlong cites. The payoff applies wherever sub-LLM calls inside a generated block dominate wall-clock; wiring it into a Bash REPL means driving the sPTC daemon over its socket rather than the one-line Python patch.

Alternative to See all + compare →

picobot

A self-hosted personal AI agent in a single ~9MB Go binary — persistent memory, 16 tools + MCP, skills, cron/heartbeat, and Telegram/Discord/Slack/WhatsApp channels. Runs on a $5 VPS.

Why it fitsBoth are self-hosted always-on personal agents with persistent memory and IM channels. Picobot is a 9MB Go binary with 16 fixed tools that runs on a $5 VPS; Headlong is Bash all the way down, has no tool system, and thinks continuously instead of on triggers.

prime-agent

Self-improving coding/research agent around a Recursive Language Model: persistent IPython as the core tool, programmatic subagents, durable harness state it refines via evidence-backed /refine.

Why it fitsBoth are Recursive Language Model harnesses where the agent thinks in code rather than in tool-call JSON. Prime-agent uses a persistent IPython REPL and targets coding/research with evidence-backed self-refinement; Headlong uses Bash and targets open-ended persistent agency.

core

Self-hosted, always-on "personal AI OS": watches your apps, keeps a persistent memory graph, and acts autonomously within guardrails — a product, not a library for building agents.

Why it fitsSame ambition — an always-on agent that carries your context and acts on its own. Core is a product with a memory graph and guardrails; Headlong is 10K lines of shell you are expected to read, fork and point at your own machine.