ephemlets # ephemlets Keep living Markdown task reports beside your Pi conversation, and steer the agent through checklists and questions without interrupting it. ![Ephemlets demo: Pi creates a release report, the panel expands with alt+e and collapses again](assets/demo.gif) ## Use in Pi Available only in Pi's interactive TUI; headless, JSON, print, and RPC modes expose no ephemlet tool. Pi uses ephemlets for evolving, multi-step work where a persistent report helps more than another message. Short, single-step results stay in chat. Reports show concise progress, decisions and blockers: what and why, not implementation diaries. Chat and panels complement each other without repeating the same report. Ask Pi for a persistent report, for example: “Track the release prep in an ephemlet.” Reports can carry checklists, for example a plan whose steps you can veto while Pi works: “Put the plan in an ephemlet checklist so I can untick steps.” Your ticks override Pi's own marks and never start a turn; Pi reads them at its next checkpoint. Pi can also ask questions there: a choice between options, a yes/no confirmation, or a short free-text answer. For text, focus the field and press `enter` or `space` to edit inline; `enter` submits and `escape` cancels. Long answers wrap inside the field instead of scrolling out of sight. Open questions show `needs you` in the panel and in the indicator above the editor, for example `Ephemlets 2 · 1 needs you`. A confirmation also raises a one-time notification. Answers reach Pi as a visible message. While Pi is working, every choice, text and confirmation answer steers it before its next step. When Pi is idle, a confirmation starts a turn; choices and text wait for your next prompt, and only your latest answers are sent. Each question shows this before you answer: a muted `next turn` label, or a warm-tinted header with an `instant` label for answers that start Pi right away. Rapid clicks are combined into one message. When Pi cannot continue without an answer, it may wait for it: only Pi's tool call pauses, the question shows `agent waiting`, you get a notification, and your answer returns to Pi directly instead of as a message. Waits end after five minutes by default. The panel header shows `unread`, then `sent`, then `read` once the model has actually received your latest answers. Ephemlets have stable IDs and persist with the session. Tool rows stay compact; Pi's normal tool expansion reveals bounded detail previews. The agent reads metadata by default and explicitly requests source or bounded last-rendered text when needed. It never sees a screenshot. New and restored ephemlets start as a small count-and-keybind indicator above the editor. Creation and updates do not open the large view or steal your current selection. `/ephemlets` or `alt+e` toggles compact and expanded views; `ctrl+alt+e` opens and focuses the panel. The expanded overlay appears on the right in landscape terminals and at the top in portrait terminals. It covers underlying content rather than reflowing the transcript. The panel is drawn with background colors from your Pi theme instead of box-drawing characters: a header band with a checklist progress bar, read receipt and icon controls, banded question headers, and highlighted rows for focus and mouse hover. Items you untick after Pi had checked them are struck through and marked as yours. When a theme names terminal palette colors, the panel asks the terminal for their values to blend its tints; terminals that do not answer get plain theme colors instead. URL clicks use Pi's native hyperlink handling; availability still depends on terminal hyperlink support. Within the panel: arrow and page keys scroll, `tab`/`shift+tab` move between checklist items and answers, `space` or `enter` selects one, `alt+left/right` switches ephemlets, `ctrl+s` saves, `ctrl+w` deletes, and `escape` collapses to the indicator. Clicking items and answers, header controls, and wheel scrolling require Pi fullscreen mode; regular mode retains terminal-owned mouse handling. Icons use Nerd Font glyphs by default. Without a Nerd Font, set plain Unicode symbols in `~/.pi/agent/settings.json`: ```json { "ephemlets": { "icons": "unicode" } } ``` **Delete removes the ephemlet from the active session branch; hiding does not.** **Save sends an exact snapshot and save instructions to the main agent as a follow-up, rather than directly exporting it.** Agent-written interactive components have been removed in favor of these declarative fields. Sessions that still contain one show a notice in its place; the original data stays in the session file. [Installation](../../README.md#install) ### Commands | Command | Purpose | | --- | --- | | `/ephemlets` | Toggle compact/expanded ephemlets, or show/hide/focus panel | ### Setting names | Setting | Environment | | --- | --- | | `ephemlets.icons` | `PI_EPHEMLETS_ICONS` | #### Setting values | Setting | Default | Valid values | Purpose | | --- | --- | --- | --- | | `ephemlets.icons` | `"nerd"` | `"nerd"`, `"unicode"` | Icons: Glyphs for checkboxes, receipts and panel controls: Nerd Font icons, or plain Unicode for fonts without them. |