Timeline & Bookmarks

As agent sessions grow longer and more complex, understanding the historical flow of events and auditing what happened becomes crucial. Braide provides a visual Timeline Strip and Bookmarks feature to help you navigate, filter, and reference specific moments in a session's history in real time.

Timeline Toggle

The timeline is associated with each active session and can be toggled on or off using the Timeline Toggle button (represented by a clock/ruler icon) in the right-hand area of the Session Header toolbar.

When visible, the timeline strip mounts directly above the session transcript area. To save vertical space or focus solely on conversation, you can also collapse or expand the lanes on the timeline strip itself using the chevron toggle button located directly on the strip. This collapse preference is persisted in your local storage (localStorage) per session, meaning it survives unmount/remount operations and full page reloads.

Note: On narrow viewports (below 480 pixels), the timeline strip is force-collapsed and the chevron toggle is hidden to ensure the UI remains clean and readable.

Visual Lanes & Event Glyphs

The timeline strip visualizes the session's history by partitioning events into five distinct horizontal lanes, each populated with visual glyphs corresponding to specific event types:

  1. Conversation: Represents the core human-agent chat.
    • User Prompts are rendered as solid teal dots (●).
    • Agent Messages are shown as rounded teal pills with medium opacity (0.7).
    • Agent Thoughts are rendered as light teal pills with lower opacity (0.4) to denote internal reasoning.
  2. Tools: Displays tool use.
    • Completed Tool Calls are rendered as solid rectangular pills colored with the tool theme color.
    • Pending Tool Calls are shown with reduced opacity and dashed borders to indicate they are currently running.
  3. Permissions: Displays user approval interactions.
    • Pending Permission Requests appear as amber markers with an active pulsing animation to capture your attention.
    • Approved/Denied Permissions turn solid and are colored green or red depending on the outcome.
  4. Lifecycle: Highlights critical session markers.
    • Displays errors, completions, "phantom" completions, and context-compression events.
  5. Metadata: Contains background/context events.
    • Displays plan changes, plan transitions, token usage summaries, terminal commands, config option updates, and code diff reports.

Interacting with Event Glyphs

  • Hover (Preview Card): Hovering over any event glyph displays a Hover Preview Card after a short delay (80ms). This 240px-wide card provides crucial details:
    • Header: The raw event type (e.g. tool_call) and wall-clock time (hh:mm:ss).
    • Subtitle: A kind-specific subtitle (e.g. user prompt, agent thought, tool name and status).
    • Body: Up to 120 characters of representative event body/arguments.
    • Footer: Tool execution duration and relative time elapsed from wall-clock now (e.g., 5m 12s ago).
  • Click (Focus Event): Clicking on an event glyph immediately dispatches a focus event that scrolls the session transcript to focus directly on that event card.

Timeline Filtering (Range Selection)

The timeline strip is not just a passive display—it acts as an interactive filter for the main session transcript. You can isolate a specific window of time to focus your audit or review:

  • Drag to select custom range: Click and drag horizontally across any area of the timeline strip. This sets a custom start and end time filter range, filtering the main session transcript to display only events that fell within that range. The filtered range is rendered on the timeline as an overlay bracket in accent color with a time readout (e.g., 14:34:18 → 14:38:22).
  • Click to select default range: Single-clicking at any point $t$ on the timeline strip sets a default 4-minute filter range centered on that point ([t - 120s, t + 120s]).
  • Double-click to clear filter: Double-clicking anywhere on the timeline strip clears the active range filter and restores the full transcript view.

Bookmarks

Bookmarks allow you to tag specific, meaningful moments in a session with custom labels, serving as jump points that survive across sessions.

Adding a Bookmark

To bookmark an event:

  1. Locate the event card in the main session transcript.
  2. Right-click on the event card to summon the Add Bookmark Popover.
  3. The popover text field will auto-focus and be pre-seeded with a default label (the first 40 characters of the event's text) selected so you can overwrite it immediately.
  4. Press Enter or click Save to persist the bookmark. Press Escape or click outside to dismiss without saving.

Viewing and Navigating Bookmarks

Bookmarks appear on the timeline strip as amber downward triangles (▼) situated directly above the timeline's ruler.

  • Bookmark Overlaps (Badges): When multiple bookmarks are chronologically close enough that their glyphs would overlap, they are automatically grouped into cluster badges showing the count (e.g., ▼·3).
  • Clicking a Bookmark: Clicking any bookmark triangle or cluster badge immediately focuses and scrolls the session transcript to the corresponding bookmarked event. Clicking a bookmark resolves its target block as the first renderable block at-or-after the bookmark's timestamp.