Chat & Tools
How Pi-backed project sessions and native tool events work in OpenWaggle.
Sessions
OpenWaggle uses project-scoped sessions. The sidebar groups sessions under project sections; there is no separate global Chats section.
To start work:
- Select a project folder.
- Create or select a session under that project.
- Pick an enabled provider-qualified model in the composer.
- Send a message.
Session branches are Pi session branches inside a session, not Git branches. Use the right-side Session Tree to inspect and navigate the full Pi node graph.
Messages
Assistant output streams from Pi session events. OpenWaggle projects those events into a renderer-friendly transcript with:
- Markdown text.
- Thinking blocks when Pi emits thinking events.
- Tool call blocks when Pi emits tool activity.
- Errors and stop/cancel state from the active run.
Native Pi Tools
Pi owns active tool selection. OpenWaggle does not pass an explicit allowlist to Pi. With the current Pi SDK defaults, the initial built-in tools are read, bash, edit, and write; OpenWaggle also renders Pi search/listing tools when Pi enables or emits them.
| Tool | Purpose |
|---|---|
read | Read file contents. |
write | Create or replace files. |
edit | Apply file edits. |
bash | Run shell commands. |
grep | Search file contents. |
find | Find files. |
ls | List directory contents. |
Pi owns tool execution. OpenWaggle renders the resulting events directly in the transcript.
Command Palette
Press Cmd+K / Ctrl+K or type / at the start of the composer input.
Current command-palette uses include:
- Skill references.
- Waggle presets.
/compactfor manual Pi compaction./forkto choose a previous user turn and copy that branch into a new session./cloneto copy the current selected node path into a new session.- Open Session Tree for branch and node navigation in the active Pi session.
Error Handling
When something fails, OpenWaggle shows a structured error panel with the message, details, copy action, settings shortcut for auth errors, and retry/dismiss controls where relevant.
If the app closes while a run is active, OpenWaggle does not auto-resume it on restart. It refreshes the latest Pi session snapshot, marks the affected session branch as interrupted, and shows a compact inline notice when you open that branch. Dismissing the notice or sending a new message from that branch clears the indicator.
Command Environment
The integrated terminal uses OpenWaggle’s filtered terminal environment. Pi’s bash tool follows Pi SDK runtime behavior and currently receives Pi’s shell environment, not OpenWaggle’s terminal filter.