Pi Keytree

Hierarchical leader-key command menu for Pi.

Discover commands through a small, keyboard-driven tree instead of memorizing every slash command. Inspired by Neovim/LazyVim/which-key style command discovery. This is an independent project, not an official Neovim, LazyVim, or which-key integration.

Features

• Leader-key style command discovery with configurable categories and actions.
• Right-side bordered overlay; submenus update the same panel.
• Hierarchical navigation, scrolling, and responsive sizing.
• Plugin-aware availability and context checks before execution.
• Configurable timeout; 0 means no automatic timeout.
• Optional Nerd Font icons with plain-text fallback.
• Terminal-default background and Pi theme foreground colors.
• No replacement of the Pi editor; current drafts are preserved.
• Read-only project file viewer and safe Git base-branch selection.
• No additional runtime dependencies: Pi supplies the host libraries.

Screenshot

Installation

Requires Pi 1.0.0. Later releases are not yet verified. Pi itself supplies @earendil-works/pi-coding-agent and @earendil-works/pi-tui.

Local development / source checkout

From a local checkout:

# Try only this extension for one invocation, without changing Pi settings.
pi --no-extensions -e ./index.ts

# Alternatively, install the local package persistently.
pi install .

The temporary command disables other extensions in that invocation; their menu actions will be unavailable. It does not disable or modify them in your saved configuration. Avoid loading another leader-menu extension on Ctrl+Space at the same time. Use /keytree if the activation shortcut conflicts.

npm (after publication)

pi install npm:pi-keytree

This command is not available until this package is published to npm. A valid manifest does not reserve the npm name or guarantee publishing permission. No npm publication is performed by the development or test scripts.

Usage

Press Ctrl+Space, or run /keytree, then press a category key and an action key.

The path appears in the title, for example Pi Keytree > Git. Unknown keys and unavailable actions keep the panel open and show a short hint. /keytree off closes UI owned by this extension; it is not a persistent disable switch.

Ordinary Space is never an activation key. While the menu is open, it temporarily owns keyboard focus; unknown input is not forwarded into your draft. Closing restores Pi's previous focus.

Default key tree

L below means Ctrl+Space. Keys are pressed sequentially.

Built-in UI commands marked prepare are inserted into an empty editor and require Enter. A nonempty draft, including whitespace, is never overwritten. Agent shortcuts do not start work without a user-supplied task.

Git base selection uses a valid remote HEAD first, then main, then master. Multiple candidates or no recognized default cause a selection prompt, not a guess. The selected ref is resolved to a commit before passing it to /diff. Three-dot comparison covers committed branch changes, not unstaged edits. No fetch or repository mutation is performed.

Configuration

No configuration file is required: config.example.json is the safe built-in default. It contains no provider-specific model defaults, credentials, or personal paths.

For local development, copy the example:

cp config.example.json config.json

config.json is ignored by Git and excluded from the npm package. For an installed npm package, keep configuration outside its install directory so updates do not overwrite it:

mkdir -p ~/.pi/agent/pi-keytree
cp config.example.json ~/.pi/agent/pi-keytree/config.json

Run that copy command from a checkout or the installed package directory. When using a custom Pi agent directory, use its pi-keytree/config.json instead.

Lookup order (the first existing file wins; files are not merged):

1. PI_KEYTREE_CONFIG, if set (a missing explicit file is an error).
2. <Pi agent directory>/pi-keytree/config.json.
3. config.json beside index.ts (local development).
4. Bundled config.example.json.

A malformed chosen file is reported rather than silently ignored. Run /reload after edits. No config is automatically written or copied.

{
  "enabled": true,
  "activation": "ctrl+space",
  "timeout": 0,
  "position": "right",
  "width": "auto",
  "showIcons": true,
  "showUnavailable": true
}

This excerpt shows UI options only; retain presets and menu from the full example. Numeric width means terminal columns, not percent. timeout: 5000 closes after five seconds of inactivity. See Configuration reference for actions, presets, icons, and bounds.

Integrations

All integrations are optional, detected by registered extension commands, not imported as dependencies.

Missing commands are dimmed and marked unavailable, or hidden with showUnavailable: false. They are never submitted as ordinary model prompts. Not being in a Git repository also disables Git actions. An unavailable integration does not prevent using Session or other independent categories.

The example's fast/review/main presets contain names only. If a matching Spark preset is absent, that shortcut remains unavailable until you configure a local fallback. Matching Spark presets always win; Pi Keytree does not maintain a second competing set of model defaults.

Opening MCP setup is deliberate user interaction: saving inside that plugin may change its configuration. Pi Keytree itself does not write those files.

Philosophy

This is command discovery, not a Vim mode. It does not take over ordinary Space, introduce modal text editing, create a CustomEditor, or replace Pi's editor, header, or footer. It uses public extension and TUI APIs without patching Pi core.

Known limitations

• Pi 1.0.0 has no uniform public executeCommand() for built-in UI commands. Those actions prepare text for explicit confirmation instead of using synthetic input or private methods.
• Ctrl+Space depends on terminal keyboard encoding and may be intercepted by an input method or desktop shortcut. /keytree is a fallback. Kitty's legacy NUL and CSI-u encodings are supported through Pi's key parser.
• The panel is visually nonintrusive but temporarily captures focus. A passive overlay would allow menu letters to leak into the editor. Model/tool activity can continue behind it.
• Terminal-default background can preserve terminal transparency, but this is not alpha blending of conversation text beneath the panel. Padding replaces those cells.
• Font detection is conservative and configuration-based, not a guarantee of glyph coverage. Unknown environments use text-only rows.
• Extremely small terminals show a compact title. Longer descriptions can be truncated; unavailable actions show their reason when pressed.
• Availability checks do not prove network connectivity or plugin health. Authentication expiry and plugin errors remain the plugin's responsibility.
• Some context checks are snapshots taken when opening the menu. Reopen after changing files or configuration; reload after changing extension settings.
• Host shortcut conflict checks do not enumerate every other extension's shortcut. Check /hotkeys and startup warnings when changing activation.

Development

Source is loaded directly by Pi; no build step or generated JavaScript is required.

npm install
npm test
pi --no-extensions -e ./index.ts
# Inside Pi, after edits:
# /reload
npm pack --dry-run

npm install is for development/testing (Jiti and host peer packages); it is not required for Pi-managed installation. To test against an existing Pi installation without installing dependencies, set PI_KEYTREE_TEST_HOST to the directory containing that installation's package.json. The test runner resolves host libraries and Jiti from there. See Development and release checklist.

Uninstall

To disable without removing files, set enabled: false in your chosen config and run /reload. To remove a package installation:

pi remove npm:pi-keytree
# For a local installation, pass the same local package path instead.

Temporary -e usage ends when that Pi process exits. Deleting a checkout does not remove a persistent package declaration; remove it through Pi first. User configuration at <agent directory>/pi-keytree/ may be retained or deleted separately. No background services are installed.

License

MIT — Copyright (c) 2026 Pi Keytree contributors.