Running a Session

Sessions are where you interact with agents. This guide covers the full workflow from creation to conversation.

Creating a Session

1. Make sure you have a project selected and at least one agent running

2. Click New Session in the left sidebar. The New Session button is a split button — clicking the main body creates a default worktree session; clicking the chevron to the right opens a menu with two other modes:

   • New Session in Project Root — run in the project's root directory with no worktree. Useful for merging session branches back into main. Only one such session is permitted per project, so the option is disabled when one already exists. See Project Root Mode.
   • New Session in Scratch Directory — run in an empty ephemeral directory with no project sources. Useful for general assistant use without touching the project. See Scratch Mode.

   If the project root is not a git repository, the split button adapts: the primary action becomes New Session in Project Root, the caret-menu hides the now-redundant project-root entry, and a banner beneath the button offers an Initialise Git Repository action so worktree mode can be enabled with one click. See Projects Without a Git Repository for the full behaviour.

3. Select a persona or agent from the dropdown in the prompt toolbar:

   • If the project has personas configured, the persona selector is shown. Choosing a persona automatically selects its preferred agent, applies its MCP servers and config options, and prepends its instructions to your first prompt.
   • If no personas are configured, the agent selector is shown and you choose an agent directly. Your last-used capability choices for that agent are restored automatically — see Remembered Capability Choices below.
   • If personas are configured but you want to skip them for this session, pick No persona from the top of the persona dropdown. The agent selector appears alongside it so you can choose an agent directly — the session is then created exactly as in the no-personas flow above, with no persona instructions, MCP servers, or config overrides applied. See Opting Out with "No Persona" for the full behaviour.

4. A new row appears in the sidebar immediately — showing a rotating dashed spinner and a stepped subtitle that ticks through Preparing session… → Creating workspace… → Connecting to agent… while the server provisions the worktree and completes the agent handshake. These are the same steps you see on the welcome splash, so both views agree on where setup currently is. The row transitions to ready once setup finishes and you can send your first prompt. If anything fails on the way — worktree creation error, agent not reachable, handshake timeout — the row flips to failed with the error as its subtitle and stays in the list until you delete or archive it. Non-worktree sessions display a coloured mode pill (ROOT or SCRATCH) from the moment the row appears, so the badge stays put across the whole setup. See Session Status Indicators and Failed Session Setup for the full lifecycle.

   You can click New Session several times in quick succession to queue up multiple setups — each click creates its own session row and they provision in parallel.

Remembered Capability Choices

Many agents expose capability options — things like model selection, thinking mode, or permission bypass — in the config options bar that sits above the prompt input. The value you pick for each option is remembered so you don't have to reconfigure the agent every time you create a session.

Where choices are stored depends on whether the project uses personas.

Setup	Source of truth	Scope
Personas configured	The selected persona's Agent Config Options (see Personas > Agent Config Options)	Per persona, per agent. Each persona carries its own set of overrides, so switching personas picks up that persona's configuration.
No personas	Project preferences, keyed by agent id	Per project, per agent. Each agent remembers its own last-used values independently.

How the no-persona flow works:

1. When you land on the New Session view, Braide loads the project preferences and seeds the agent selector with the last-used agent.
2. A session is created for that agent. As soon as the agent reports its config options, any values previously chosen for this agent are re-applied on top of the agent's defaults. You see the remembered values immediately; they are also sent to the agent via the session config API so the first prompt runs with the correct configuration.
3. Any change you make in the config options bar before sending the first prompt is written back to project preferences. Once the session is running, in-session changes are session-local and do not update the remembered defaults — this matches the persona flow, where overrides are edited through the Personas settings page rather than the live session.
4. If the agent's schema has changed since you last used it (an option was removed, or a select value is no longer legal), stale entries are silently dropped when applying overrides, so the session always starts in a valid state.

Why the split? Personas already give you multiple named configurations per agent, so a separate project-level store would duplicate that behavior and could silently mask the persona's overrides. The direct-agent flow has no equivalent "named configuration" concept, so project preferences fill that gap — but only when no personas are defined, avoiding any conflict with the persona model.

Branch Selector

