agent/pi - pi - Penguin

refactor(plan-mode): use smart keyword matching instead of IDs

- Remove ugly [DONE:id] tags - users no longer see IDs
- Track progress via keyword matching on tool results
- Extract significant keywords from todo text
- Match tool name + input against todo keywords
- Sequential preference: first uncompleted item gets bonus score
- Much cleaner UX - progress tracked silently in background

Helmut Januschka · 2026-01-04 18:13:29 +01:00

f6b728a6e5

refactor(hooks): address PR feedback

- Rename getTools/setTools to getActiveTools/setActiveTools
- Add getAllTools to enumerate all configured tools
- Remove text_delta event (use turn_end/agent_end instead)
- Add shortcut conflict detection:
  - Skip shortcuts that conflict with built-in shortcuts (with warning)
  - Log warnings when hooks register same shortcut (last wins)
- Add note about prompt cache invalidation in setActiveTools
- Update plan-mode hook to use agent_end for [DONE:id] parsing

Helmut Januschka · 2026-01-04 18:13:29 +01:00

4ecf3f9422

feat(plan-mode): show final completed list in chat when plan finishes

Displays all completed items with strikethrough markdown when
all todos are done.

Helmut Januschka · 2026-01-04 18:13:29 +01:00

5b634ddf75

fix(plan-mode): buffer text_delta to handle split [DONE:id] patterns

The [DONE:id] pattern may be split across multiple streaming chunks.
Now accumulates text in a buffer and scans for complete patterns.

Helmut Januschka · 2026-01-04 18:13:28 +01:00

e27a2c226c

feat(hooks): add text_delta event for streaming text monitoring

- New text_delta hook event fires for each chunk of streaming text
- Enables real-time monitoring of agent output
- Plan-mode hook now updates todo progress as [DONE:id] tags stream in
- Each todo item has unique ID for reliable tracking

Helmut Januschka · 2026-01-04 18:13:28 +01:00

d1eea3ac4e

feat(plan-mode): use ID-based todo tracking with [DONE:id] tags

- Each todo item gets a unique ID (e.g., abc123)
- Agent marks items complete by outputting [DONE:id]
- IDs shown in chat and in execution context
- Agent instructed to output [DONE:id] after each step
- Removed unreliable tool-counting heuristics

Helmut Januschka · 2026-01-04 18:13:28 +01:00

7a03f57fbe

feat(plan-mode): show todo list in chat after planning, widget during execution

- After agent creates plan: show todo list as a message in chat
- During execution: show widget under Working indicator with checkboxes
- Check off items as they complete with strikethrough

Helmut Januschka · 2026-01-04 18:13:28 +01:00

e781c9a466

fix(plan-mode): fix todo extraction from assistant messages

- AssistantMessage.content is an array, not string
- Handle markdown bold formatting in numbered lists
- Extract text content blocks properly

Helmut Januschka · 2026-01-04 18:13:28 +01:00

c09f8644be

fix(plan-mode): show widget after extracting todos and in plan mode

Helmut Januschka · 2026-01-04 18:13:28 +01:00

dd7c01a47c

feat(hooks): add setWidget API for multi-line status displays

- ctx.ui.setWidget(key, lines) for multi-line displays above editor
- Widgets appear below 'Working...' indicator, above editor
- Supports ANSI styling including strikethrough
- Added theme.strikethrough() method
- Plan-mode hook now shows todo list with checkboxes
- Completed items show checked box and strikethrough text

Helmut Januschka · 2026-01-04 18:13:28 +01:00

dc44816051

feat(plan-mode): add todo list extraction and progress tracking

- Extract numbered steps from agent's plan response
- Track progress during execution with footer indicator (📋 2/5)
- /todos command to view current plan progress
- State persists across sessions including todo progress
- Agent prompted to format plans as numbered lists for tracking

Helmut Januschka · 2026-01-04 18:13:28 +01:00

537d672f17

feat(coding-agent): add hook API for CLI flags, shortcuts, and tool control

Hook API additions:
- pi.getTools() / pi.setTools(toolNames) - dynamically enable/disable tools
- pi.registerFlag(name, options) / pi.getFlag(name) - register custom CLI flags
- pi.registerShortcut(shortcut, options) - register keyboard shortcuts

