TYPESCRIPT / OSS · CASE STUDY
headless_core.
AI Agentを、同じインターフェースで。
Codex、Claude Code、GrokなどのローカルCLIをアプリケーションから共通の方法で扱うための、Node.js向けコアライブラリです。
example.ts — headless_core
ILLUSTRATIVE CODE · SEE REPO FOR EXACT APIconst result = await core.run({
agent: { provider: 'codex' },
prompt: 'Build something',
onProgress: onUpdate
});01 / PROBLEM FRAMING
何を解決したいのか。
ツールごとに呼び出し方、返り値、進捗通知、タイムアウトの扱いが違うと、AI Agentを組み込むアプリの実装が複雑になります。違いを吸収する薄い共通レイヤーを設計しています。
02 / DESIGN DECISIONS
何を選び、どう形にしたか。
DESIGN NOTE / 01
入口を共通にする
同一のrun() APIを通じて異なるローカルAgent CLIを実行する。
DESIGN NOTE / 02
途中の状態を観測する
onProgressで処理中の出力を受け取れる。
DESIGN NOTE / 03
終了と失敗を制御する
AbortSignal・timeoutMs・fallback hooksを備える。
DESIGN NOTE / 04
モデル設定を整理する
プロバイダ別のモデルとreasoning effortの差を変換する。
03 / HOW IT WORKS
仕組みの全体像。
アプリが run() を呼ぶ→Provider adapter→ローカルAgent CLI→結果・進捗を返す
構成を理解しやすくした概念図です。正確な実装詳細はソースコードを参照してください。
技術詳細を追いたい場合は、公開リポジトリのREADMEとソースコードが一次情報です。
GitHubのREADMEとコードを読む ↗04 / STATUS & LIMITATIONS
公開状況と注意点。
headless_coreはWeb APIサーバーではなく、ローカルCLIを起動するライブラリです。CLIごとの権限や認証、セキュリティ上の注意事項はREADMEを確認してください。