A session is a conversation between you and an agent. Each session tracks the full history of prompts you send and the responses the agent generates.
Every session runs in one of three modes, which determine the working directory the agent operates in. The mode is chosen when the session is created and cannot be changed afterwards.
| Mode | Working directory | Use for |
|---|---|---|
| Worktree (default) | A fresh git worktree on a dedicated branch | Feature work, experiments, anything you want isolated from your other sessions |
| Project Root | The project's root directory itself | Cross-branch operations like merging or rebasing session branches back into main |
| Scratch | An empty ephemeral directory under the session dir | Using the agent as a general assistant without exposing your project's sources |
You choose a mode from the New Session split button in the sidebar — see Creating a Session for the UI, and the sub-sections below for the semantics.
Each worktree session runs inside its own git worktree — an isolated copy of the project's repository. This means:
acp-session/<session-id>) created from the project's current HEAD at the time the session starts.For more details on working with worktrees, including how to commit, rebase, and merge changes, see the Worktrees guide.
If the project's root path is not a git repository, worktree creation is impossible and every new session falls back to Project Root mode automatically — the agent runs in the project root directly and the session is badged with the orange ROOT pill, just like an explicitly-created project-root session.
Worktrees are the recommended way to work: they keep each session isolated on its own branch, let you review per-session diffs, and make the commit / merge / pull-request actions meaningful. To encourage that, the sidebar behaves differently when the project root is not a git repo:
Clicking Initialise Git Repository runs three git commands in the project root, in order:
git init — create the .git directory.git add -A — stage every file already in the project root (respecting any existing .gitignore). If you had sources in the folder before adding it to Braide, they are captured by the initial commit so worktree sessions inherit them.git commit --allow-empty -m "Initial commit" — seed HEAD so git worktree add has something to branch from. --allow-empty means the step still succeeds on a truly empty project folder. If no git identity is configured globally, the commit is retried with a placeholder Braide <acp@local> author so a freshly-installed machine isn't blocked.Once init completes, the sidebar re-queries the git status, the banner disappears, and the split button reverts to its normal worktree-first behaviour. You can amend the initial commit (for instance to change the author or message) from any session or from your own terminal.
If the init fails — for example because the project root is inside another non-writable git repository, or git isn't on $PATH — the error message is shown in red inside the banner and the UI stays in the non-git state so you can retry.
A project-root session runs the agent directly in the project's root path, with no worktree and no dedicated branch. It is designed for actions that need to see the real repository state, such as merging a session branch back into main.
Project-root sessions are marked with an orange ROOT pill in the sidebar and behave differently from worktree sessions:
git status / git diff before committing.A scratch session runs in an empty directory created under the session storage (~/.braide/projects/<project-id>/sessions/<session-id>/worktree/). There is no git repository and no project source — the agent starts with an empty slate.
Scratch sessions are marked with a blue SCRATCH pill in the sidebar and are useful for:
Like project-root sessions, scratch sessions have no git repository, so the branch selector, branch-related sidebar actions, and session-branch rename/archive operations are all suppressed.
When a scratch session is deleted, its directory is removed with the rest of the session storage — nothing persists in the project.
If the worktree cannot be created or the agent handshake fails (agent not running, protocol error, timeout, etc.), the session's setup is aborted. Rather than disappearing silently, the session is kept in the sidebar at failed status so you can see what went wrong:
failureReason is persisted on the session's meta and surfaced as the row subtitle ("Setup failed: {reason}").acpId, so commit / merge / pull-request actions are disabled in the context menu.When an agent is upgraded or restarted, the ACP session ID that the agent previously knew may no longer exist. Braide handles this transparently so you can keep working without manually recreating the session.
When you send a prompt to a session whose agent has restarted:
Load attempt — Braide first tries loadSession to restore the session on the agent side. If the agent supports this capability and the session ID is still valid, the session resumes normally.
Fallback to new session — If loadSession fails (the agent no longer recognises the session ID), Braide automatically creates a new session via newSession and remaps the app-level session to the new ACP ID. All in-memory state (listeners, config options, project mappings) and on-disk metadata are updated so subsequent operations use the new ID.
History compression — The conversation history from the original session is compressed into a summary and prepended to your prompt. This gives the agent enough context to continue where it left off.
The history summary is built from the persisted event stream (events.jsonl) and uses a tiered approach to fit within an 8 KB budget:
Per-round extraction — Events are grouped into prompt-response rounds. Each round captures:
rawInput fields rather than full output)Tiered detail levels — All rounds start at full detail. If the total exceeds the budget, the oldest rounds are progressively downgraded:
| Level | Includes |
|---|---|
| Full | Prompt (400 chars), agent message (600 chars), verbose tool list, diff summary, outcome |
| Compact | Prompt (200 chars), tool counts only, outcome |
| Minimal | One-line summary with prompt snippet and tool count |
| Dropped | Omitted entirely, with a count shown in the header |
Tool call de-duplication — Within each round, file-oriented tool calls are de-duplicated to reduce noise:
| Scenario | Rule |
|---|---|
| Write to a file | Discard all prior Read, Edit, and Write for that file |
| Read before a Write | Discard the Read (the Write replaces the entire file) |
| Read before Edit(s) | Keep both — the Read provides context, but de-duplicate if the same file was read multiple times (keep only the latest Read) |
| Multiple Edits to the same file | Keep all (edits may target non-overlapping regions) |
| Multiple Reads with no subsequent Edit or Write | Keep only the latest Read |
| Grep / Glob searches | Always kept — the file system may have changed between searches |
The summary uses structured rawInput fields (file paths, commands, patterns) rather than tool output, which is typically much larger.
When a session is recreated, a context compressed card appears in the event stream at the boundary between old and new history. It shows an amber indicator with the total number of rounds and a breakdown of how many were rendered at each detail level (full, compact, minimal, omitted).
Each session in the sidebar displays a status icon that reflects its current state:
| Status | Indicator | Description |
|---|---|---|
| Initializing | Rotating dashed arc | Server has created the session record but the worktree or agent handshake is still in progress. The sidebar subtitle reads "Setting up…" |
| Not started | Hollow circle | Session is fully set up but no prompt has been sent yet |
| Running | Animated spinner | Agent is actively processing a prompt |
| Running with plan | Segmented donut chart | Agent is working through a plan — shows completed (green), in-progress (blue), and pending (grey) segments with a count (e.g. 2/5) |
| Paused | Orange pause icon | Session is waiting for user input (e.g. a permission request) |
| Completed | Green checkmark | Agent has finished and the session is idle |
| Error | Red X | Something went wrong mid-session — check the session for error details |
| Failed | Red X on a tinted disk | Session setup did not complete (worktree or agent handshake failed). The subtitle reads "Setup failed: {reason}" and the row stays in the sidebar until you delete or archive it |
When a session is running with a plan, the donut chart animates with a rotating glow to indicate active work, and the segment proportions update in real time as tasks are completed.
While a session is running, you'll see a stream of events in the event history.
As the agent works, the session tracks cumulative cost and context window usage. This information is displayed in a status bar anchored to the bottom of the session view, above the prompt input, rather than inline in the event stream.
$0.2819).used / total (percentage) (e.g. 37,120 / 1,000,000 (3.7%)).When the agent is actively working, the cost info appears right-aligned on the same line as the "Working..." status indicator. When the agent is idle, the cost info remains visible on its own as long as usage data has been reported for the session.
On the same status bar, to the left of the cost and context figures, two optional pill buttons summarise the delegation activity that has happened in the session:
Agent/Task tool calls spawned by the main agent to delegate a subtask).Skill tool.Each pill is hidden when its count is zero, so a session with no delegation shows only the running cost/context figures. The count comes from the same tool-call events that populate the Tool Calls area — no separate instrumentation is needed, and the figures update live as new calls arrive.
Clicking a pill opens a popover anchored above the button with a grouped breakdown:
Explore, Plan, general-purpose), the number of times it was called, and the unique descriptions passed to each call. Sub-agents without an explicit type fall back to general-purpose.likec4-dsl, tdd) and the number of times it was loaded.In both popovers, groups are sorted by call count (most-used first), then alphabetically. Press Escape or click outside the popover to dismiss it; click the originating pill again to toggle it closed.
A third pill — Files N — appears on the same status bar, to the right of the sub-agent and skill pills. It surfaces where the agent's Read / Write / Edit / MultiEdit / NotebookEdit tool calls have landed in the worktree, giving you three signals at a glance: hotspots, coverage, and the balance between reads and writes.
status: "completed" are counted — pending and failed calls are ignored.Clicking the pill opens an anchored popover whose bottom edge sits just above the pill. As you expand or collapse rows, the popover's top edge grows or shrinks while its bottom stays pinned — so the relationship between the popover and the pill remains stable. When there isn't enough room above (e.g. the session view is short), the popover flips below the pill instead.
The popover shows a condensed activity tree — only directories on the path to a touched file plus the touched files themselves.
3 reads, 2 writes. Reads are rendered in the accent colour; writes share a second, warmer hue. All write-style tools (Write, Edit, MultiEdit, NotebookEdit) share the write colour — the UI does not distinguish between them.+N untouched files summary counts the direct siblings in that directory the agent has not touched. It's display-only in the compact view — it helps you see coverage without widening the popover.A maximise icon in the popover header opens the full File activity modal.
The modal renders the same tree on a larger canvas with two additional capabilities:
+N untouched files rows are clickable. Expanding one reveals the specific untouched siblings inline at low opacity, so you can see which files were skipped — useful for judging whether the agent missed something it should have considered.A tab bar is reserved at the top of the modal for future visualisations (treemaps, timelines, etc.); in the current version only the tree tab is implemented.
Press Escape or click outside the modal to dismiss it; clicking a file row inside the modal opens it in the editor and closes the modal.
git ls-files via the session worktree tree API — the same source the File Browser uses). If the listing hasn't loaded or fails, the +N untouched files rows simply don't render; the touched-file tree still works.Some agents break their work into a structured plan — a list of tasks with progress tracking. When a plan is active, it appears as an anchored bar at the bottom of the session view.
Each plan item has a status icon:
The plan bar updates in real time as the agent works through tasks.
By default, the plan bar is collapsed. In this state it shows:
Click anywhere on the plan bar to expand it. The expanded view shows the full list of all plan items with their status icons, scrollable if the list is long. Click the bar again to collapse it back to the summary view. The toggle arrow rotates to indicate the current state.
The prompt input supports several features:
/ to see available commands with fuzzy matching autocomplete@ to autocomplete file paths for attaching contextYou can continue typing and submitting prompts while the agent is processing a previous one. Instead of blocking input, the prompt is added to a queue that is displayed as a row of removable chips above the input area.
When the agent completes its current task, all queued prompts are automatically sent together as a single prompt submission. Each queued prompt becomes a separate content block so the agent sees them as distinct instructions.
The left sidebar lists all sessions for the current project:
Status icon — Shows the current state of each session (see Session Status Indicators above)
Auto-labeling — Sessions are automatically labeled based on the first prompt text
Rename — Click a session name to rename it
Subtitle — Below each session label, a subtitle line shows the persona name (when the session was created with a persona) or the agent name (for sessions without a persona, or when the original persona has since been deleted), followed by the session creation date. The agent ID is used as a last resort if the agent is not currently known to the client. See Using Personas in Sessions for how personas are associated with sessions.
Mode pill — Sessions in a non-default mode display a coloured pill next to the agent/date line: orange ROOT for project-root, blue SCRATCH for scratch sessions
Context menu — Click the kebab menu (three dots) on a session item to access actions:
For a failed session the menu is still available but the commit, merge, and pull-request entries are disabled — there's no agent connection or session branch to act on. Archive and Permanently Delete are the only meaningful actions and are how you remove the row from the list.
For details on configuring commit and merge actions, see the Actions guide.
Click the cancel button (visible while the agent is running) to stop the agent mid-response. The session remains open and you can send new prompts.
You can have multiple sessions open within a project. The sidebar lets you switch between them. Each session maintains its own independent conversation history and isolated worktree with its assigned agent.