When a new worktree session is created, the prompt toolbar includes a branch selector that lets you pick the branch the worktree will be created from. The session's new branch is started from exactly that commit. Once the first prompt is sent the selector locks to indicate the base branch is fixed; changing it afterwards from the session view recreates the worktree against the new ref.

The selector only appears when the session has a git worktree, so it is hidden for:

• Worktree sessions in a project whose root is not a git repo — the session is auto-promoted to project-root mode, and there is no branch list to pick from.
• Project Root sessions — these don't track a base branch or own a session branch, so the selector would have no effect.
• Scratch sessions — these run in an empty directory with no git repository at all.

The branch list excludes Braide's own session branches (current, archived, and deleted) so the dropdown only offers genuine project branches.

Sending Prompts

Type your message in the prompt input at the bottom of the screen and press Enter (or click the send button).

Prompt Features

• Multi-line — Press Shift+Enter for new lines; Enter sends the prompt
• Slash commands — Type / to open a command autocomplete menu. As you continue typing, the list is filtered using fuzzy matching. Use the arrow keys to navigate and Enter or Tab to select a command. Press Escape to dismiss.
• File references — Type @ to open a file autocomplete menu. The menu loads file paths from the session's worktree asynchronously and filters them as you type. Select a file to attach it as context for the agent. Use arrow keys to navigate and Enter or Tab to confirm.
• Rich text responses — The </> toggle in the prompt toolbar opts the agent into HTML artifacts that render inline as interactive panels (comparison cards, multi-question forms, custom editors). See Rich Text Responses for the full feature and the companion skill download.
• Config options — Some agents expose configuration options in a bar above the prompt input

Both the / and @ menus can also be opened via buttons next to the prompt input, which is useful on touch devices or if you prefer clicking.

Pasting Code

When you paste multi-line content into the prompt input, the app tries to identify the language of the pasted text and, if it recognises one, wraps the paste in a triple-backtick fenced code block tagged with that language:

```typescript
import { useState } from "react"

export function Counter() {
  const [n, setN] = useState(0)
  return <button onClick={() => setN((c) => c + 1)}>{n}</button>
}
```

The agent receives the prompt with the fence tag intact, so it knows the attached material is typescript and not prose — useful when you're asking it to review, refactor, or diff pasted snippets. When the paste is later rendered back in the message stream, the same fence tag drives syntax highlighting.

What triggers auto-fencing:

• Multi-line paste (contains at least one newline) — single-line pastes always go through unchanged.
• Not already fenced — if the clipboard contents already start with ```, the paste is inserted as-is so manually constructed blocks aren't double-wrapped.
• Recognised as code — the server-side detector returns a confident language guess. Prose (including text that happens to start with words like "Create a…" or "Select …") is left as plain text.

Detection runs locally so there is no perceptible delay before the text appears in the input. If detection fails for any reason, the paste falls back to plain text — you never lose content.

Recognised languages include all of the common ones listed under Code Syntax Highlighting. Short snippets (a handful of lines) are more likely to fall through as plain text than longer, structurally distinctive code; if you want a specific language tag, type the opening fence (e.g. ```sql) before pasting. JSON is a special case: any paste that parses as valid JSON is tagged as json regardless of length, so small objects and arrays get fenced reliably.

Action Buttons

If you have configured actions in the project settings, additional buttons appear in the prompt input toolbar. The Run, Build, Test, and Browse actions are shown as icon buttons between the terminal toggle and the config options bar. Each button has a distinctive icon and a tooltip showing the action name. When multiple actions are defined for a type, a split button is shown — click the primary button to run the default action, or click the chevron to choose from alternatives.

Clicking an action button executes its configured command:

• Terminal mode actions open the session terminal pane (if not already visible) and run the command there. You can see the command output directly in the terminal at the bottom of the session view.
• Agent mode actions send the prompt text to the active agent. The agent's response appears inline in the session's message stream, just as if you had typed the prompt yourself.

Action buttons are only visible when they have been configured with a non-empty prompt in project settings. See Settings & Preferences for how to configure them.

Media Attachments

Click the paperclip icon in the prompt toolbar (next to the command menu button) to attach local image or video files to the next prompt. The button is available as soon as a session is being created — attachments added during setup are persisted once the session is ready.

