pi-dynamic-help

Dynamic /help dashboard for Pi. It summarizes loaded slash commands, tools, MCP servers, and installed Pi packages, then shows them in a concise TUI markdown panel.

Install

pi install npm:pi-dynamic-help

Local development install:

pi install /absolute/path/to/pi-dynamic-help

Temporary test run without adding it to settings:

pi -e /absolute/path/to/pi-dynamic-help

After installing, run /reload or restart Pi if the command is not visible immediately.

Commands

• /help — open the dynamic help dashboard.
• /help refresh — refresh the resource index and persist state.
• /help search <term> — filter the dashboard by a term.
• /help pin <term> — pin the best matching resource.
• /help unpin <term> — unpin the best matching resource.

What it indexes

• Slash commands registered by Pi, packages, prompt templates, and extensions.
• Active tools exposed to the agent.
• MCP gateway and configured MCP servers.
• Packages listed in user and project Pi settings.

The dashboard keeps command/tool/package/MCP sections separate so the resource type is clear.

Usage counters

Usage counters currently focus on tools and MCP calls, based on Pi session/tool-result data that is available to the extension. Commands are ranked by pinning and known metadata unless Pi exposes reliable command-usage data in the future.

State and migration

Runtime metadata is stored under the user's Pi agent state directory:

~/.pi/agent/state/pi-dynamic-help/state.json

The old local-extension state file, if present, is read as a migration source:

~/.pi/agent/state/dynamic-help.json

State uses stable identities for resources. Command identities normalize /help and help to the same item, and this package's own local/npm/git/node_modules sources normalize to pkg:pi-dynamic-help, preserving /help pins and usage across install-source changes.

If the current state file is corrupt, it is moved aside as:

~/.pi/agent/state/pi-dynamic-help/state.corrupt-<timestamp>.json

Then the extension starts from legacy state or an empty state. State save failures show a warning but should not prevent /help from rendering.

Runtime state is not part of the npm package and should not be committed or published.

Privacy and safety

This extension reads local Pi settings and MCP configuration files to build the dashboard. It does not upload this information. Like all Pi extensions, it runs locally with the permissions of your Pi process, so install only from sources you trust.

Development

npm install
npm run check
npm run test
npm run pack:dry

Tests are hermetic and use temporary directories for state-store coverage; they should not write to your real ~/.pi/agent/state.

Useful local smoke test:

npm pack
TMP_AGENT_DIR=$(mktemp -d /tmp/pi-dynamic-help-agent-XXXXXX)
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi install ./pi-dynamic-help-0.2.0.tgz
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help refresh"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help search mcp"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help pin bash"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help unpin bash"

Troubleshooting

• /help does not appear: run /reload or restart Pi.
• State looks stale: run /help refresh.
• A pin targets the wrong resource: use a more specific search term with /help pin <term> or undo it with /help unpin <term>.
• Installed package is not shown: confirm it is listed in ~/.pi/agent/settings.json or project .pi/settings.json, then run /help refresh.
• State corruption warning appears: inspect the generated state.corrupt-*.json backup and continue using /help; the extension will create a fresh state file.