ガイド

このページの内容

インストール
最初のセッション
数値の見方
Hubに接続
サブエージェント
設定
知っておきたいこと

インストール

pi install npm:kankaku

他の方法: pi install git:github.com/soyunninja/kankaku（@v0.4.6でバージョン固定）、またはpi install /ローカルパス（コピーなし）。試すだけなら: pi -e /ローカルパス。

最初のセッション

何も有効化する必要はありません。次のプロンプトから測定が始まります。Hubがある場合、新しいプロジェクトを開くとクライアントとプロジェクトを聞かれます。スキップも可能で、「記憶する」を選べば次からは聞かれません。

数値の見方

/kankaku            # 今日の要約
/kankaku tasks      # タスクごとに1行
/kankaku sync       # 保留分をHubへ送信
/kankaku export     # csvまたはjson

Hubに接続（任意）

export KANKAKU_PB_URL="https://your-hub.example"
export KANKAKU_PB_EMAIL="service@your-hub.example"
export KANKAKU_PB_PASSWORD="…"

サービスアカウントを使い、自分のアカウントは使わないでください。接続しなくてもkankakuは動作します — クライアントが自由記述になるだけです。

Engramと連携。 HubにEngramが設定されていれば、各セッションが目的とやったことの要約付きで届き、時間とコストの横に表示されます。Hubサーバーの KANKAKU_ENGRAM_URL で有効にします。Engramがなくても、Hubの見た目は変わりません。

サブエージェントとgentle-ai

kankakuにgentle-aiは不要です。基本はpi自体のイベントから得られます — 作業と待機、トークン、コスト、モデル、クラッシュ復旧、Hub同期。

仕組みが重要になるのはサブエージェントです。

gentle-piとpi-subagentsは子プロセスにマークを付けます。kankakuはコストも含めて確実にオーケストレーターへ結び付けます。
piのサブエージェント例は何もマークしません。kankakuはプロセスの系譜で結び付け、プロセスの識別情報を確認します。
他の仕組みを使う場合は KANKAKU_SUBAGENT_TOOLS と KANKAKU_SUBAGENT_CHILD_ENV で宣言してください。宣言がなければ、検出した子プロセスは「不確実」のままです — 時間は別集計され、新しいタスクとしては数えられません。

reviewタグはgentle-ai review用にあらかじめ用意されています。使わなければ表示されません。KANKAKU_SEGMENTSで変更できます。

設定

変数	デフォルト	説明
`KANKAKU_DIR`	`.kankaku`	作業ログ（`worklog.jsonl`）とクラッシュ復旧用チェックポイントのディレクトリです。絶対パスでない限り、プロジェクトのcwdからの相対パスとして扱われます。
`KANKAKU_INTERACTIVE_TOOLS`	`ask_user_question,ask_user_choice`	実行時間が待機時間としてカウントされるツール名を、カンマ区切りで指定するリストです。
`KANKAKU_SEGMENTS`	`review=bash:\bgentle-ai review\b`	タグ付きセグメント用の「tag=tool:regex」ルールを「;」区切りで指定します（デフォルトは「review」ルール1件のみ）。
`KANKAKU_CLIENT`	`(unset)`	このプロジェクトのデフォルトの請求先クライアントです。「/kankaku client」より優先度は低く、プロジェクトの「config.json」より優先度は高くなります。
`KANKAKU_ROLE`	`(unset)`	1回の実行だけロールを上書きします（「orchestrator」/「subagent」）。グローバルにはエクスポートせず、`KANKAKU_ROLE=orchestrator pi …` のように限定してください。
`KANKAKU_PB_URL`	`(unset)`	PocketBaseハブのURLです。localhost/127.0.0.1/::1を指す場合を除き、HTTPSである必要があります。
`KANKAKU_PB_EMAIL`	`(unset)`	ハブのサービスアカウントのメールアドレスです。
`KANKAKU_PB_PASSWORD`	`(unset)`	ハブのサービスアカウントのパスワードです。
`KANKAKU_MACHINE`	`OS hostname`	このマシンの表示名です。ハブが設定されると、すべてのレコードに「machine」として付加されます。
`KANKAKU_SYNC_PROMPT`	`none`	同期時のプロンプトのプライバシー設定です。「none」（送信しない）、「truncated」（先頭120文字）、「full」のいずれかです。
`KANKAKU_SYNC_WINDOW_HOURS`	`24`	同期のウォーターマークから何時間さかのぼって再評価するかを指定します。遅れて完了するサブエージェントを捕捉するためのものです。
`KANKAKU_SYNC_RECORDS`	`1 (enabled)`	「0」にすると「work_records」（生の詳細データ）のアップロードを無効化します。「task_entries」は常にアップロードされます。
`KANKAKU_SYNC_AUTO`	`1 (enabled)`	「0」にすると「session_start」「agent_settled」時の自動同期を無効化します。「/kankaku sync」は引き続き使用できます。
`KANKAKU_SYNC_MIN_INTERVAL_MINUTES`	`5`	自動同期の最短間隔（分）です。「0」で間隔制限を無効化します。手動同期には影響しません。

知っておきたいこと

有効化しない限り、プロンプトはマシンの外に出ません。
並行して動くサブエージェントがあっても時間は二重になりません。
クラッシュしても何も消えません — 「中断」として記録されます。
kankakuはコストを推定するだけで、請求はしません。
/kankaku doctorは通信せずに診断します。

指標	内容
作業時間	実際に作業した時間
待機時間	あなたを待っていた時間
wall-clock time	開始から終了までの合計