hotmilk

hotmilk is a Pi meta-package. One install brings gentle-pi, context-mode, graphify, subagents, and about two dozen other pi-* extensions, each behind a toggle in $PI_CODING_AGENT_DIR/hotmilk.json (see Configuration). Every extension starts off. You switch on the ones you use with /mode, and you do not have to hand-pick packages or wire settings.json yourself.

Requires Pi 1.0 or later and Node.js 22.19+. Also runs on omp (22 of 28 extensions).

Contents

• What you get
• Quick start and upgrading from 0.1.x
• Configuration: toggles, /mode groups, workflow routing
• Development, contributing, license
• Documentation map

What you get

Bundled extensions switch on and off in hotmilk.json (via /mode), then /reload. Only src/index.ts is listed in package.json → pi.extensions; every other bundled package loads dynamically when its toggle is true. Every bundled extension defaults off (0.2.0 minimal core), so a fresh install runs the hotmilk theme, footer, /mode, and the indexed skills and prompts only. An existing hotmilk.json keeps its saved toggles. Pi always indexes the package's pi.skills, pi.prompts, and pi.themes paths; /mode toggles do not gate them.

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"]
}

For one project only (written to .pi/settings.json):

pi install -l npm:hotmilk

From a local checkout:

pi install ./path/to/hotmilk

First run

1. Open a project directory in Pi. A short hotmilk intro animation plays, then the footer remains; no bundled extension is loaded yet.
2. On first session, hotmilk creates $PI_CODING_AGENT_DIR/hotmilk.json if missing.
3. Run /mode, switch on the extensions you want (start with context-mode, todo, subagents), then /reload.

The same thing by hand, in hotmilk.json:

{
  "extensions": { "context-mode": true, "todo": true, "subagents": true }
}

Per-extension notes and combination rules: docs/bundles.md.

Upgrading from 0.1.x

0.2.0 is a minimal-core release.

• Every extension is off by default now. A hotmilk.json you saved keeps its values; extensions it has no value for are off. The first 0.2.0 session lists the formerly default-on ones you lost, once, and records that in notices.defaultOff020. Turn them back on with /mode, then /reload.
• Requires Pi 1.0 (gentle-pi 4, @earendil-works/pi-* 1.x).
• Removed rows: sdd-init (gone from gentle-pi 4), mcp-adapter and codemcp (Pi 1.0 has built-in MCP; hotmilk no longer touches mcp.json), herdr-squad, and openspec-context. Stale keys in hotmilk.json are ignored.
• subagents now loads gentle-pi's gentle-agents (same subagent_* tools, plus /gentle:agents); uninstall pi-subagents-j0k3r from Pi settings if you have it. /subagents-doctor is gone.
• btw is plain upstream pi-btw: hotmilk's prompt shaping and proxy tools are retired (details).

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 (on Pi 1.0 today: pi-lens stops at pi-tui 0.85 and pi-rtk-optimizer stops at 0.80; all load fine, and CI tracks them in third-party-risk.test.ts). 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. Treat upstream extensions as best-effort until their maintainers widen peer ranges.

Harnesses (pi, omp, OpenClaw)

hotmilk detects its host at startup from CONFIG_DIR_NAME in @earendil-works/pi-coding-agent:

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
  }
}

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.

When a hotmilk repo checkout (project package) and a globally installed npm:hotmilk would both load, the npm-installed copy yields and the project copy owns registration (project → user precedence). An installed release yields only once it carries this guard; until then, in-repo sessions report duplicate-tool diagnostics. To develop in-repo without them today, launch with a clean agent dir (PI_CODING_AGENT_DIR=$(mktemp -d) pi) so only the project copy loads (config seeds on first run).

Commands (hotmilk)

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

For how a change runs (W-model: test design per level, bottom-up execution), see Workflow routing 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

Bundled extension defaults live in src/config/bundled-extensions.ts. hotmilk.json stores user overrides and non-extension defaults; edit it with /mode, then run /reload to apply extension changes.

context-mode: the extension registers ctx_* via its built-in bridge (same module as upstream .pi/extensions/context-mode, loaded from build/adapters/pi/extension.js). hotmilk does not manage mcp.json or bundle an MCP adapter: Pi 1.0 has built-in MCP (pi mcp add, /mcp, docs), and omp reads its own mcp.json. Do not also list context-mode as an MCP server there; that registers ctx_* twice.

/mode groups

