pi-essentials

Small quality-of-life extensions for pi that pi does not ship natively.

Install

pi install npm:@samfp/pi-essentials
# or straight from GitHub
pi install git:github.com/samfoy/pi-essentials

What's included

Extension	File	What it does
Screenshot	dist/screenshot.js	/ss command: grab the clipboard image (over SSH, via kitty's clipboard protocol) or send an image file to the agent
Image Context Pruner	dist/image-context-pruner.js	Strips images from all but the most recent image-bearing user message before each LLM call, to save context tokens
Daily Log	dist/daily-log.js	daily_log tool: append timestamped entries to a daily markdown note
Markdown Viewer	dist/markdown-viewer.js	Rendered view of .md files the agent reads, writes, or edits (Ctrl+O), plus /mdview and /mermaid commands. Registers no tools

Load only some of them

Filter the package in settings.json. Filters match the manifest paths above:

{
  "packages": [
    {
      "source": "npm:@samfp/pi-essentials",
      "extensions": ["**/screenshot.*", "**/image-context-pruner.*", "**/daily-log.*"]
    }
  ]
}

Markdown Viewer

The viewer does not replace pi's read, write, or edit tools, so it loads next to any extension that does. When a turn reads, writes, or edits a .md/.mdx/.markdown file, the viewer adds a one-line [md read] path (Ctrl+O for rendered view) entry after the tool output. Ctrl+O (pi's tool-expand key) shows the rendered markdown, with mermaid blocks drawn as images. The views are custom session entries: they show in the interactive TUI, are kept with the session, and are never sent to the model. To keep session files small, a view stores at most 200 KB of the file; a longer file shows its first 200 KB and a (truncated, N KB) note.

The views need pi 0.87.0 or newer, which added the turn_end entries they are written through. On older pi the viewer is inactive and raises no errors: it adds no views, and before pi 0.80.4, which added entry renderers, it does not register /mdview or /mermaid either.

• /mdview [path] renders a file in a full-screen view. With no path, it opens the last file the viewer showed on this branch.
• /mermaid [file.mmd | file.md | code] renders mermaid diagrams. With no argument, it uses the mermaid blocks of that same last file.

Daily Log configuration

Variable	Default	Meaning
DAILY_LOG_DIR	~/daily-notes	Directory holding YYYY-MM-DD.md notes
DAILY_LOG_SECTION	## Journal	Section header entries are appended under
DAILY_LOG_TEMPLATE	unset	Template file for new notes ({{date}} is substituted)
DAILY_LOG_CREATE_CMD	unset	Shell command that creates a new note (receives DATE)

Requirements

• pi 0.87 or newer (built and tested against 0.87.1). The markdown viewer's views need at least 0.87.0; on older pi the viewer is inactive and raises no errors
• Screenshot from clipboard: kitty terminal with clipboard_control read-clipboard, tmux with set -g allow-passthrough on, and the kitten binary at ~/.local/bin/kitten on the machine running pi
• Mermaid rendering: curl and internet access (diagrams are rendered by the mermaid.ink API)

Migrating from 0.x

1.0.0 removes six extensions. Pi 0.87 covers most of what they did. If you filtered this package by path in settings.json, drop the patterns for the removed files.

Removed extension	What it did	Replacement in pi 0.87
auto-session-name	Named an unnamed session after the first 60 characters of its first user message	Native, mostly. The /resume session selector already shows a session's first message when it has no name (docs/session-format.md, SessionInfoEntry). Name a session explicitly with /name <name> or pi --name <name>. For an extension that names sessions, see examples/extensions/session-name.ts (pi.setSessionName()). Pi does not auto-name sessions.
auto-title	Set the terminal title and the tmux window name from the first prompt	Partly native. Interactive mode sets the terminal title to π - <session name> - <cwd basename>, or π - <cwd basename> when unnamed (the last component of the working directory, not the full path), and refreshes it when the session is renamed (updateTerminalTitle() in dist/modes/interactive/interactive-mode.js). Not replaced: titling from the first prompt, and renaming the tmux window. In tmux, set -g automatic-rename-format '#{pane_title}' (with allow-set-title on) makes the window name follow pi's title. Extensions can call ctx.ui.setTitle(); see examples/extensions/titlebar-spinner.ts.
compact-header	Replaced the startup header with a compact model/keybinding table	Native setting plus example. quietStartup: true hides the startup header (docs/settings.md). To draw your own, see examples/extensions/custom-header.ts (ctx.ui.setHeader()). Run /hotkeys for the keybinding reference.
clipboard-image	Turned base64 PNG/JPEG text pasted into the prompt into an image attachment	Native for real images. app.clipboard.pasteImage (Ctrl+V; Alt+V on Windows and WSL) pastes an image from the clipboard (docs/keybindings.md), and images can be dragged into a compatible terminal (docs/usage.md). Not replaced: decoding pasted base64 text. Over SSH, this package's /ss still reads your local clipboard.
subagent	subagent and subagent_status tools that ran background pi processes and injected their results when done, plus a tmux interactive mode	Example extension. examples/extensions/subagent/ delegates to child pi processes with isolated context, in single, parallel, and chain modes. Not replaced: fire-and-forget background runs, subagent_status, and the tmux interactive mode. The example waits for its children to finish.
context-pruner	context_prune tool that let the agent swap bulky search results for a short summary	No drop-in replacement. Pi's automatic compaction frees context by summarizing older turns (compaction.enabled, compaction.keepRecentTokens, compaction.reserveTokens in docs/settings.md; /compact; docs/compaction.md). It does not let the agent pick individual tool results. An extension can do that with context_edit entries returned from a turn_end handler (docs/extensions.md, docs/session-format.md).

Paths above are relative to the installed @earendil-works/pi-coding-agent package ($(npm root -g)/@earendil-works/pi-coding-agent).

Development

npm ci
npm test        # tsc --noEmit + unit tests
npm run build   # regenerate dist/ (committed; CI fails if it is stale)

License

MIT