Conversations and tools

Give the agent a task, follow its tool activity, and continue work in a project conversation.

A session is a conversation about work in a project. It keeps your messages, the agent’s replies, and a record of the tools it used. You can return to the same session later instead of explaining the task again.

Sessions

1. Select your project in the sidebar and choose New session, or open an existing session.
2. For a new session, choose Current checkout or New worktree above the message box. See Projects and worktrees if you’re unsure which to use.
3. Choose a model beside the message box. If a model appears under several providers, choose the provider you connected.
4. Describe the result you want, the files or behavior involved, and anything the agent must leave alone.

For example:

Find where this app validates email addresses. Explain the current behavior
and suggest a test for an address with surrounding spaces. Don't edit files yet.

Changing the model

You can switch an open session to another model at any time with the model selector beside the message box. The session keeps the new model, including after you restart OpenWaggle. The choice belongs to that session only: other sessions keep their models, and new sessions still start with the project’s default.

If the agent is working when you switch, the current turn finishes on the model it started with. A note above the message box says which model your next message will use, and it disappears once your next message, or a message you queued, starts on the new model.

Keep related work in the same session. Start another session for an unrelated task. Multiple sessions using Current checkout can edit the same files, so a new conversation alone does not isolate their changes.

Session titles

A new session first shows your opening message as its title. A second or two later, OpenWaggle replaces it with a short generated title such as “Fix sidebar row overlap”, so you can find the session again weeks later. Workers are titled the same way from the task they were given.

The title stays put after that. If your first message was too vague to name, for example “fix this” or a bare screenshot, OpenWaggle titles the session once more after the agent’s first reply. It never re-titles a session as the conversation moves on, and a title change never moves a session in the sidebar.

To rename a session, double-click its title in the sidebar or in the header, press F2 on a focused row, or choose Rename session from the row menu. Enter or clicking away saves, and Escape cancels. A title you chose is never replaced by a generated one. Regenerate title in the same menu asks for a new title from the whole conversation and applies it right away.

Titles are generated by the Title model in Settings > Connections. By default it uses the cheapest available model from the same provider and model family as the session, for example Claude Haiku for a Claude Sonnet session on Amazon Bedrock, in the same region. Your message goes nowhere it wasn’t already going. Choose Off to keep the opening message as the title.

Sessions from the Pi CLI

If you also use the pi command, the sessions you start with it show up in OpenWaggle on their own. There is nothing to import. A pi session appears under a project when you started it in that project’s folder or in any folder inside it, for example packages/api. It takes a few seconds after OpenWaggle opens, or after the session is created.

It is the same session, not a copy. Open it to read the conversation, then send a message to carry on. Later, pi --resume in the terminal picks up the same history, including what you added in OpenWaggle. If you continue the session in the terminal while OpenWaggle is open, OpenWaggle reads the new messages the next time you open it or send a message. Avoid writing to the same session from both at the same moment, since neither one waits for the other.

When you send a message in a session that pi used last, OpenWaggle first asks where to continue it. Continue in OpenWaggle sends the message. Keep running in pi opens the session’s terminal in the folder the session ran in, with pi --session <file> typed in for you to run, and keeps your message in the composer. Tick Remember for this project to skip the question in that project next time. The choice is yours only: it is saved in your OpenWaggle settings, not in the project, and you can change it per project in Settings > General > Pi sessions. Messages from agents and the openwaggle CLI are never held back by it.

A few things to know:

