CLI

インストール

npm install -g kankaku
kankaku setup

kankaku-tuiからの移行

両方のパッケージがkankakuコマンドを提供するため、旧パッケージを残したまま新パッケージをインストールするとEEXISTで失敗します。次の順序で切り替えてください。

npm uninstall -g kankaku-tui
npm install -g kankaku
kankaku setup

Claude Codeのフック、ステータスライン、コマンドが参照するインストール済みパッケージのパスが変わるため、kankaku setupを再実行してください。

Node.js 24以降が必要です。以下のローカルHubはmacOSとLinuxに対応しています。

セットアップ

ターミナルでkankaku setupを実行すると、フルスクリーンのウィザードが開きます。Agents、Hub、Roots、Review、Apply、Doneの順に進みます。Agentsには各エージェントの設定状態とパスが表示され、設定済みの項目を外すとそのエージェントからkankakuの設定を削除します。CodexとOpenCodeは無効です。アダプターがまだないか、インストールされていません。既存のHub（URL、メール、マスクされたパスワード、接続確認）、ローカルへのインストール、またはスキップを選べます。「ローカルにインストール」では所有者のメールアドレスとパスワード、ポートを入力します。ポートには空いている最初の番号があらかじめ入力されます。Rootsにはプロジェクトの親フォルダーをカンマ区切りで入力します。最大5階層まで探し、.kankaku/worklog.jsonlのあるフォルダーをプロジェクトとみなします。Reviewでは変更するファイルを一つずつ確認でき、Doneでダッシュボードが開きます。

kankaku setup --yesは確認なしで既定値を使います。kankaku setup --dry-runは変更せず計画を表示します。各ファイルの初回変更前に<file>.bakを作成し、セットアップは再実行できます。kankaku doctorは読み取り専用の診断結果を表示します。

コマンド

画面

• Dashboard: 今日の作業・待機・コスト・タスク・cache hit、直近7日間、プロジェクト別の割合、Hubカード。cで一覧更新、sで全件同期、Sで完全同期、rで再読み込み。HubカードではhでローカルHubを起動・停止します。
• Tasks: タスクの一覧と詳細（プロンプト、顧客、案件、Hubタスク、総時間・作業・待機、コスト、cache hit、サブエージェント）。aで今日と全期間を切り替えます。mで選択中のタスクを別の顧客・案件・Hubタスクへ移し、Mで現在の表示にあるタスクのうちHub上で未割り当てのものをすべて移します。
• Catalog: 顧客・案件と未完了タスク数、キャッシュの経過時間と古さを表示します。
• Sync: プロジェクトごとのカード。sで同期、fで完全同期、Sで全プロジェクトを同期します。

1～4で画面切り替え、qで終了、矢印キーで移動、Enterで開き、Escで戻ります。

タスクの割り当て変更

• Tasks画面のmは選択中のタスク、Mは現在の表示にある対象タスクを移します。どちらも選択画面を開き、顧客、その顧客の案件、その案件の完了していないタスクの順に選びます。現在の割り当て → 新しい割り当てを確認し、行ごとの結果を表示します。
• MはHub上ですでに実際の顧客に割り当てられた行には触れません。Hubにまだないタスクは「sync first」としてスキップされます。
• 顧客・案件・タスクの整合しない組み合わせは選べず、送信前に拒否されます。一覧を更新できない場合、選択画面は開きません。
• 同期は行の作成時にだけ割り当てを設定し、変更後の割り当てを元に戻しません。ローカルの作業ログは書き換えられないため、ローカルレポートには記録時の割り当てが残り、Hubには修正後の割り当てが保持されます。

テーマ

--theme gentleman-sexy（既定）、--theme gentleman-cute、--theme gentleを指定するか、KANKAKU_TUI_THEMEを設定します。

ローカルHub

kankaku hub install [--port N] [--owner-email E]はnpmパッケージkankaku-hubからOS・CPUに合うPocketBaseを取得してSHA256を検証し、~/.kankaku/hub/に設置します。管理者・所有者・サービスアカウントを作成し、Hubを起動したままにします。ターミナルでは未入力の所有者メール・パスワードを尋ねます（パスワードは非表示）。非対話で使う場合は--owner-emailと--owner-passwordの両方が必要です。再実行しても既存の設定は変更されません。既定ポートは8090です。使用中ならインストールは停止し、--portで指定できる空きポートを案内します。自動で別のポートは選びません。既存のインストールはそのポートを維持します。ローカルインストールはmacOSとLinuxのみです。

ローカルHubのインストールだけでは、別のHubに設定済みのこのマシンの同期先は変わりません。~/.kankaku/credentials.jsonが別のHubを指していれば変更されません。ローカルHubへ切り替えるにはkankaku hub useを実行します（以前のファイルはバックアップされます）。kankaku hub statusにはsync: local hub、sync: <url>、またはsync: not configuredが表示されます。

kankaku hub start | stop | status | upgrade | logs [-n N]で管理します。upgradeは新しいapp/<version>/をコピーし、PocketBaseのバージョンが変わった場合のみ再取得して再起動します。pb_dataは変更しません。

設定

~/.kankaku/tui.jsonには{"roots": [...]}、~/.kankaku/credentials.jsonには{url,email,password}を保存します。環境変数がフィールドごとに優先されます: KANKAKU_PB_URL、KANKAKU_PB_EMAIL、KANKAKU_PB_PASSWORD。その他: KANKAKU_SYNC_WINDOW_HOURS、KANKAKU_SYNC_PROMPT、KANKAKU_SYNC_RECORDS、KANKAKU_MACHINE、KANKAKU_TUI_THEME。認証情報がない場合、catalogとsync statusはメッセージを表示して終了コード0、catalog refreshと同期コマンドはエラーを表示して終了コード1になります。