ガイド

インストール

どのエージェントでも、次の方法を推奨します。

npm install -g kankaku
kankaku setup

kankakuをインストールすると、CLI、piの拡張機能、Claude Code連携がすべて利用できます。

Node.js 24以降が必要です。kankaku setupはエージェント（pi、gentle-shell、Claude Code）、Hub（既存・ローカル設置・スキップ）、プロジェクトの親フォルダーを選ぶウィザードです。続いてkankakuでダッシュボードを開けます。スクリプトではkankaku setup --yesが確認なしで既定値を使い、kankaku setup --dry-runは変更せず計画を表示します。kankaku doctorは状態を読み取り専用で診断します。詳しくはCLIガイドをご覧ください。

piの拡張機能だけ使う場合:

pi install npm:kankaku-pi

既存のインストールではpi install npm:kankakuも引き続き動作しますが、CLIの依存パッケージもpiに取り込みます。両方のソースを同じ設定に残さないでください。拡張機能が二重に読み込まれ、すべての測定が重複します。

他の方法: pi install git:github.com/soyunninja/kankaku（現在のバージョンに固定するには@v1.3.0を指定。v0.9.0～v0.12.0のタグはgitから読み込めません）、またはpi install /absolute/path/to/kankaku/packages/pi（コピーなし）。インストールせずに試すにはpi -e /absolute/path/to/kankaku/packages/pi。gentle-shellではインストールコマンドにgentle-shell install …を使います。

最初のセッション

piでは次のプロンプトから測定されます。Claude Codeでもkankaku setupで設定すると同様です（下の「Claude Code」を参照）。

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

piのTUIでは、/kankakuで枠付きのパネルが開きます。タイトル（>_ kankaku · <画面名>）は開いている画面に合わせて変わります。

• Target: 顧客、案件、Hubタスク、ラベル。
• Report: 集計、タスク、セッション、顧客、案件。今日または全期間を選び、チャットに固定できます。
• Sync: 状態、今すぐ同期、全件同期、過去分、一覧更新。
• Export: CSVまたはJSON、今日または全期間、ファイルへの書き出し。
• Doctor: 孤立または不確実な子プロセスの数。
• About: バージョン、保存先、Hub、設定。
• 操作: ↑/↓ 移動、Enter 開く、Esc/← 戻る、q 閉じる。

ルート画面ではEscまたは←で閉じ、qならどの画面からでも閉じます。フッターのヒントと行をマウスでクリックできるのはpiのフルスクリーンモードだけです。通常モードではマウス操作は使えません。サブコマンドは従来どおり利用でき、TUIでもパネルを経由しません。ヘッドレス（print/RPC）モードでもサブコマンドを使います。このモードでは、引数なしの/kankakuは今日の合計を表示します。

Claude Code

kankaku setupでClaude Codeを選びます。リポジトリのクローンも--plugin-dirも不要です。セットアップは~/.claude/settings.jsonの他のキーやツールのフックを保ちながら、プロンプトごとのコストを伝えるstatusLineと、プラグインが宣言する各イベントのフックを追加します。ユーザーコマンドは~/.claude/commands/kankaku/に設置されます。Node.jsのバージョン変更などでインストール先が変わったら、セットアップを再実行してください。--plugin-dirを併用するとフックが二重実行され、記録も重複します。

プロンプトごとにpiと同じ形式の作業ログを記録します。総時間、質問や許可を待った時間、作業時間（総時間から待機を引いた値）、トークン数、コストです。各記録には測定したエージェント（claude-code）、プラグイン（kankaku-claude）とそのバージョン、Claude Codeのバージョンが付き、CLIでHubへ同期しても保持されます。顧客と案件はプロジェクトのconfig.json、次にキャッシュ済みHub一覧のリポジトリパスから解決します。フックは通信しません。中断したプロンプトは最後に記録された活動時刻で閉じられます。コストはセッションの累計額が2回の確定時点でどれだけ増えたかで計算します。各プロンプトは前のプロンプトの終了時点を起点にするため、プロンプト間の消費額は次の記録に入ります。トークン数にはサブエージェントの消費分も含まれ、プロンプト間に使った分は次の記録に入ります。ヘッドレス実行（claude -p）にはstatuslineがありませんが、セッション終了時にClaude Code自身のセッション記録からコストを読み取ります。

