Guide

On this page

Install
First session
Your numbers
Connect the hub
Subagents
Settings
Good to know

Install

pi install npm:kankaku

Also: pi install git:github.com/soyunninja/kankaku (add @v0.4.6 to pin), or pi install /local/path, no copy. Try without installing: pi -e /local/path.

Your first session

Nothing to turn on — kankaku measures from the next prompt. With a hub, opening a new project asks for the client and project; you can skip it, and saying yes to remembering means it won’t ask again.

Your numbers

/kankaku            # today's summary
/kankaku tasks      # one line per task
/kankaku sync       # push what's pending to the hub
/kankaku export     # csv or json

Connect the hub (optional)

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

Use a service account, never your own. Without this, kankaku still works — the client is just free text.

With Engram. If the hub has Engram configured, each session arrives with its goal and a summary of what got done, next to time and cost. Enable it with KANKAKU_ENGRAM_URL on the hub server. Without Engram, the hub looks exactly the same.

Subagents and gentle-ai

kankaku doesn’t need gentle-ai. The essentials come from pi’s own events: work vs. waiting, tokens, cost, model, crash recovery, and hub sync.

Where the mechanism does matter is subagents:

gentle-pi and pi-subagents mark their children. kankaku joins them to their orchestrator with certainty, cost included.
The pi subagents example marks nothing. kankaku joins it by process ancestry, checking process identity.
Another mechanism: declare it with KANKAKU_SUBAGENT_TOOLS and KANKAKU_SUBAGENT_CHILD_ENV. Otherwise a detected child stays uncertain: its time is reported separately and never counted as a new task.

The review tag comes ready for gentle-ai review. If you don’t use it, it never shows up. Change it with KANKAKU_SEGMENTS.

Settings

Variable	Default	Meaning
`KANKAKU_DIR`	`.kankaku`	Directory for the work log (`worklog.jsonl`) and crash-recovery checkpoints, relative to the project cwd unless given as an absolute path.
`KANKAKU_INTERACTIVE_TOOLS`	`ask_user_question,ask_user_choice`	Comma-separated list of tool names whose execution span counts as waiting time.
`KANKAKU_SEGMENTS`	`review=bash:\bgentle-ai review\b`	";"-separated "tag=tool:regex" rules for tagged segments (defaults to the single "review" rule).
`KANKAKU_CLIENT`	`(unset)`	Default billing client for this project; lower precedence than "/kankaku client", higher than the project's "config.json".
`KANKAKU_ROLE`	`(unset)`	Overrides role detection ("orchestrator"/"subagent") for one invocation only — never export it globally: `KANKAKU_ROLE=orchestrator pi …`.
`KANKAKU_PB_URL`	`(unset)`	PocketBase hub URL. Must be HTTPS unless it points at localhost/127.0.0.1/::1.
`KANKAKU_PB_EMAIL`	`(unset)`	Hub service-account email.
`KANKAKU_PB_PASSWORD`	`(unset)`	Hub service-account password.
`KANKAKU_MACHINE`	`OS hostname`	This machine's display name, attached to every record as "machine" once the hub is configured.
`KANKAKU_SYNC_PROMPT`	`none`	Prompt privacy for sync: "none" (omitted), "truncated" (first 120 characters), or "full".
`KANKAKU_SYNC_WINDOW_HOURS`	`24`	How many hours behind the sync watermark are re-evaluated on every run, to catch subagents that settle late.
`KANKAKU_SYNC_RECORDS`	`1 (enabled)`	"0" disables uploading "work_records" (raw detail); "task_entries" are always uploaded.
`KANKAKU_SYNC_AUTO`	`1 (enabled)`	"0" disables the automatic "session_start"/"agent_settled" sync; "/kankaku sync" still works.
`KANKAKU_SYNC_MIN_INTERVAL_MINUTES`	`5`	Minimum minutes between automatic syncs; "0" disables the throttle. Never applies to a manual sync.

Good to know

Prompt text never leaves your machine unless you turn it on.
A subagent running in parallel never doubles the time.
A crash doesn’t erase anything — it’s marked interrupted.
kankaku estimates cost; it never invoices.
/kankaku doctor diagnoses without touching the network.

Metric	What it is
work time	what it actually worked
waiting time	what it waited on you
wall-clock time	the total, start to finish