honcho-cli

Honcho CLI

honcho は Honcho Python SDK をエージェント向けのデフォルト設定でラップします。JSON 出力、構造化されたエラー、入力検証を備えています。ワークスペースの状態の確認、ピアのメモリのデバッグ、弁証法の診断に使用します。

出力と設定

• TTY：人間が読みやすいテーブル（インタラクティブな場合のデフォルト）
• パイプ出力／--json：JSON — コレクションを扱うコマンドは配列を、単一リソースを扱うコマンドはオブジェクトを出力します
• 終了コード：0 成功 · 1 クライアントエラー（無効な入力、見つからない） · 2 サーバーエラー · 3 認証エラー
• 設定：~/.honcho/config.json（他の Honcho ツールと共有）。CLI は最上位の apiKey と environmentUrl を管理します。honcho init を実行して確認または設定します。コマンドごとのスコープ（ワークスペース／ピア／セッション）は、-w／-p／-s フラグまたは HONCHO_* 環境変数で指定します。

コマンドグループ

• honcho config — CLI の設定
• honcho start／stop／status — ローカル Docker スタック（environmentUrl は変更しません）。初回起動時に Honcho イメージのダイジェストを固定し、プロファイルに config.toml を書き込みます。対話型設定ウィザードを使用するには、--setup basic または --setup advanced を渡します（TTY の場合のみ。.env のオーバーライドを書き込みます）。honcho status はすべてのプロファイルを一覧表示します。特定のプロファイルを表示するには --profile を渡します。
• honcho workspace — 確認、削除、検索、チャット
• honcho peer — 確認、カード、チャット、検索
• honcho session — 確認、表示（トランスクリプト）、コンテキスト、要約
• honcho scope — 一覧表示、作成、確認、セッション、セッションの追加、セッションの削除、ステータス
• honcho message — 一覧表示と取得
• honcho conclusion — 一覧表示、検索、作成、削除

ルール

• 出力をプログラムで処理する場合は、必ず --json を渡してください。
• コンテキストを把握するため、honcho peer chat の前に honcho peer inspect を実行してください。
• エージェントが受け取る内容を正確に確認するには、honcho session context を使用してください。
• 先に honcho workspace inspect を実行せずに、honcho workspace delete を実行しないでください。
• ピアカードと結論を比較して、メモリの状態を把握してください。
• honcho scope add-sessions の後、スコープを指定した chat の前に honcho scope status <name> を確認してください。バックフィルが pending の場合、スコープの追いつきがまだ完了していないことを示しており、想起すべき内容がないという意味ではありません。
• honcho start は environmentUrl を書き換えません。ローカルスタックに接続するには、HONCHO_BASE_URL=http://127.0.0.1:8000 を使用してください。

確認の手順

Honcho のデプロイ環境を把握するときは、外側から内側へ確認します。

1. ワークスペースを把握する

honcho workspace inspect --json

2. ピアを見つける

honcho peer list --json
honcho peer inspect <peer_id> --json

3. ピアのメモリを確認する

honcho peer card <peer_id> --json
honcho conclusion list --observer <peer_id> --json
honcho conclusion search "topic" --observer <peer_id> --json

4. セッションをデバッグする

honcho session inspect <session_id> --json
honcho session view <session_id> --last 20 --json
honcho session view <session_id> --page 2 --size 50 --json
honcho message list <session_id> --last 20 --json
honcho session context <session_id> --json
honcho session summaries <session_id> --json

5. ワークスペース全体を検索する

honcho workspace search "query" --json
honcho workspace chat "what themes show up across peers?" --json
honcho workspace chat "what happened in this project?" --scope my-project --json
honcho peer search <peer_id> "query" --json

6. スコープで想起範囲を限定する

honcho scope list --json
honcho scope inspect <name> --json                       # members + backfill summary
honcho scope create <name> --sessions <id1>,<id2> --json
honcho scope status <name> --json                        # wait until nothing is pending
honcho workspace chat "what happened here?" --scope <name> --json

デバッグ手順

ピアが学習していない？

# Is observation enabled?
honcho peer inspect <peer_id> --json | jq '.configuration'

# What conclusions exist?
honcho conclusion list --observer <peer_id> --json
honcho conclusion search "expected topic" --observer <peer_id> --json

セッションのコンテキストがおかしい？

# Raw context an agent would receive
honcho session context <session_id> --json

# Summaries feeding the context
honcho session summaries <session_id> --json

# Recent message history
honcho message list <session_id> --last 50 --json

弁証法の回答が不適切？

# What the peer card says
honcho peer card <peer_id> --json

# Conclusions on the specific topic
honcho conclusion search "topic" --observer <peer_id> --json

# Exercise the dialectic directly
honcho peer chat <peer_id> "what do you know about X?" --json
honcho peer chat <peer_id> "what happened here?" --scope my-project --json
honcho workspace chat "what themes show up across peers?" --json