kankakuは、Claude Codeがディスクに保存するセッション記録から、トークン数、Claude Codeのバージョン、セッションが対話型かヘッドレスかを読み取ります。プロンプトや回答は読み取らず、この処理によって外部へ何も送信しません。

トークン数とcache hitは、Claude Code自身のセッション記録から得られます。この内部形式は文書化されたインターフェースではないため、Claude Codeの更新で形式が変わると、kankakuが対応するまでトークン数なし（ヘッドレス実行ではコストもなし）で記録は書き続けられます。コストはstatuslineから取得したセッション合計をプロンプトごとに配分します。バックグラウンドのサブエージェント時間は個別に測定されません。許可待ちはクリック時ではなく次のフックイベントで終わります。Claude Code内から顧客や案件を変更することはまだできません。

数値の見方

/kankaku all        # 全期間の要約（TUIのサブコマンド）
/kankaku tasks      # タスクごとに1行
/kankaku sync       # 保留分をHubへ送信
/kankaku export     # csvまたはjson

トークンが記録されたレポート行の末尾にはcache hit NN%が付きます。プロバイダーのキャッシュから読み出されたプロンプト入力トークンの割合で、計算式はcacheRead / (input + cacheRead + cacheWrite)です。トークンの記録がない場合、0%とは表示せず、この部分を省略します。例: orchestrator: work 41m00s, waiting 0m00s, 1 record(s), $0.82, cache hit 68%。piのタスク、クライアント、プロジェクトの行にも適用されます。1.3.0以降のClaude Codeの記録にもトークン数が含まれ、その行にはcache hitが表示されます。それより前のバージョンで書かれた記録にはトークン数がありません。

Hubに接続（任意）

先に試してみたい場合は、https://demo.kankaku.io を開き、demo@kankaku.io / demokankaku でログインしてください（読み取り専用、架空データ）。Hubはオープンソースです: github.com/soyunninja/kankaku_hub。

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

Hubがまだない場合は、kankaku setupのHub手順で「ローカルにインストール」を選ぶか、kankaku hub installを実行してください。詳しくはCLIガイドをご覧ください。

サービスアカウントを使い、自分のアカウントは使わないでください。接続しなくてもkankakuは動作します — クライアントが自由記述になるだけです。Hubのクライアント・プロジェクト一覧は毎回のセッション開始時に更新されます（選択画面は更新を少し待ちます）。手動更新には/kankaku catalog refreshを使えます。

/kankaku task（または/kankaku task pick）で、現在のHubプロジェクトの未着手・進行中タスクを選び、このセッションに紐付けます。以降に同期されるタスク行にはそのリンクが付きます。解除は/kankaku task clearです。リンクはセッション限りで、config.jsonには保存されず、セッション開始時にも尋ねられません。/kankaku target pick|clearでも解除され、サブエージェントには引き継がれません。タスクはHubで作成し、kankakuでは作成しません。担当者の割り当ては行の作成時だけなので、HubのWebアプリで担当者を変更しても、その後の同期で元に戻されません。

Claude Codeでは/kankaku:taskでHubタスクをセッションに紐付けられます。別のHubへ切り替えると、前のHubの同期状態は再利用されず、すべて再送されます。Hubの行に表示されるエージェントは同期したツールではなく、測定した側（piまたはClaude Code）です。

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で変更できます。

設定

パネルのAbout画面では、環境変数でのみ設定できる項目がすべて読み取り専用で表示されます。バージョン、解決済みのKANKAKU_DIR、Hub URLも確認できます。

知っておきたいこと

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