Tallow Expert Skill

When This Triggers

• User asks about tallow architecture, internals, or source code
• How extensions work, their API, or how to create them
• The pi framework (ExtensionAPI, tools, commands, events, types)
• Configuration (settings.json, themes, keybindings, packages)
• How skills, agents, or prompts are loaded and discovered
• Debugging or troubleshooting tallow itself
• How the TUI, session management, or model registry works

Procedure

Invoke the tallow-expert agent via the subagent tool:

{ "agent": "tallow-expert", "task": "<the user's question>" }

The agent explores the tallow source code and returns an answer. Relay that answer to the user.

Quick Reference

Agent frontmatter fields: tools, disallowedTools, maxTurns, mcpServers, context: fork, agent, model

Extension API Surface

Extensions export a default function receiving ExtensionAPI (conventionally named pi):

Registration

• registerTool(tool: ToolDefinition<TParams, TDetails>) — Register a tool that the LLM can call.
• registerCommand(name: string, options: Omit<RegisteredCommand, "name">) — Register a custom command.
• registerShortcut(shortcut: KeyId, options: object) — Register a keyboard shortcut.
• registerFlag(name: string, options: object) — Register a CLI flag.
• registerMessageRenderer(customType: string, renderer: MessageRenderer<T>) — Register a custom renderer for CustomMessageEntry.
• registerProvider(name: string, config: ProviderConfig) — Register or override a model provider.

Messaging

• sendMessage(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: object) — Send a custom message to the session.
• sendUserMessage(content: string | (TextContent | ImageContent)[], options?: object) — Send a user message to the agent.
• appendEntry(customType: string, data?: T) — Append a custom entry to the session for state persistence (not sent to LLM).

Session

• setSessionName(name: string) — Set the session display name (shown in session selector).
• getSessionName() — Get the current session name, if set.
• setLabel(entryId: string, label: string) — Set or clear a label on an entry.

Tools & Model

• getFlag(name: string) — Get the value of a registered CLI flag.
• exec(command: string, args: string[], options?: ExecOptions) — Execute a shell command.
• getActiveTools() — Get the list of currently active tool names.
• getAllTools() — Get all configured tools with name and description.
• setActiveTools(toolNames: string[]) — Set the active tools by name.
• getCommands() — Get available slash commands in the current session.
• setModel(model: Model<any>) — Set the current model.
• getThinkingLevel() — Get current thinking level.
• setThinkingLevel(level: ThinkingLevel) — Set thinking level (clamped to model capabilities).
• events — Shared event bus for extension communication.

Events (pi.on(event, handler))

Session lifecycle

Agent lifecycle

Tool events

Input & resources

Message streaming

ExtensionContext (ctx in event handlers)

• ui — UI methods for user interaction
• hasUI — Whether UI is available (false in print/RPC mode)
• cwd — Current working directory
• sessionManager — Session manager (read-only)
• modelRegistry — Model registry for API key resolution
• model — Current model (may be undefined)
• isIdle() — Whether the agent is idle (not streaming)
• abort() — Abort the current agent operation
• hasPendingMessages() — Whether there are queued messages waiting
• shutdown() — Gracefully shutdown pi and exit.
• getContextUsage() — Get current context usage for the active model.
• compact(options?: CompactOptions) — Trigger compaction without awaiting completion.
• getSystemPrompt() — Get the current effective system prompt.

ExtensionCommandContext (ctx in command handlers, extends ExtensionContext)

• waitForIdle() — Wait for the agent to finish streaming
• newSession(options?: object) — Start a new session, optionally with initialization.
• fork(entryId: string) — Fork from a specific entry, creating a new session file.
• navigateTree(targetId: string, options?: object) — Navigate to a different point in the session tree.
• switchSession(sessionPath: string) — Switch to a different session file.
• reload() — Reload extensions, skills, prompts, and themes.

ExtensionUIContext (ctx.ui)

• select(title: string, options: string[], opts?: ExtensionUIDialogOptions) — Show a selector and return the user's choice.
• confirm(title: string, message: string, opts?: ExtensionUIDialogOptions) — Show a confirmation dialog.
• input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions) — Show a text input dialog.
• notify(message: string, type?: "info" | "warning" | "error") — Show a notification to the user.
• onTerminalInput(handler: TerminalInputHandler) — Listen to raw terminal input (interactive mode only).
• setStatus(key: string, text: string) — Set status text in the footer/status bar.
• setWorkingMessage(message?: string) — Set the working/loading message shown during streaming.
• setWidget(key: string, content: string[], options?: ExtensionWidgetOptions) — Set a widget to display above or below the editor.
• setFooter(factory: ((tui: TUI, theme: Theme, footerData: ReadonlyFooterDataProvider) => Component & { dispose?() — Set a custom footer component, or undefined to restore the built-in footer.
• setHeader(factory: ((tui: TUI, theme: Theme) => Component & { dispose?() — Set a custom header component (shown at startup, above chat), or undefined to restore the built-in header.
• setTitle(title: string) — Set the terminal window/tab title.
• pasteToEditor(text: string) — Paste text into the editor, triggering paste handling (collapse for large content).
• setEditorText(text: string) — Set the text in the core input editor.
• getEditorText() — Get the current text from the core input editor.
• editor(title: string, prefill?: string) — Show a multi-line editor for text editing.
• readonly theme — Get the current theme for styling.
• getAllThemes() — Get all available themes with their names and file paths.
• getTheme(name: string) — Load a theme by name without switching to it.
• setTheme(theme: string | Theme) — Set the current theme by name or Theme object.
• getToolsExpanded() — Get current tool output expansion state.
• setToolsExpanded(expanded: boolean) — Set tool output expansion state.