• The title is the name you gave it with /name in Pi. Without one, it is titled like a session started in OpenWaggle: from its first message, and then by the Title model when that message is less than a day old. Older sessions keep the first message as their title. A later /name changes it too, unless you renamed the session in OpenWaggle; then your title stays.
• When you continue it, the agent works in the folder you started the pi session in, with the model and thinking level the session last used, the same way pi --resume would. If the session never changed its thinking level, it uses Pi’s default thinking level: a .pi/settings.json in the folder you started the session in wins over your global Pi settings, as it does for pi. A model that offers fewer levels gets the nearest one it has.
• If you keep Pi’s sessions somewhere else with PI_CODING_AGENT_SESSION_DIR or the sessionDir setting, OpenWaggle looks there too, and stores its own new sessions there so pi --resume finds them.
• Sessions from folders that aren’t an OpenWaggle project stay hidden. Add the folder as a project and its pi sessions appear.
• Deleting the session in OpenWaggle removes it from OpenWaggle only. The Pi session file stays, so pi --resume still has it, and OpenWaggle doesn’t list it again. Sessions you started in OpenWaggle are deleted completely, as before.
• If the Pi session file is deleted outside OpenWaggle, for example from pi --resume, the session leaves OpenWaggle’s sidebar too, since its history was in that file, unless a fork or a Worker of it still depends on it; then it stays, to read only, and says so when you open it. Until then, sending a message to it fails with a message that says so; OpenWaggle never starts a new file under the same session. If the folder that holds the file is missing, for example because it was renamed or is on a drive that is not connected, or the file is a link to such a drive or can’t be read, the session stays with its history, and says so when you open it. Until you reconnect the drive, put the folder back or make the file readable again, sending a message to it, forking, cloning or compacting it, or going to another branch fails with a message that says so. The same goes for sessions you started in OpenWaggle. A file put back later is found again.
• If the Pi file of a session you started in OpenWaggle is deleted outside OpenWaggle, the session says so when you open it. Your next message starts a new transcript: the agent no longer has the earlier conversation, and the session shows only what comes after. Until you send it, the session can’t be forked, cloned, compacted or switched to another branch. If OpenWaggle can’t read a folder that may hold a copy of the file, it doesn’t start a new transcript: the session says so and names the folder, and messages to it fail until you make that folder readable again.
• Removing a project also keeps the Pi files of its pi sessions. If you add the folder again later, they come back. If the folder is inside another project, that project lists them once the removal is done, since they were started inside its folder.
• Opening a session to read it never changes its file.
• A session you forked with /fork in Pi shows up as its own session, next to the one it came from.

Reading the sidebar

The sidebar groups sessions by project. Each row shows a title, its current state, and a timestamp. Hover a row to see its actions without hiding the timestamp.

What a row tells you

Idle sessions have no state label. Sessions needing attention also have a colored edge marker, but you don’t need to distinguish colors to read the state.

Provenance icons

Hover these icons for details about where the session works:

Conversation branches are alternate paths through the chat, not Git branches. Use the Session tree to browse them.

Narrowing the list

Type in the sidebar filter to match session titles and project names. Cmd+F on macOS or Ctrl+F on Windows and Linux focuses it. Escape clears the filters while the field has focus.

State chips beneath the filter show counts. Select one to find matching sessions across all projects, including collapsed projects. Collapsed project headings also show counts for work in progress or needing attention.

Filters reset when you quit. Sorting and collapsed project sections are remembered.

Messages

Replies appear as the model generates them. The conversation can include formatted text, thinking blocks when the model provides them, tool calls, and errors.

A tool is an action the agent can take outside its reply, such as reading a file or running a test command. Read the tool activity as well as the final answer. An agent saying a test passed is less useful than the actual command and result.

Each tool row starts with an icon for the kind of tool: a terminal for shell commands, a file for reads, the pickaxe for Workers (the same one the sidebar and Hive panel use), the MCP logo for MCP tools, a pointer for the browser preview, and so on. A row whose label shimmers is still running. A failed call keeps its text, turns its icon red and ends with ×; a finished call has no extra mark. An MCP tool reads as its server and tool name (Datadog › analyze_datadog_logs).

When the agent coordinates Workers, each row names the Worker it acted on by its current title and agent definition, for example Spawned Worker (reviewer) · Review the diff or Messaged Worker · Check main process. A spawn the agent made directly also shows the Worker’s state as the Hive panel words it and an Open button. Waiting on Workers adds no row; the spawn rows and the Hive panel show what the agent is waiting for.

Expand a tool row to inspect its arguments and output. Shell output can appear while the command is still running; a live excerpt is progress, not a success result. Failed commands keep their available output for inspection. Use Copy command or Copy output when those controls are available.

Expanding a successful edit row shows that file’s diff instead of the raw edit arguments. Select the file name to open it at the first change, or use Copy diff, Copy path, Copy args, or Copy output. Any output an extension adds to the edit, such as diagnostics, appears under the diff. A failed edit still shows its arguments and the error. To review everything a turn changed, use the changed-files card or the diff panel.

A first message reports each setup step in the conversation, such as pulling the branch, creating a worktree, or connecting an MCP server it has to wait for. Worktree created confirms the checkout exists, not that project setup or the task has finished. A configured setup command must complete before the first agent turn. See First-send worktree feedback.

