laude-institute/headlong

Headlong – 持続的なAIエージェント向けのBashベースのマイクロハーネス

何であるか

• 自分のマシン（またはDocker内）で継続的に思考するAI「エージェント」を実行できるオープンソースの研究フレームワーク。コアは約11K行のBashで構成され、再帰的言語モデル（RLM）を実装している：LLMがBashコマンドを生成し、システムが実行し、出力をモデルにフィードバックして繰り返す。
• 持続的エージェンシーを目的としている – だれも話しかけていなくてもエージェントは継続的に思考を生成し、いつ・どのように返信するかを自ら決定する。
• マルチユーザー対応：Slack、Telegram、またはWebダッシュボードから入力されたメッセージは、すべて1つの共有思考ストリームに統合され、複数の人が同じエージェントと会話できる。

主要概念

概念	意味
持続的エージェンシー	要求/応答のチェックリストではない。エージェントは「思考」（シェルコマンド）を継続的に生成するループを実行し、メッセージに返信する価値があると判断したときのみループを中断する。
再帰的言語モデル（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 – 1つ以上の思考プロセスを実行するディスパッチャ。
• 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            # 1回のメッセージを送信し、返信を待つ
  ada                  # インタラクティブチャットセッションを開く
  ada dash             # Webダッシュボードを起動（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_* 変数をexport）し、エージェントを再起動する。
• 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キーを使用し、エージェントをサンドボックス化（Dockerまたは明示的なコンテナ化）することを推奨。
• 作者らの報告によると、デフォルト設定下で1時間あたり1～2ドル程度のコストが発生する。モデルサイズやループ速度によって異なる。
• エージェントが無効状態になると、システムは指数関数的にバックオフするため、誰も話しかけていないときはコストが急激に低下する。

ドキュメントと追加リーディング

• philosophy.md – デザインの根拠と、小さな可合成Bashツールに関する「ケン・トマソン」哲学。
• docs/shellm.md – RLMループ、コンテキスト処理、Dockerサンドボックスの詳細解説。
• docs/install.md – すべてのインストールオプション、CIフレンドリーな非対話型インストール、専用サーバーでの実行方法。
• AGENTS.md – アイデンティティ（キャラクター）の管理、ログの確認、ヘルスチェックの方法。
• web/, slack/, telegram/ – ダッシュボードおよびチャットブリッジのソースコード。

ライセンス

• Apache 2.0（© 2026 Laude Institute）。

---

結論：Headlongは研究用の高品質なBash中心のフレームワークであり、継続的な自律的推論、マルチユーザー対応、自己修正コードを可能にするLLM駆動エージェントを自宅のハードウェアで構築できる。意図的に軽量で、検査しやすく、LLMがツール呼び出し層を経由せずに直接シェルコマンドを生成・実行するという思想に基づいている。開発者が自前ハードウェアで持続的AIエージェントを実験したい場合に最適。全体のスタックは透明で編集可能である。