File Picker

The picker opens a filesystem browser titled Attach Media, showing both image files (png, jpg, jpeg, gif, webp, svg, bmp, heic, heif) and video files (mp4, webm, mov, avi, mkv, m4v). Directories appear first, then media files with thumbnails (images) or a play icon (videos) and sizes. Click a directory to navigate into it, or use the up-arrow button to go to the parent.

Default location. The picker opens at the last directory you attached from, remembered per project. If that directory was inside your session's worktree, it is stored as worktree-relative and re-resolved against the current session's worktree on next open — so it "follows" you across worktrees. The first time you open the picker in a project it defaults to the current worktree directory.

Selecting files. Both image and video files are selectable using the same controls:

Action	Behaviour
Click	Select just that file
Cmd/Ctrl-click	Toggle an individual file in the selection
Shift-click	Select a contiguous range from the previously clicked file
Cmd/Ctrl+Shift-click	Add a range to the existing selection
Double-click	Select that file and attach immediately
Enter	Attach the current selection
Escape	Cancel without attaching

Click Attach (N) to attach the selected files and remember the current directory for next time.

Selection restrictions. You cannot mix video and image files in the same selection — doing so disables the Attach button and displays a warning: "Cannot mix video and image files in one selection". You also cannot select more than one video file at a time; selecting multiple videos shows: "Only one video file can be selected at a time". These restrictions exist because video files are routed to the Video Keyframe Modal for frame extraction, which processes one video at a time.

Video files. When a single video is selected and you click Attach (or double-click it), the picker closes and the Video Keyframe Modal opens so you can select specific frames to extract.

Drag and Drop

The entire session view — prompt input, message stream, session header — acts as a drop target for image and video files. You can drag media from any external source that provides file data:

• Finder, Explorer, or any native file browser
• A web browser's downloads bar, address bar, or inline image (drag-to-save)
• Other Electron apps that expose files (Slack attachments, etc.)
• Terminal emulators that support file drag
• Bookmark-style drag sources that carry an image URL (browser fallback only — see below)

Visual feedback. While you're dragging files over the session view, a dashed cyan overlay labelled "Drop images or videos to attach" appears above the content. If multiple files are involved, the overlay stays until the last one is released. Non-media files are silently skipped at drop time, so mixed drags (media + text files, for example) only process the media portion.

Mixed drops. You can drop images and videos in one gesture. Image files become individual attachment pills (as before). If a video file is included, the first video opens the Video Keyframe Modal so you can extract frames from it. Image files in the same drop are attached immediately.

Supported formats. Images: png, jpg, jpeg, gif, webp, svg, bmp, heic, heif. Videos: mp4, webm, mov, avi, mkv, m4v. Files with other extensions are silently ignored, and drops that contain no media files are no-ops.

What happens on drop depends on the runtime:

Runtime	Behaviour
Electron desktop app	Image attachments reference the file in place — nothing is copied or uploaded. Video files open the keyframe modal directly. The file must remain at that path when the prompt is sent; if it has been moved or deleted by then, that one image is skipped with a warning and other images go through.
Plain browser	Each file is uploaded to the session's storage area (the overlay briefly shows "Uploading…"). Uploads are capped at 100 MB per file to accommodate video. Uploaded files are removed automatically when the session is deleted.