If an approval request appears, check the proposed action and its target. Choose Allow once to proceed or Continue without to skip it and give different instructions. Ask for approval does not ask before every file read or guarantee that files cannot be edited.

You can send an ordinary message while the agent is busy. It waits as a follow-up rather than starting a second task at the same time. For changes already made to files, use the diff panel to review them and send corrections.

Native Pi tools

Pi is the agent engine used by OpenWaggle. Its usual starting file and shell tools are:

Other tools, including grep, find, and ls, may be available depending on the active configuration. Tool activity appears in the conversation. Agent definitions can restrict the available tools with an allowlist, so not every session has the same set.

The agent can also discover and use saved Project actions, such as your test command or development server, under its existing permissions. These are managed runs with output and controls in Session Summary > Actions, separate from the interactive terminal. Saving an action does not grant extra permission to run it.

Browser preview tools

The agent can inspect and interact with the same Browser preview you use. For example, ask it to open your running app, check a page at a phone width, and report what it finds.

Control this in Settings > Browser > Let agents open and drive the preview browser. Page-changing actions use the approval flow. Your keyboard or pointer input interrupts an agent action so you can take over.

Turning the setting off removes preview access from later turns and rejects further preview calls from a turn already running. Your own browser controls remain available. Agent access is also blocked if the setting cannot be read.

Slash command menu

Type / at the start of a word in the message box. Keep typing to filter, then use the arrow keys and Enter to choose an item.

The menu lists the built-in commands /compact, /fork, and /clone first, followed by skills, saved Waggle presets, and commands added by enabled extensions. A skill supplies instructions for a particular task. A Waggle preset sets up a multi-agent review.

In a session, the menu also lists the commands its Pi extensions register, such as Pi’s /mcp, with their descriptions. Choosing one inserts it; Pi runs it when you send the message, instead of sending the message to the model. A session is not titled from such a command: its title comes from the first real request.

When a built-in command such as /compact is the whole message, press Enter to run it. Tab or a click always completes the command so you can add text after it, such as compaction instructions. Enter also completes it when the message contains other text.

Selecting a skill or preset replaces only the slash token, keeping the rest of your draft. The selection appears as a chip before you send. A Waggle preset applies to that message, not every later message.

Global command palette

Press Cmd+K on macOS or Ctrl+K on Windows and Linux to find app actions. The palette includes new sessions, project selection, recent sessions, settings, view controls, file and content search, panels, and extension actions. Use the message box’s / menu for skills and Waggle presets.

The Panels section lists every panel the right panel can show: All panels, Changes, Project Actions, Browser, Files, Session Tree, Resources, and each extension side panel that can run, with its extension’s name beside it. Each entry shows its shortcut when it has one. Choosing a panel shows it in the right panel and never closes the right panel, even when that panel is already showing. To give a panel a shortcut, see Panel shortcuts.

The commands /compact, /fork, and /clone require the session to be idle. If work is running, wait for it to finish and submit the command again. OpenWaggle keeps your draft and attachments when it refuses one of these commands. Ordinary messages, skill prompts, and Pi extension commands can still wait as follow-ups.

Press Cmd+P or Ctrl+P for project file search. Select a result to open the file on the right. Text files support autosave with detection of changes made outside the editor. Markdown and HTML have safe previews; images and PDFs display in place. Content-search results open at the matching line.

For reducing a long conversation’s context, see Context management.

Error handling

When an action fails, the error panel shows the message and details. Use its copy action when reporting a problem. Authentication errors can link to Settings; retry and dismiss controls appear where applicable.

Closing or restarting the desktop app does not interrupt an agent run. A separate background process, the Session Host, keeps runs going. Reopen the app to check progress. If a run is actually interrupted, inspect its last tool results and files before asking it to continue. Closing the window is not a way to stop work.

Command environment

The built-in terminal is for commands you run yourself. It starts your interactive shell in the session’s Working path and loads your normal shell configuration. The agent’s bash tool has its own shell-launch behavior; it is not the terminal panel.

To share terminal output, select it, right-click, and choose Add selection to chat. This adds a removable context chip with the terminal and working-path details. Check the chip and send your message when ready. Selecting output alone sends nothing, and OpenWaggle marks it as untrusted output rather than instructions.