hotmilk

hotmilk is a Pi meta-package: one install wires gentle-pi, context-mode, graphify, subagents, and related extensions, plus user toggles in $PI_CODING_AGENT_DIR/hotmilk.json (Pi agent dir — see Configuration).

Use it when you want a practical engineering workstation without hand-picking a dozen pi-* packages and wiring settings.json yourself.

Contents

• What you get
• Quick start
• Configuration — toggles, /mode groups, workflow routing
• Development
• Documentation map

What you get

| Layer | Packages / assets | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Orchestration | gentle-pi (el Gentleman, SDD/OpenSpec sync, skill registry, /gentle-ai:doctor) | | Context | context-mode, pi-simplify, pi-rtk-optimizer (default off), pi-observational-memory (default off) | | Codebase graph | graphify-pi (default on); optional pi-shazam (default off) | | Subagents & interaction | pi-subagents-j0k3r, @juicesharp/rpiv-ask-user-question, @juicesharp/rpiv-todo, pi-intercom, pi-lens, gentle-engram, pi-herdr-squad (Herdr panes off by default) | | Goals & docs | pi-goal (default off), pi-docparser | | File-based planning | @tomxprime/planning-with-files (default off), @plannotator/pi-extension (browser plan approval, default off) | | Integrations | pi-mcp-adapter (default off), pi-btw (side channel — see below), @haispeed/pi-obsidian | | Web tools | pi-web-access (default off) | | Search tools | @ff-labs/pi-fff (replaces built-in find/grep, default off) | | Experiment loops | pi-autoresearch (default off) | | Output style | pi-caveman / pi-kanagawa (default off); optional @dietrichgebert/ponytail (lazy-senior mode, default off) | | Local assets | ./prompts, ./skills, ./themes, mcp.json template |

Bundled extension on/off is controlled in hotmilk.json (via /mode), then /reload. Only src/index.ts is listed in package.json → pi.extensions; every other bundled package is loaded dynamically when its toggle is true. Package-level pi.skills / pi.prompts / pi.themes paths are always indexed by Pi (they are not gated by /mode toggles).

Quick start

Install

pi install npm:hotmilk

Or add to Pi settings ($PI_CODING_AGENT_DIR/settings.json or project .pi/settings.json):

{
  "packages": ["npm:hotmilk"]
}

Local checkout:

pi install -l npm:hotmilk

First run

1. Open a project directory in Pi.
2. On first session, hotmilk creates $PI_CODING_AGENT_DIR/hotmilk.json if missing (defaults match the bundled template).
3. After config changes, run /reload.

Pi and npm peers

