laude-institute/headlong

An open source agent microharness featuring persistent agency and recursive LLMs. Of bash, by bash, for bash; it's shells all the way down.

Headlong – 지속적인 AI 에이전트를 위한 Bash 기반 마이크로 하드웨어

무엇인가요

자신의 컴퓨터(또는 Docker 내)에서 지속적으로 생각하는 AI "에이전트"를 실행할 수 있는 오픈소스 연구 프레임워크입니다. 핵심은 약 11K 줄의 Bash로 구성된 재귀적 언어 모델(RLM)을 구현한 것으로, LLM이 Bash 명령어를 작성하고, 시스템이 실행한 후 출력을 다시 모델에 피드백하여 반복합니다.
지속적인 에이전시를 목표로 합니다 – 아무도 대화하지 않아도 에이전트는 지속적으로 생각을 생성하며, 언제, 어떻게 응답할지를 스스로 결정합니다.
다중 사용자 상호작용을 지원합니다: Slack, Telegram, 또는 웹 대시보드에서 들어오는 메시지는 모두 하나의 공유 사고 스트림으로 통합되어 여러 사람이 동일한 에이전트와 대화할 수 있습니다.

핵심 개념

개념	의미
지속적인 에이전시	요청/응답 체크리스트가 아님. 에이전트는 "사고"(쉘 명령어)를 지속적으로 생성하는 루프를 실행하며, 메시지에 응답할 가치가 있다고 판단할 때만 루프를 중단합니다.
재귀적 언어 모델 (shellm)	LLM은 현재 컨텍스트를 받고, Bash 스크립트 조각을 반환합니다. 이 조각은 실행되며, 그 stdout/stderr는 다음 컨텍스트의 일부가 됩니다. 모델이 사용하는 유일한 "도구"는 Bash 자체입니다.
궤적 (Trajectory)	에이전트가 실행한 모든 명령어, 출력, 메타데이터를 기록하는 추가 전용 JSON-L DAG입니다. 전체 기록은 탐색, 분기, 병합, 요약이 가능합니다.
단계적 컨텍스트 압축	최근 항목은 그대로 유지되며, 오래된 항목은 점진적으로 요약되어, 토큰 제한을 넘지 않으면서도 장기 기억을 효율적으로 유지할 수 있습니다.
서브에이전트	에이전트는 부모의 궤적을 상속하는 자식 에이전트를 생성할 수 있어, 계층적 프로젝트와 자기 개선이 가능합니다.
Docker 사전	기본적으로 설치 프로그램은 에이전트를 컨테이너 내에서 실행하여 생성된 명령어를 호스트에서 격리합니다. 호스트 설치는 가능하지만 명시적인 "예"가 필요합니다.

주요 도구 (모두 작고 작은 Bash 실행 파일)

shellm – RLM 엔진(핵심 루프).
llm – Anthropic, OpenAI, Gemini, OpenRouter, 또는 어떤 OpenAI 호환 로컬 서버(Ollama, llama.cpp, vLLM 등)에도 사용 가능한 통합 CLI.
traj – 궤적 DAG 조작(추가, 분기, 병합).
context – 궤적을 단계적 압축을 포함한 LLM 호환 메시지 배열로 렌더링.
thinkers – 하나 이상의 사고 프로세스를 실행하는 디스패처.
mem / skills – 파일 기반 메모리 저장소와 재사용 가능한 기술 정의(Markdown로 설명된 절차).
headlong-web – 브라우저 대시보드로 사고를 실시간으로 관찰할 수 있습니다.
headlong-slack-bridge / headlong-telegram-bridge – 채팅 메시지를 에이전트의 관측으로 변환하는 연결기.
headlong-killall – 모든 Headlong 프로세스를 즉시 중지하는 패닉 버튼.

설치 및 시작 방법

# 1라인 설치 프로그램 (bash, git, curl, jq, Python 3, LLM API 키 필요)
curl -fsSL https://headlong.ai/install.sh | bash

설치 프로그램은 에이전트를 Docker 내에서 실행할지(권장) 또는 직접 호스트에서 실행할지 묻습니다.

설치 후 에이전트 이름에 따라 명령어가 생성됩니다 (예: ada).

ada hello            # 단일 메시지를 보내고 응답을 기다림
ada                  # 인터랙티브 채팅 세션 열기
ada dash             # 웹 대시보드 시작 (http://localhost:8080)
ada stop / ada start # 백그라운드 사고 루프 일시 정지 또는 재개

headlong-killall은 모든 것을 즉시 중지; status.sh는 실행 중인 프로세스를 보고; uninstall.sh는 설정을 제거합니다.

로컬 모델로 실행하기

OpenAI 채팅 완성 API를 구현하는 서버라면 어떤 것도 가능합니다 (Ollama, llama.cpp, vLLM, LM Studio 등).
~/.headlong/.env에 프로바이더, URL, 모델을 설정하거나 HEADLONG_* 변수를 내보내고 에이전트를 재시작합니다.

Ollama 예시:

export HEADLONG_PROVIDER=local
export HEADLONG_LOCAL_URL=http://127.0.0.1:11434/v1
export HEADLONG_LOCAL_MODEL=qwen3:8b
curl -fsSL https://headlong.ai/install.sh | bash

비용 및 안전성 참고사항

에이전트가 지속적으로 실제 쉘 명령어를 실행하므로, 전용이고 지출 제한이 있는 API 키를 사용하고 에이전트를 사전화(도커 또는 명시적 컨테이너화)하는 것이 좋습니다.
저자들은 기본 설정 하에서 시간당 1~2달러 정도의 비용이 발생한다고 보고하며, 모델 크기와 루프 속도에 따라 다릅니다.
에이전트가 비활성 상태일 때 시스템은 지수적으로 백오프하므로, 아무도 대화하지 않을 때 비용이 급격히 감소합니다.

문서 및 추가 읽기

philosophy.md – 디자인 철학과 작은, 조합 가능한 Bash 도구에 대한 "켄 톰슨" 철학.
docs/shellm.md – RLM 루프, 컨텍스트 처리, Docker 사전화에 대한 심층 설명.
docs/install.md – 모든 설치 옵션, CI 친화적인 비대화형 설치, 전용 서버에서 허브를 실행하는 방법.
AGENTS.md – 아이덴티티(성격) 관리, 로그 보기, 헬스 체크 방법.
web/, slack/, telegram/ – 대시보드 및 채팅 브리지의 소스 코드.

라이선스

결론: Headlong은 연구 수준의, Bash 중심의 프레임워크로, 지속적인 자율적 추론, 다중 사용자 상호작용, 자기 수정 코드를 가능하게 하는 LLM 기반 에이전트를 구축할 수 있습니다. 의도적으로 가볍고, 검사 가능하며, LLM이 별도의 도구 호출 계층을 거치지 않고 직접 쉘 명령어를 생성하고 실행해야 한다는 아이디어에 기반합니다. 개발자들이 자신의 하드웨어에서 지속적인 AI 에이전트를 실험하면서 전체 스택을 투명하고 편집 가능한 상태로 유지하고 싶은 경우에 적합합니다.

laude-institute/headlong

Headlong – 지속적인 AI 에이전트를 위한 Bash 기반 마이크로 하드웨어

관련