Plan mode hook (examples/hooks/plan-mode.ts):
- /plan command or Shift+P shortcut to toggle
- --plan CLI flag to start in plan mode
- Read-only tools: read, bash, grep, find, ls
- Bash restricted to non-destructive commands (blocks rm, mv, git commit, etc.)
- Interactive prompt after each response: execute, stay, or refine
- Shows plan indicator in footer when active
- State persists across sessions

Helmut Januschka · 2026-01-04 18:13:28 +01:00

c956a726ed

WIP: Add hook API for dynamic tool control with plan-mode hook example

- Add pi.getTools() and pi.setTools(toolNames) to HookAPI
- Hooks can now enable/disable tools dynamically
- Changes take effect on next agent turn

New example hook: plan-mode.ts
- Claude Code-style read-only exploration mode
- /plan command toggles plan mode on/off
- Plan mode tools: read, bash, grep, find, ls
- Edit/write tools disabled in plan mode
- Injects context telling agent about restrictions
- After each response, prompts to execute/stay/refine
- State persists across sessions

Helmut Januschka · 2026-01-04 18:13:28 +01:00

059292ead1

Merge branch 'feat/ctrl-n-external-editor' - configurable keybindings (#405 )

Mario Zechner · 2026-01-03 22:51:12 +01:00

f2b89d5ec5

docs(coding-agent): correct filename in subagent example README (#427 )

The README referenced subagent.ts but the actual file is index.ts.

Co-authored-by: Will Hampson <whamp@ggl.slmail.me>

Will Hampson · 2026-01-03 22:36:58 +01:00

d6c39655e6

feat: configurable keybindings for all editor and app actions

All keybindings configurable via ~/.pi/agent/keybindings.json

Editor actions:
- cursorUp, cursorDown, cursorLeft, cursorRight
- cursorWordLeft, cursorWordRight, cursorLineStart, cursorLineEnd
- deleteCharBackward, deleteCharForward, deleteWordBackward
- deleteToLineStart, deleteToLineEnd
- newLine, submit, tab
- selectUp, selectDown, selectConfirm, selectCancel

App actions:
- interrupt, clear, exit, suspend
- cycleThinkingLevel, cycleModelForward, cycleModelBackward
- selectModel, expandTools, toggleThinking, externalEditor

Also adds support for numpad Enter key (Kitty protocol codepoint 57414
and SS3 M sequence)

Example emacs-style keybindings.json:
{
  "cursorUp": ["up", "ctrl+p"],
  "cursorDown": ["down", "ctrl+n"],
  "cursorLeft": ["left", "ctrl+b"],
  "cursorRight": ["right", "ctrl+f"],
  "deleteCharForward": ["delete", "ctrl+d"],
  "cycleModelForward": "ctrl+o"
}

Helmut Januschka · 2026-01-03 08:23:56 +01:00

8f2682578b

fix(coding-agent): export Theme and ThemeColor for hooks to use proper types

Mario Zechner · 2026-01-03 00:13:26 +01:00

8c227052d3

fix(coding-agent): fix Theme type cast in todo hook example

Mario Zechner · 2026-01-03 00:13:26 +01:00

65d3081d80

feat(coding-agent): expose deliverAs option in hook sendMessage() API

- pi.sendMessage(msg, options?) now accepts { triggerTurn?, deliverAs? }
- deliverAs: 'steer' (default) or 'followUp' controls delivery timing
- Update all mode handlers to pass options through
- Update file-trigger example to use new API
- Update CHANGELOG

Mario Zechner · 2026-01-03 00:13:26 +01:00

9d8230dfc6

Revert /todos to custom TUI component

Mario Zechner · 2026-01-03 00:13:25 +01:00

a980998464

Change /todos to open in external editor instead of custom TUI

Mario Zechner · 2026-01-03 00:13:25 +01:00

cc7823eb45

Add todo hook companion to todo custom tool

- /todos command displays all todos on current branch with custom UI
- Update hooks.md to clarify components must not be wrapped in Box/Container
- Cross-reference tool and hook in example READMEs

Mario Zechner · 2026-01-03 00:13:25 +01:00

74dc5e7c49

Update docs for ctx.ui.editor() and handoff example

- Added ctx.ui.editor() to hooks.md and custom-tools.md
- Added ctx.ui.editor() to CHANGELOG.md
- Added handoff.ts to examples/hooks/README.md

Mario Zechner · 2026-01-02 01:26:21 +01:00

02175d908b

fix(coding-agent): prevent full re-renders during write tool streaming

Move line count from header to footer to avoid changing the first line
during streaming, which was triggering full screen re-renders in the
TUI's differential rendering logic.

Mario Zechner · 2026-01-02 01:11:06 +01:00

d51770a63d

Use serializeConversation in handoff hook

Properly handles all message types including tool calls, thinking,
and tool results instead of manual text extraction.

Mario Zechner · 2026-01-02 00:45:03 +01:00

91c52de8be

Add handoff example hook

Transfers context to a new focused session instead of compacting.
User provides a goal, hook generates a prompt with relevant context,
creates a new session with parent tracking, and loads the prompt
as a draft in the editor for review.

Inspired by Amp's handoff feature.

Mario Zechner · 2026-01-02 00:42:11 +01:00

ace0063a00

Consolidate session events: remove session_before_new/session_new, add reason field to switch events

- Remove session_before_new and session_new hook events
- Add reason: 'new' | 'resume' to session_before_switch and session_switch events
- Remove 'new' reason from custom tool onSession (use 'switch' for both /new and /resume)
- Rename reset() to newSession(options?) in AgentSession
- Add NewSessionOptions with optional parentSession for lineage tracking
- Rename branchedFrom to parentSession in SessionHeader
- Rename RPC reset command to new_session with optional parentSession
- Update example hooks to use new event structure
- Update documentation and changelog

Based on discussion in #293

Mario Zechner · 2026-01-01 23:31:26 +01:00

484d7e06bb

Add ctx.ui.theme getter for styling status text with theme colors

- Add theme property to HookUIContext interface
- Implement in interactive, RPC, and no-op contexts
- Add status-line.ts example hook
- Document styling with theme colors in hooks.md

Mario Zechner · 2026-01-01 21:58:01 +01:00

dccdf91b8c

Add setEditorText/getEditorText to hook UI context, improve custom() API

- Add setEditorText() and getEditorText() to HookUIContext for prompt generator pattern
- custom() now accepts async factories for fire-and-forget work
- Add CancellableLoader component to tui package
- Add BorderedLoader component for hooks with cancel UI
- Export HookAPI, HookContext, HookFactory from main package
- Update all examples to import from packages instead of relative paths
- Update hooks.md and custom-tools.md documentation

fixes #350

Mario Zechner · 2026-01-01 00:04:56 +01:00

6f7c10e323

Change branch() to use entryId instead of entryIndex

- AgentSession.branch(entryId: string) now takes entry ID
- SessionBeforeBranchEvent.entryId replaces entryIndex
- getUserMessagesForBranching() returns entryId
- Update RPC types and client
- Update UserMessageSelectorComponent
- Update hook examples and tests
- Update docs (hooks.md, sdk.md)

Mario Zechner · 2025-12-31 13:47:34 +01:00

8e1e99ca05

Update custom-compaction example to use serializeConversation

Also fix docs to show convertToLlm is needed first.

Mario Zechner · 2025-12-31 13:24:23 +01:00

027d39aa33

Reorder execute params: (toolCallId, params, onUpdate, ctx, signal?)

Optional signal now at the end for cleaner API

Mario Zechner · 2025-12-31 12:14:28 +01:00

19c4182c21

Rework custom tools API with CustomToolContext

- CustomAgentTool renamed to CustomTool
- ToolAPI renamed to CustomToolAPI
- ToolContext renamed to CustomToolContext
- ToolSessionEvent renamed to CustomToolSessionEvent
- Added CustomToolContext parameter to execute() and onSession()
- CustomToolFactory now returns CustomTool<any, any> for type compatibility
- dispose() replaced with onSession({ reason: 'shutdown' })
- Added wrapCustomTool() to convert CustomTool to AgentTool
- Session exposes setToolUIContext() instead of leaking internals
- Fix ToolExecutionComponent to sync with toolOutputExpanded state
- Update all custom tool examples for new API

Mario Zechner · 2025-12-31 12:05:24 +01:00

568150f18b

refactor(coding-agent): fix compaction for branched sessions, consolidate hook context types

Compaction API:
- prepareCompaction() now takes (pathEntries, settings) only
- CompactionPreparation restructured: removed cutPoint/messagesToKeep/boundaryStart, added turnPrefixMessages/isSplitTurn/previousSummary/fileOps/settings
- compact() now takes (preparation, model, apiKey, customInstructions?, signal?)
- Fixed token overflow by using getPath() instead of getEntries()

Hook types:
- HookEventContext renamed to HookContext
- HookCommandContext removed, RegisteredCommand.handler takes (args, ctx)
- HookContext now includes model field
- SessionBeforeCompactEvent: removed previousCompactions/model, added branchEntries
- SessionBeforeTreeEvent: removed model (use ctx.model)
- HookRunner.initialize() added for modes to set up callbacks

Mario Zechner · 2025-12-31 02:24:24 +01:00

ddda8b124c

refactor(hooks): split session events into individual typed events

Major changes:
- Replace monolithic SessionEvent with reason discriminator with individual
  event types: session_start, session_before_switch, session_switch,
  session_before_new, session_new, session_before_branch, session_branch,
  session_before_compact, session_compact, session_shutdown
- Each event has dedicated result type (SessionBeforeSwitchResult, etc.)
- HookHandler type now allows bare return statements (void in return type)
- HookAPI.on() has proper overloads for each event with correct typing

Additional fixes:
- AgentSession now always subscribes to agent in constructor (was only
  subscribing when external subscribe() called, breaking internal handlers)
- Standardize on undefined over null throughout codebase
- HookUIContext methods return undefined instead of null
- SessionManager methods return undefined instead of null
- Simplify hook exports to 'export type * from types.js'
- Add detailed JSDoc for skipConversationRestore vs cancel
- Fix createBranchedSession to rebuild index in persist mode
- newSession() now returns the session file path

Updated all example hooks, tests, and emission sites to use new event types.

Mario Zechner · 2025-12-30 22:42:22 +01:00

d6283f99dc

Remove allowDuringStreaming flag - commands always run immediately

Hook commands now always execute immediately, even during streaming.
If a command needs to interact with the LLM, it uses pi.sendMessage()
which handles queueing automatically.

This simplifies the API and eliminates the issue of queued slash
commands being sent to the LLM instead of executing.

Mario Zechner · 2025-12-30 22:42:22 +01:00

575c875475

Rename immediate -> allowDuringStreaming for hook commands

Mario Zechner · 2025-12-30 22:42:22 +01:00

f8352bb7d7

WIP: Major cleanup - move Attachment to consumers, simplify agent API

- Removed Attachment from agent package (now in web-ui/coding-agent)
- Agent.prompt now takes (text, images?: ImageContent[])
- Removed transports from web-ui (duplicate of agent package)
- Updated coding-agent to use local message types
- Updated mom package for new agent API

Remaining: Fix AgentInterface.ts to compose UserMessageWithAttachments

Mario Zechner · 2025-12-30 22:42:20 +01:00

6ddc7418da

Fix snake border alignment using visibleWidth for proper ANSI length calculation

Mario Zechner · 2025-12-30 22:42:20 +01:00

6977bc73ca

Snake: add full border frame and pause/resume with session persistence

- Full box border around title, game area, and instructions
- ESC pauses and saves state to session via pi.appendEntry()
- Resume shows 'PAUSED - press any key to continue'
- Q quits and clears saved state
- High score persists across games

Mario Zechner · 2025-12-30 22:42:20 +01:00

b47151a04f

Fix snake velocity: render cells as 2 chars wide for square aspect

Terminal cells are ~2:1 aspect ratio, so movement appeared faster
vertically. Now each game cell is 2 characters wide.

Mario Zechner · 2025-12-30 22:42:19 +01:00

5ae33defd3

Improve snake game visuals

- Rounded box corners (╭╮╰╯)
- Better characters: ● head, ○ body, ◆ food, · empty
- Colored title with emoji
- Dimmed borders and help text
- Bold highlights for score and controls

Mario Zechner · 2025-12-30 22:42:19 +01:00

516c0ea8bc

Add immediate flag to hook commands for non-queued execution

Commands with immediate: true run right away even during streaming.
Used for UI-only commands like /snake that don't interact with LLM.

Mario Zechner · 2025-12-30 22:42:19 +01:00

818196d2c3

Fix snake.ts: use key helpers from pi-tui for ESC and arrow keys

Mario Zechner · 2025-12-30 22:42:19 +01:00

165fb58b39

Add ui.custom() for custom hook components with keyboard focus

- Add custom() to HookUIContext: returns { close, requestRender }
- Component receives keyboard input via handleInput()
- CustomMessageComponent default rendering now limits to 5 lines when collapsed
- Add snake.ts example hook with /snake command

Mario Zechner · 2025-12-30 22:42:19 +01:00

14ad8d6228

Move exec to HookAPI, sessionManager/modelRegistry to HookEventContext

Breaking changes:
- HookEventContext now has sessionManager and modelRegistry (moved from SessionEventBase)
- HookAPI now has exec() method (moved from HookEventContext/HookCommandContext)
- HookRunner constructor takes sessionManager and modelRegistry as required params
- Session events no longer include sessionManager/modelRegistry fields

Hook code migration:
- event.sessionManager -> ctx.sessionManager
- event.modelRegistry -> ctx.modelRegistry
- ctx.exec() -> pi.exec()

Updated:
- src/core/hooks/types.ts - type changes
- src/core/hooks/runner.ts - constructor, createContext
- src/core/hooks/loader.ts - add exec to HookAPI
- src/core/sdk.ts - pass sessionManager/modelRegistry to HookRunner
- src/core/agent-session.ts - remove sessionManager/modelRegistry from events
- src/modes/* - remove setSessionFile calls, update events
- examples/hooks/* - update to new API

Mario Zechner · 2025-12-30 22:42:19 +01:00

29fec7848e

Hook API: replace send() with sendMessage(), add appendEntry() and registerCommand()

Breaking changes to Hook API:
- pi.send(text, attachments?) replaced with pi.sendMessage(message, triggerTurn?)
  - Creates CustomMessageEntry instead of user messages
  - Properly handles queuing during streaming via agent loop
  - Supports optional turn triggering when idle
- New pi.appendEntry(customType, data?) for hook state persistence
- New pi.registerCommand(name, options) for custom slash commands
- Handler types renamed: SendHandler -> SendMessageHandler, new AppendEntryHandler

Implementation:
- AgentSession.sendHookMessage() handles all three cases:
  - Streaming: queues message with _hookData marker, agent loop processes it
  - Not streaming + triggerTurn: appends to state/session, calls agent.continue()
  - Not streaming + no trigger: appends to state/session only
- message_end handler routes based on _hookData presence to correct persistence
- HookRunner gains getRegisteredCommands() and getCommand() methods

New types: HookMessage<T>, RegisteredCommand, CommandContext

Mario Zechner · 2025-12-30 22:42:18 +01:00

ba185b0571

Refactor SessionEventBase to pass sessionManager and modelRegistry

Breaking changes to hook types:
- SessionEventBase now passes sessionManager and modelRegistry directly
- before_compact: passes preparation, previousCompactions (newest first)
- before_switch: has targetSessionFile; switch: has previousSessionFile
- Removed resolveApiKey (use modelRegistry.getApiKey())
- getSessionFile() returns string | undefined for in-memory sessions

Updated:
- All session event emissions in agent-session.ts
- Hook examples (custom-compaction.ts, auto-commit-on-exit.ts, confirm-destructive.ts)
- Tests (compaction-hooks.test.ts, compaction-hooks-example.test.ts)
- export-html.ts guards for in-memory sessions

Mario Zechner · 2025-12-30 22:42:18 +01:00

9bba388ec5

Fix API key priority and compaction bugs

- getEnvApiKey: ANTHROPIC_OAUTH_TOKEN now takes precedence over ANTHROPIC_API_KEY
- findCutPoint: Stop scan-backwards loop at session header (was decrementing past it causing null preparation)
- generateSummary/generateTurnPrefixSummary: Throw on stopReason=error instead of returning empty string
- Test files: Fix API key priority order, use keepRecentTokens=1 for small test conversations

Mario Zechner · 2025-12-30 22:42:17 +01:00

251fea752c

Session tree structure with id/parentId linking

- Add TreeNode base type with id, parentId, timestamp
- Add *Content types for clean input/output separation
- Entry types are now TreeNode & *Content intersections
- SessionManager assigns id/parentId on save, tracks leafId
- Add migrateSessionEntries() for v1 to v2 conversion
- Migration runs on load, rewrites file
- buildSessionContext() uses tree traversal from leaf
- Compaction returns CompactionResult (content only)
- Hooks return compaction content, not full entries
- Add firstKeptEntryId to before_compact hook event
- Update mom package for tree fields
- Better error messages for compaction failures

Mario Zechner · 2025-12-30 22:42:17 +01:00

c58d5f20a4

73 Commits