Peer ranges live in package.json → peerDependencies. Some bundled dependencies still declare narrow peer ranges that disagree with hotmilk’s Pi peers (pi-kanagawa peers on the @mariozechner/* namespace). npm may report ERESOLVE until those packages publish wider peers.

This repo ships .npmrc with legacy-peer-deps=true so npm install and npm ci succeed. Copy from .npmrc.example if you clone without .npmrc. Treat upstream extensions as best-effort until their maintainers widen peer ranges.

Project trust

Pi gates project-local .pi/ resources and .agents/skills behind project trust (Pi docs). hotmilk registers a project_trust handler and, by default, defers to Pi's built-in prompt (projectTrust.mode: "delegate").

Configure in $PI_CODING_AGENT_DIR/hotmilk.json:

{
  "projectTrust": {
    "mode": "delegate",
    "remember": false
  }
}

| mode | Behavior | | ---------- | ------------------------------------------------------------------------------ | | delegate | Let Pi resolve trust (trust.json, defaultProjectTrust, or built-in prompt) | | prompt | hotmilk confirm explaining what project trust enables | | always | Trust project-local resources (optionally remember: true) | | never | Decline project-local resources for this handler |

On startup, hotmilk scans only global Pi settings for bundled-extension dedupe. After trust, project .pi/settings.json duplicates are reported; run /reload to dedupe.

Commands (hotmilk)

| Command | Purpose | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | /mode | Toggle persona (gentleman / neutral / gyal / raiden) and bundled extensions; writes $PI_CODING_AGENT_DIR/hotmilk.json | | /stop | Stop current running work | | /interrupt <message> | Steer in-flight work with an interrupt prompt | | /subagents-doctor | When subagents is on: doctor report (hotmilk registers this in src/bootstrap/subagents-doctor.ts) |

Upstream packages add their own commands (gentle-pi /gentle-ai:status, /gentle-ai:doctor, SDD chains, graphify, context-mode, planning-with-files /plan-status, plannotator /plannotator, and so on).

For which plan, memory, or optimize path to use, see Workflow routing (canonical matrix) and the bundled pioneer skill.

Configuration

Pi agent directory: $PI_CODING_AGENT_DIR when set, otherwise ~/.pi/agent. Pi and hotmilk resolve the same path (getAgentDir()). Paths below use $PI_CODING_AGENT_DIR/….

$PI_CODING_AGENT_DIR/hotmilk.json

{
  "extensions": {
    "skill-registry": true,
    "sdd-init": true,
    "gentle-ai": true,
    "context-mode": true,
    "ask-user": true,
    "todo": true,
    "graphify": true,
    "shazam": false,
    "subagents": true,
    "herdr-squad": false,
    "lens": true,
    "goal": false,
    "docparser": true,
    "obsidian": true,
    "btw": true,
    "intercom": true,
    "simplify": true,
    "rtk-optimizer": false,
    "observational-memory": false,
    "engram": true,
    "mcp-adapter": true,
    "planning-with-files": false,
    "plannotator": true,
    "caveman": true,
    "ponytail": true,
    "red-green": false,
    "autoresearch": false,
    "web-access": true,
    "fff": false,
    "kanagawa": false,
    "prompt-template-model": false
  },
  "graph": {
    "warnOnStale": true,
    "autoSuggestUpdate": true
  },
  "defaults": {
    "persona": "neutral"
  },
  "mcp": {
    "seedOnStart": false
  },
  "projectTrust": {
    "mode": "delegate",
    "remember": false
  }
}

| Key / area | Behavior | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | extensions.* | Set to false to skip registering that bundled extension | | extensions.gentle-ai | Default true. gentle-pi: orchestration, lazy SDD preflight, OpenSpec sync/archive agents, /gentle-ai:doctor / :status. hotmilk keeps startup-banner off (figlet header instead) | | extensions.subagents | Default true. pi-subagents-j0k3r: subagent_* delegation, task/background modes, history, model profiles. Use with gentle-ai for focused delegation. | | extensions.ask-user | Default true. @juicesharp/rpiv-ask-user-question provides structured questions when requirements or risky choices need explicit user input. | | extensions.todo | Default true. @juicesharp/rpiv-todo provides explicit task-state tracking for the parent workflow. | | extensions.lens | Default true. pi-lens provides runtime code feedback, LSP, lint, format, and structural analysis. | | extensions.btw | Default true. Side conversation via /btw while main runs. Delegate implementation to subagents; use BTW for quick human questions. See pi-btw coexistence | | extensions.context-mode | Default true. Prefer ctx_* for large outputs (see project context-window rules) | | extensions.observational-memory | Default false. Compaction continuity; pairs with context-mode. See Workflow routing | | extensions.shazam | Default false. Tree-sitter + LSP execute guards (shazam_impact, shazam_verify); complements graphify — see Workflow routing | | extensions.herdr-squad | Default false. Visible read-only Herdr investigation squads (/herdr-squad). Requires Pi inside a Herdr-managed pane (HERDR_ENV=1) | | extensions.rtk-optimizer | Default false. Bash/read/grep output compaction; enable with context-mode for leftover shell output. Install rtk CLI for command rewrite (/rtk verify) | | extensions.planning-with-files | Default false. On-disk planning — see Workflow routing | | extensions.plannotator | Default true. Browser plan approval — see Workflow routing | | extensions.autoresearch | Default false. Optimize loop — see Workflow routing | | extensions.goal … mcp-adapter | Integration / perf extensions (formerly always loaded via pi.extensions; now toggled like other bundled deps) | | Enabled extensions | context-mode / rtk-optimizer load first (context stack), then all other enabled extensions in parallel. BTW uses a pre-load session hook but loads through the same registry path. | | graph.warnOnStale | Notify when graphify-out/needs_update exists | | graph.autoSuggestUpdate | Append graphify update . to that notification | | defaults.persona | Seeds .pi/gentle-ai/persona.json when missing. Supported modes: gentleman, neutral, gyal, and raiden; hotmilk default is neutral. gyal and raiden replace gentle-pi's persona section while preserving its harness rules. | | defaults.language | Appends a project language hint to the system prompt each turn | | mcp.seedOnStart | Copy mcp.json template into $PI_CODING_AGENT_DIR/mcp.json when missing (empty template; for pi-mcp-adapter) | | projectTrust.mode | Pi project trust: delegate (default), prompt, always, or never | | projectTrust.remember | When mode is always or never, persist the decision in Pi trust.json | | extensions.mcp-adapter | Default true. Enable only when you want MCP servers from $PI_CODING_AGENT_DIR/mcp.json (do not duplicate context-mode) |

MCP (default): context-mode extension registers ctx_* via its built-in bridge (same module as upstream .pi/extensions/context-mode, loaded from build/adapters/pi/extension.js). Hotmilk removes any context-mode server from $PI_CODING_AGENT_DIR/mcp.json when the extension is on. Enable mcp-adapter only for other MCP servers—not a second context-mode entry.

/mode groups

/mode starts with Defaults (persona), then bundled-extension sections from BUNDLED_EXTENSION_GROUP_ORDER in src/config/bundled-extensions.ts:

| Group | Extensions (toggle ids) | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Defaults | persona: gentleman, neutral, gyal, raiden | | Harness | skill-registry, sdd-init, gentle-ai | | Agent tools | ask-user, todo, graphify, shazam, prompt-template-model, subagents, herdr-squad, lens, fff, web-access | | Context & performance | context-mode, simplify, rtk-optimizer, observational-memory, engram | | Integrations | goal, docparser, obsidian, btw, intercom, mcp-adapter | | Workflow | planning-with-files, plannotator, red-green | | Output | caveman, ponytail, kanagawa | | Experiments | autoresearch |

Workflow routing

Pick one plan authority per task. Memory and optimize loops are not plan paths — they layer beside execution. Full tie-breakers and anti-patterns: bundled pioneer skill.

Plan paths (enable toggle → /reload when default off):

| When | Toggle / command | Artifact | Pioneer reference | | --------------------------------- | ---------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | | Small, bounded fix | (none) — chat Plan: | chat only | chat-plan.md | | Medium scope + browser approval | plannotator → /plannotator plans/<name>.md | plans/*.md | plannotator-routing.md | | Heavy research, /clear recovery | planning-with-files → /skill:planning-with-files | task_plan.md, findings.md, progress.md | upstream PWF skill | | Cross-cutting, spec, >400L review | gentle-ai → OpenSpec SDD | openspec/changes/<change>/ | openspec-routing.md |

Memory layers (supplementary — never replace plan/spec authority):

| Need | Prefer | | ----------------------------- | ------------------------------------------------------------------------------- | | Large logs, docs, test output | context-mode → ctx_* | | Rationale across compactions | observational-memory (extra model cost; V3 needs clean session after upgrade) | | User-readable plan files | planning-with-files | | Execute-time impact / LSP | shazam (after graphify recon; complements graphify) |

Details: observational-memory-routing.md, shazam-routing.md.

Optimize loops (mutually exclusive with SDD/Plannotator on the same task):

| Need | Prefer | | ------------------------------------------ | ------------------------------------------------------------ | | Metric optimize (bench, bundle size, loss) | autoresearch → /skill:autoresearch-create | | Feature delivery, spec, approval gates | gentle-ai SDD or plannotator — keep autoresearch off | | Correctness-first TDD | red-green (/tdd) |

Stop active loops (/autoresearch off) before switching plan paths. Details: autoresearch-routing.md. Default shortcut Ctrl+Shift+F — override in $PI_CODING_AGENT_DIR/extensions/pi-autoresearch.json.

Agents, skills, and scope

Pi resolves bundled assets at user (global), project, and package layers. hotmilk ships package defaults; you override per machine or per repo.

| Layer | Config | Agents (pi-subagents-j0k3r) | Skills / prompts | | ----------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | User (global) | $PI_CODING_AGENT_DIR/hotmilk.json, $PI_CODING_AGENT_DIR/settings.json | $PI_CODING_AGENT_DIR/agents/ or ~/.agents/ | User skill dirs indexed by gentle-pi skill-registry | | Project | .pi/settings.json | .pi/agents/ (canonical); legacy .agents/ still read | .pi/skills/; legacy .agents/skills/ | | Package | pi install npm:hotmilk | agents/ in the npm tarball — source of truth in git, not auto-discovered at runtime | package.json → pi.skills, pi.prompts, pi.themes (always indexed; extension toggles do not gate these) |

Precedence (same runtime name): project → user → builtin (pi-subagents-j0k3r built-ins). /run, chains, and the subagent tool default to agentScope: "both" (user + project + builtin).

hotmilk subagents

• Edit in git / npm: agents/*.md — package canonical prompts (package: hotmilk in frontmatter → runtime name hotmilk.coach, hotmilk.planner, …).
• Pi discovery: copy or symlink into .pi/agents/ for the project you are working in. pi-subagents-j0k3r reads project and user dirs only; it does not scan the installed package’s agents/ folder.
• Parent vs child: the main session runs gentle-ai orchestration (delegation, SDD, skill injection). Subagents get isolated prompts; the parent stays responsible for /run, acceptance blocks, and routing.

After changing prompts in this repo, sync the local project overlay (often untracked):

cp agents/*.md .pi/agents/

Verify with /subagents-doctor — expect hotmilk.* under project agents when .pi/agents/ is populated.

Environment variables

Pi and bundled extensions read the process environment. hotmilk honors PI_CODING_AGENT_DIR for hotmilk.json and global extension dedupe (same agent dir as Pi). HOTMILK_CONFIG_ROOT overrides that for tests/sandboxes.

Pi core (always relevant; full list in Pi usage — environment variables):

| Variable | Purpose | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | PI_CODING_AGENT_DIR | Override agent config dir (default ~/.pi/agent). hotmilk uses this for hotmilk.json, global settings dedupe, and MCP path | | PI_CODING_AGENT_SESSION_DIR | Override session storage (also --session-dir) | | PI_PACKAGE_DIR | Override package dir (Nix/Guix store paths) | | PI_OFFLINE | Disable startup network (update checks, package checks, install telemetry) | | PI_SKIP_VERSION_CHECK | Skip pi.dev latest-version check only | | PI_TELEMETRY | Opt in/out of install/update telemetry and provider attribution headers (1/0) | | PI_CACHE_RETENTION | long for extended prompt cache where supported | | PI_TIMING | 1 — emit timing diagnostics | | PI_HARDWARE_CURSOR | 1 — show hardware cursor (IME / some terminals) | | PI_TUI_WRITE_LOG | Path — log raw TUI ANSI to a file (debug) | | VISUAL, EDITOR | External editor for Ctrl+G |

LLM providers (Pi auth.json → env fallback; not hotmilk-specific): common keys include ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, Azure (AZURE_OPENAI_*), Vertex (GOOGLE_CLOUD_*). See @earendil-works/pi-ai for the full provider table.

hotmilk-owned:

| Variable | Purpose | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | HOTMILK_CONFIG_ROOT | Test/sandbox override for the directory that contains hotmilk.json. Wins over PI_CODING_AGENT_DIR. Normal installs leave unset |

Bundled extensions (only when the matching /mode toggle is on):

| Variable | Toggle / package | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------- | | PI_SUBAGENTS_HISTORY_DB_PATH | subagents | Override j0k3r task-history SQLite path | | PI_SUBAGENTS_HISTORY_HOME | subagents | Override j0k3r task-history home directory | | GEMINI_API_KEY, GOOGLE_API_KEY | graphify (CLI) | Semantic extraction backend for graphify extract | | GRAPHIFY_GEMINI_MODEL, GRAPHIFY_WHISPER_MODEL | graphify (CLI) | Override graphify LLM / Whisper model | | EXA_API_KEY, PERPLEXITY_API_KEY, GEMINI_API_KEY | web-access | Search / fetch keys (~/.pi/web-search.json also) | | PI_ALLOW_BROWSER_COOKIES | web-access | 1 — allow Chromium cookie extraction for Gemini Web | | CTX_FETCH_STRICT | context-mode | 1 — stricter fetch routing in context-mode | | … | | Issues and PRs are welcome. When you add an extension, skill, or workflow, document how to enable it (toggle key, settings path, or command) in this README. | | … | | 309:[Showing lines 1-300 of 446. Use :301 to continue] |

[Showing lines 1-300 of 309. Use :301 to continue]