/mode renders groups from BUNDLED_EXTENSION_GROUP_ORDER in src/config/bundled-extensions.ts.

Workflow routing

The bundled pioneer skill runs each change as a roadmap-anchored W-model. The change starts from a ROADMAP.md horizon item, with sequencing gates respected. Every level (requirements, system design, detailed design, code) gets its test design and review gate before the next. Tests run bottom-up, each failure goes back to the level that caused it, and the roadmap is synced on close. The skill works in any repository and depends on no bundled extension; plannotator and planning-with-files stay optional paths outside it. Memory and optimize loops layer beside execution. comfortzone applies TCZ to the agent: coach it toward a goal, or let it self-coach when work stalls.

Skills and scope

Pi resolves assets at user (global), project, and package layers. hotmilk ships package defaults; you override per machine or per repo. hotmilk ships no subagent prompts: its change-flow practice lives in the pioneer skill (/pioneer or /skill:pioneer).

Environment variables

Pi and bundled extensions read the process environment. hotmilk never reads directory variables itself: it asks the host through getAgentDir() (agent dir: hotmilk.json, dedupe) and CONFIG_DIR_NAME (project dir: .pi, or .omp under omp), so every host rule below applies. HOTMILK_CONFIG_ROOT overrides the hotmilk.json dir for tests/sandboxes.

omp directories (omp resolves them; full list in omp's environment-variables doc):

Notifications show the resolved path home-relative (for example ~/.omp/profiles/work/agent/hotmilk.json).

Pi core (full list in Pi usage: environment variables):

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:

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

CI / publish (this repo only): GitHub Actions uses secret NPM_TOKEN, mapped to NODE_AUTH_TOKEN on the publish step. Local bun publish uses ~/.npmrc, not NPM_TOKEN.

pi-btw (side questions)

The btw row loads upstream pi-btw as is. BTW runs a separate Pi session whose tool surface, prompt, and extension sources are pi-btw's: it loads no extensions unless ~/.pi/agent/btw.json lists them (for example {"extensions": ["npm:pi-web-access"]}; see the pi-btw README). hotmilk adds no BTW prompt shaping or proxy tools (retired in 0.2.0: the createAgentSession wrap it relied on does not take effect on Pi 1.0).

hotmilk does not bind pi-btw's Alt+W width toggle, so Pi's Alt+W keybinding stays yours. Set "btw": false in /mode if you want no side channel.

Choosing extensions

Every bundled row with its package, /mode group, coupling class, omp support, RFC 2119 recommendation level, and combination rules (for example caveman vs defaults.language: ja, autoresearch vs goal) lives in docs/bundles.md. Enable a row in /mode or set its key to true in hotmilk.json, then /reload.

Alternative skill stacks (not bundled)

hotmilk does not bundle bigpowers, a separate spec-driven skill stack (70+ skills, prompts, MCP). It has no pi.extensions entry, runs postinstall global symlinks, and conflicts with the pioneer W-model flow. Install separately if you want that workflow instead of hotmilk's defaults:

pi install npm:bigpowers

Do not run bigpowers and pioneer on the same task.

latchkey (API credential injection via /skill:latchkey) is also not bundled; install with pi install npm:latchkey if needed.

Cursor models (optional, not bundled)

hotmilk does not ship @netandreus/pi-cursor-provider. Install when you route Pi through the Cursor Agent CLI:

pi install npm:@netandreus/pi-cursor-provider
agent login
# then in Pi: /model cursor/auto

Development

Requires Node.js and Pi peer versions from package.json (engines, peerDependencies). This repo uses Bun (bun.lock).

bun install       # commit bun.lock; peers resolved by Bun
bun run test      # vp test (same as CI)
bun run lint
bun run format    # vp fmt --write
bun run check     # format check + lint; run bun run test separately

npm install still works with this repo's .npmrc (legacy-peer-deps=true). This repo commits bun.lock only (no package-lock.json); CI uses Bun (bun install --frozen-lockfile).

Contributing

Work starts from a ROADMAP.md horizon item and follows the change flow in docs/maintenance.md: plan with a W table, write the failing test first, then bun run lint and bun run test, and sync the docs in the same change. AGENTS.md lists the hard rules (for example: only src/index.ts goes in pi.extensions). Which doc to open: docs/guidance.md. Adding a bundled extension: docs/bundles.md. Issues and pull requests: github.com/dayjobdoor/hotmilk.

License

MIT