New-session caveat (browser only). In the browser, drag-and-drop requires the session to already exist because uploads are session-scoped. If you drop media in the new-session view before sending your first prompt, the drops are silently skipped. Either use the paperclip picker (which doesn't need a session) or send a prompt first to create the session. The Electron desktop app does not have this limitation.

After drop. Dropped images become regular attached image pills — same color coding, same detach behaviour, same preview popover, same "only unsent images are re-sent" rule on prompt submit. Video frames extracted via the keyframe modal also become image pills after extraction.

Video Keyframes

When you select or drop a video file, a Video Keyframe Modal opens where you can scrub through the video and capture specific frames to send to the agent as image attachments. See the Video Keyframe Editor guide for full details on video loading, the filmstrip timeline, play/pause controls, keyframe capture, and keyboard shortcuts.

Attached Image Pills (Composing vs Submitted)

Attached images go through two visual phases in the interface:

• Prior to Submission: They appear as pills in the prompt composing area directly above the prompt textarea. These pills are color-coded in cyan and carry a small image icon. You can hover over a pill and click its × button to detach it, or click the pill to open the Image Preview Popover described below.
• Post-Submission: Once the prompt is submitted (or queued), they disappear from the composing area. To access them, click the Attachments button (the paperclip icon) in the Session Header toolbar (next to the Reset button). This opens the Attachments Popover, displaying all images and GitHub issues attached to the session. Clicking any image pill inside the attachments popover opens its preview.

Attachments are references only — the underlying file is never copied, so detaching leaves the file on disk untouched. Frames extracted from video keyframes appear as regular image pills indistinguishable from directly attached images.

Image Preview Popover

Clicking an image pill (either in the prompt composing area before submission, or in the session header's Attachments Popover after submission) opens a preview popover anchored underneath the pill. Inside the popover:

• Click the image to toggle between the anchored preview and a full-screen view. Click again to return.
• Left/Right arrow keys cycle through all attached images in both preview and full-screen modes (with wrap-around). The popover re-anchors under the pill matching the current image.
• Click another pill while the preview is open to move the preview to that pill; click the same pill again to dismiss the preview.
• Escape closes the preview from either mode.

Historical image thumbnails also appear in the past prompt cards in the event stream — click any thumbnail to open the same preview popover.

Opening an Image as a Tab

The preview popover also contains an Open as tab button (the arrow-out-of-square icon, next to the close button). Click it to promote the current image onto the session's main canvas as a dedicated tab — the popover closes and the new tab becomes the active one. One tab per image: switching to another image in the popover and clicking "Open as tab" opens a second tab rather than replacing the first.

The image tab simply displays the image at the largest size that fits the tab area. It sits alongside any open file or issue tabs and follows the same interaction model: switch with a click, reorder by drag, close with the × on the tab, and the state persists with the session so the tab reappears when you return.

See File Browser & Editor → Tabs for full details on tab behaviour.

Sending Images to the Agent

When you submit a prompt, any attached images that haven't been sent in a previous prompt for this session are delivered to the agent alongside your text. Images already sent in a prior prompt are not re-transmitted. This keeps token usage predictable when images accumulate across multiple prompts.

Text is required. An image-only prompt cannot be submitted — images describe what, but the agent still needs text telling it what to do with them. The send button stays disabled until you type a prompt (or an unsent issue provides the instructions). When keyframes are extracted from a video, the auto-inserted caption text satisfies this requirement.

If an attached image has been moved or deleted on disk by the time you send the prompt, it is silently skipped for that request and a warning is logged. Other images go through as normal.

Queued Prompts

You don't have to wait for the agent to finish before sending your next prompt. While the agent is running, you can continue typing and pressing Enter to queue additional prompts.

Queued prompts appear as small chips labelled Queued above the prompt input. You can remove any queued prompt by clicking its × button, or click a chip to edit its text. Drag and drop chips to reorder them — prompts are sent in the order they appear from left to right.

When the agent completes its current task, all queued prompts are automatically flushed as a single submission. Each queued prompt is sent as a separate content block so the agent treats them as individual instructions.

While the agent is running, the send button keeps its regular appearance — only its tooltip changes to "Queue prompt" to indicate that the submission will be queued rather than sent immediately. Both the stop button and the send button are visible at the same time, so you can cancel the current run or queue follow-up work as needed.

You can also queue prompts for a future time using scheduled tasks. Click the clock icon in the prompt toolbar to set a schedule — all prompts submitted while a schedule is active are queued and sent automatically at the scheduled time.

Reading Responses

Agent responses stream in real time as a series of events.

Chat Messages

The agent's text responses are rendered as markdown with support for headings, code blocks, lists, tables, and links. Fenced code blocks with an explicit language tag are tokenised and colour-coded — see Code Syntax Highlighting for the supported languages and palette. Fenced blocks tagged mermaid, likec4, or c4 render as interactive diagrams instead. Blocks tagged braide render as inline HTML artifacts — see Rich Text Responses.

Tool Calls

When the agent uses tools (reading files, running commands, searching), the tool calls are collapsed into the agent message or thinking block that preceded them. Each such block dedicates its right-hand column to a Tool Calls area containing:

• A header — the label Tool Calls and a completed/total count.
• A status-dot grid — one small square per tool call, colour-coded by outcome: amber for pending, green for completed, red for failed. The grid wraps across multiple lines so every tool call is always represented and a dot pops briefly when its call finishes. Hovering a dot shows the tool name and, when the call has a short description (for commands and delegated tasks), that description is used as the tooltip.
• A disclosure chevron (▾) aligned to the middle-right that rotates when the area is expanded.

Click anywhere in the Tool Calls area to reveal the individual tool call cards inside the same block, below the message text and separated by a thin divider. Each card shows the tool name, arguments, result, and status. Click again to collapse. If a permission request arrives while the agent is running, the area auto-expands so the request is visible.

When a tool call card is collapsed and its input includes a description, a small info icon appears in the card header (right-aligned, before the status badge). Hovering the icon reveals a popover containing the full description, so you can scan the purpose of each call without expanding it. The icon is omitted for tools that don't supply a description.

Tool calls that arrive with no preceding agent message or thinking block — for example, right after a user prompt — still render as a standalone Tool Calls panel below the prompt, with the same dot grid and expansion behaviour.

Permission Requests

Some tool calls require your approval before the agent can proceed. Braide renders these as permission cards inside the Tool Calls area where the request originated, and pauses the agent until you respond.

What Triggers a Request

The agent decides which tool calls need approval — Braide does not maintain its own allowlist. In practice you'll see permission cards for actions the agent's runtime classes as side-effectful (running shell commands, network fetches, plan-mode exits, mode switches). Side-effect-free reads, writes, searches, and listings are auto-approved (see Safe-kind auto-approval below) and never reach the card.

Anatomy of the Card

Each permission card has three parts:

• Header — A warning glyph, the tool's canonical name (e.g. Bash, WebFetch, ExitPlanMode), and an optional Show details / Hide details toggle. When the request resolves, a status pill on the right shows the outcome (Always allowed, Allowed once, Denied, or Not responded).
• Detail line — For tool calls in canonical ToolName(argument) form, the argument is rendered below the header in monospace. Long paths are abbreviated against the session's worktree (e.g. …/worktree/src/foo.ts); click any abbreviated segment to reveal the full path, then Hide full paths to re-abbreviate.
• Markdown body — When the agent attaches rationale to the request (for example the proposed plan during an ExitPlanMode request), the body is rendered as collapsible markdown so you can read it before answering.

Choosing an Outcome

The agent supplies the available options on each request. Most permission cards show two buttons in a green/red pair, but agents may offer more granular choices:

Option kind	Colour	Effect
allow_once	Green (filled)	Approve only this tool call. The next equivalent call will prompt again.
allow_always	Green (outline)	Approve this call and signal to the agent that it may continue similar calls without re-prompting for the rest of this turn / session, per the agent's own internal policy. Braide does not persist the decision across sessions.
reject_once	Red (filled)	Reject only this tool call.
reject_always	Red (outline)	Reject this call and ask the agent not to retry similar calls in this turn.
Deny	Red (filled)	Synthetic fallback shown when the agent provided no reject option. Returns a cancelled outcome to the agent.

If you close the session, refresh the page, or otherwise interrupt without choosing, the request is recorded as Not responded and the agent receives a cancellation when the session resumes.

When options are short they share one horizontal row that wraps as needed; when an option's label is prose-length the card switches to a vertical stack so the text isn't truncated.

Safe-kind Auto-approval

Braide auto-approves permission requests whose ACP kind is one of read, write, search, or list, provided the agent offered at least one allow option. The approval is returned to the agent immediately (preferring allow_always over allow_once when both are present) and an auto_approved event is appended to the session log with reason: "safe_kind" and the toolCallId. The card is not shown to the user — the underlying tool call still appears in the Tool Calls grid like any other approved call.

Auto-approval is intentionally limited to those four read/write-style kinds. Anything classed as execute, fetch, think, switch_mode, or any kind the agent leaves unset is always shown to the user.

UI Behaviour

• The Tool Calls area that contains a pending permission auto-expands the moment the request arrives, so the card is visible without hunting.
• The session's status icon switches to the orange Paused indicator while any permission request is unresolved — see Session statuses.
• Once you've responded, the card collapses to a single-line summary (header + outcome pill) and the agent resumes.
• Replayed permission events keep their final outcome — there is no way to "undo" a response after the agent has consumed it.

Permission outcomes are not currently persisted across Braide sessions. Each new session starts with a blank slate, and allow_always only signals intent to the agent's own runtime — it does not pre-approve future Braide sessions.

Diff Reports

When the agent modifies files, a diff report card appears showing a summary of all changes — files added, modified, deleted, or renamed — along with addition/deletion counts. Click a file row to expand the inline diff viewer.

For worktree sessions branched off a base branch, the card groups changes by commit so you can follow the work commit by commit:

• One section per commit — ordered oldest first, from the base branch up to the latest commit. Each section header shows the commit's short SHA and subject, followed by the files that commit changed with that commit's own incremental diff — the change introduced by that commit alone, not the accumulated total.
• Uncommitted changes — the final section: files with staged, unstaged, or untracked changes that haven't been committed yet.

The inline card shows each commit's incremental diff. To see the accumulated change per file since the base branch — every commit plus the working tree folded together — open the full-screen modal with the Expand button.

A single file can appear in several sections — for example, changed in two commits and then edited again in the working tree. Each entry carries a colour-coded source pill so you can tell what a row represents once expanded:

• COMMITTED — followed by the short SHA of the commit that touched the file (with +N and a tooltip listing the rest when multiple commits touched it)
• STAGED — added to the git index but not yet committed
• UNSTAGED — modified in the working tree but not staged
• UNTRACKED — a new file not yet added to git

Diff Viewer

The expanded diff viewer provides three view modes, selectable via tabs in the toolbar:

Mode	Description
Unified	Standard unified diff with old and new line number gutters. Changed lines are highlighted with word-level precision — individual tokens that differ within a line are emphasised so you can see exactly what changed.
Split	Side-by-side comparison with the old file on the left and the new file on the right. Word-level highlights are applied on each side independently.
Raw	The unformatted patch text. A copy button appears in the toolbar to copy the raw diff to the clipboard.

Your selected view mode is persisted across sessions and restored automatically the next time you view any diff.

Full-Screen Modal

Click the Expand button in the diff toolbar (visible in Unified and Split modes) to open the diff in a full-screen modal. The modal provides:

• File navigation — When the diff report contains multiple files, a dropdown in the modal header lets you jump to any file. The modal lists the accumulated patch per file since the base branch; a file changed both in commits and in the working tree shows as separate entries with their own source pills, so you can navigate between the accumulated committed patch and the working-tree patch independently. Previous/next buttons and keyboard shortcuts cycle through entries in a carousel (wrapping from last to first and vice versa).
• Keyboard shortcuts — Left arrow or [ for the previous file, Right arrow or ] for the next file. Up/down arrows scroll the diff content. Escape closes the modal.
• View mode toggle — Unified and Split tabs are available in the modal header, matching the inline viewer.
• Source pill — The current entry's source pill is shown next to the file dropdown so you can tell at a glance whether you're viewing a committed patch (with its short SHA) or a working-tree patch.

Click Collapse or press Escape to return to the inline view.

Commit Actions

If you have configured commit actions in project settings, a commit button appears in the diff report header:

• If a single commit action is configured, its button is shown with the action's name
• If multiple commit actions are configured, a split button is shown. The main button executes the first (default) commit action. A disclosure chevron on the right opens a dropdown with the remaining commit actions as alternatives.

For terminal mode commit actions, the command runs in the session terminal and output appears in the terminal pane. For agent mode commit actions, the prompt is sent to the agent and the response appears in the session's message stream.

Cost and Context Usage

A status bar between the event stream and the prompt input shows the session's running cost and context window consumption. When the agent is working, these figures appear right-aligned alongside the "Working..." indicator. When the agent is idle, the cost and context usage remain visible so you can review them at any time. See Cost and Context Usage in the Sessions concept page for details.

Sub-agent and Skill Counters

The same status bar also surfaces two optional pill buttons — Sub-agents N and Skills N — that appear to the left of the cost figures once the agent has made its first corresponding tool call. They roll up the delegation activity for the session at a glance:

• The pills update live as the agent works and survive session reload.
• Each pill is hidden when its count is zero, so sessions with no delegation show only the cost/context numbers.
• Clicking a pill opens a popover summarising which sub-agent types or skills have been used, with per-group call counts. Sub-agent calls also list the unique descriptions passed to each invocation so you can recognise what was delegated.
• Click the same pill again, click outside the popover, or press Escape to close it.

See Sub-agent and Skill Usage in the Sessions concept page for full details of the data model behind the pills.

File Activity

To the right of the sub-agent and skill pills, a Files N pill shows where the agent's file operations have landed. N is the number of distinct files touched so far (only completed operations count). The pill stays hidden until the first file operation completes and then updates live as the agent works.

Clicking the pill opens an anchored popover above the pill with a condensed view of the worktree:

• Only directories on the path to a touched file are shown — the rest of the tree is hidden. Directories start collapsed; click to expand.
• Each row carries a small read/write mini-bar and the total call count. Reads and writes are colour-coded. Hover the bar for a tooltip showing the exact counts (e.g. 3 reads, 2 writes).
• Below each expanded directory, a greyed +N untouched files line counts the sibling files in that directory the agent has not touched — a quick way to gauge coverage.
• Click a file row to open it in the file editor; the popover closes automatically.
• Files outside the session worktree root appear under a distinct Outside worktree branch at the bottom.

A maximise icon in the popover header opens a larger modal with two tabs — a Tree view with filename search and clickable +N untouched files rows, and a Treemap view that sizes each directory by its aggregate activity so hotspots jump out spatially. The treemap drills down one directory at a time and lets you re-weight rectangles by Total, Writes, or Reads. Use the modal when you want to investigate coverage, find a specific file quickly, or eyeball where the agent concentrated its effort.

When rows are expanded or collapsed, the popover resizes upwards from its bottom edge so the pill stays in place — no jumping. Press Escape or click outside to dismiss either the popover or the modal.

See File Activity in the Sessions concept page for the data model and classification rules.

Cancelling a Session

While an agent is running, a cancel button appears next to the prompt input. Click it to stop the agent mid-response. The session stays open — you can continue sending new prompts.

Session Recovery After Agent Restart

If an agent is upgraded or restarted while you have existing sessions, Braide automatically recovers them. When you send your next prompt, the system detects that the agent no longer knows the session and transparently creates a new one, compressing the previous conversation history into a summary that is sent alongside your prompt. A context compressed indicator appears in the event stream to mark the boundary.

No manual action is required — just keep prompting as usual. For details on how the history is compressed, see Session Recovery.

Managing Sessions

Renaming

Sessions are automatically labeled based on the first prompt. To rename:

• Click the session name in the sidebar or header
• Type a new name and press Enter

Deleting

Click the delete icon next to a session in the sidebar to remove it. This is permanent.

Archiving and Unarchiving

From a session's sidebar context menu, choose Archive to put a finished session to one side. Braide removes the session's worktree directory immediately (reclaiming the per-session disk cost) but preserves the session's committed history and uncommitted changes in git so the session can be restored later.

When you open an archived session, the terminal, file browser, and prompt input panes are replaced by a small archived affordance panel showing:

• The base branch the session was created from
• The short SHA of the session's last commit
• An indicator if uncommitted work was captured at archive time
• An Unarchive session button to restore the worktree and continue working
• A View committed diff button to inspect what the session changed without unarchiving

The transcript above the affordance stays visible as read-only history. Unarchiving recreates the worktree, reapplies any captured uncommitted changes, and re-runs the worktree setup command — because ignored files like node_modules are not preserved across archive.

See Archive & Retention for the full lifecycle, including how the background pruner permanently deletes archived sessions after a retention window, and how to protect individual sessions from automatic pruning.

Switching

Click any session in the sidebar to switch to it. Each session maintains its own conversation history.