Headlong is an open-source agent microharness whose core is about 10K lines of Bash. Its defining property is persistent agency: the agent keeps thinking between external interactions in a self-guided loop modelled on an inner monologue. A message from a person does not start a session; it lands in the agent's thought stream as one more observation, and the agent decides whether and when to respond. Given a name and a personality, the agent sets its own interests and priorities, starts projects, and pings people when it has something to say.
At the centre is shellm, a Bash implementation of a recursive language model (RLM). The agent thinks by writing shell commands, running them, and reading the output, so Bash is the only tool system; curl is the HTTP client and jq the JSON processor. The surrounding tools are small executables that compose through pipes, files, and environment variables: llm (a multi-provider CLI for Anthropic, OpenAI, Gemini, and OpenRouter), traj (trajectory operations), context (renders a trajectory into a messages array), thinkers (the dispatcher-run thought processes), mem and skills (a file-based memory store and SKILL.md abilities), and recap.
An agent's trajectory is a DAG of append-only JSONL files with fork and merge, and context is a projection of it: the whole trajectory stays in context at exponentially decaying resolution, with recent entries verbatim and older ones progressively summarised, so nothing is compacted away in place and raw entries can be retrieved on demand. Subagents see their ancestors' trajectories. Self-improvement works by fork, test, merge: an agent forks the Headlong codebase, changes something, runs, and the change is merged back or discarded.
One agent is shared by a whole team over Slack, Telegram, and a chat app, with every conversation landing in the same single stream and no per-user sessions, so anything told to the agent should be assumed visible to everyone who talks to it. A web dashboard shows the mind running. Generated code sandboxes itself into a Docker container when Docker is available, with a host-side broker enforcing policy, and the whole agent can run in a container. The thinking rate backs off exponentially when nobody is talking and resets when a message arrives; at the project’s reference settings, background thinking costs $1 to $2 an hour. Headlong is alpha research software, and a dedicated spend-capped API key is advised because the agent runs real shell commands around the clock.
Features
- Persistent agency: a self-guided thought loop that continues without external input; messages arrive as observations
- shellm RLM core: the model writes Bash, the harness runs it and feeds back the output, repeatedly
- Multi-provider llm CLI: Anthropic, OpenAI, Gemini, and OpenRouter behind one interface
- Trajectory DAG: append-only JSONL files with fork and merge, explorable down to any single step
- Tiered context compaction: the full trajectory at decaying resolution, with raw entries retrievable
- Ancestor visibility: subagents see why they were created and what the parent already tried
- Shared single mind: Slack, Telegram, and chat-app bridges feed one timeline with no per-user sessions
- Docker sandboxing: generated code runs in a container via a brokered facade, or the whole agent runs in one
- Memory and skills: file-based mem store and SKILL.md-based procedures
- Self-improvement by fork: the agent forks the codebase, tests a change, and merges or discards it
- Dashboard and tooling: a web dashboard, shellm-explore run-tree reports, a bugreport bundle, and a headlong-killall panic button
- Adaptive thinking rate: exponential back-off when idle, reset on incoming messages
