Monitoring & Analytics¶

Squad provides real-time monitoring, detailed execution history, and analytics to help you understand how your agent teams perform.

Monitoring Dashboard¶

The squad monitoring dashboard is your control center during execution. It uses a seven-tab layout to organize information:

Overview Tab¶

The Overview tab shows a summary of the squad's current state. When any agent across any squad is waiting for tool-execution approval, a pinned Waiting for Approval section appears at the top of the tab, above the hero stats. It aggregates pending requests from all squads in a single view so no approval goes unnoticed while you are watching a different squad.

Each row in the approval section shows the agent ID, the tool name requesting approval, and a risk badge (safe, low, medium, high, or critical). Clicking a row opens the approval dialog for that request. The section collapses automatically once all pending approvals are resolved.

Hero Stats¶

At the top of the dashboard, three key metrics are shown at a glance:

• Active / Total agents — How many agents are currently running out of the total configured
• Session tokens — Cumulative token consumption for the current session across all agents
• Execution phase — Current phase of the squad execution (idle, planning, executing, aggregating, etc.)

Agent Activity¶

Below the hero stats, the Agent Activity section shows all agents in the squad. A List/Grid toggle in the section header switches between two layouts.

List view renders agents as a flat, sortable list. Each row shows the squad name, agent name, status badge, and a live preview of the agent's current task. Rows are sorted by urgency: running agents first, then agents waiting for approval, then agents in error, then idle.

Grid view renders each agent as a card in a responsive grid (1 column on mobile, 2 on tablet, 3 on desktop). Each card shows the agent name, status, token usage, and last activity. The grid uses the same filter controls as the list view.

Both views share the same two filter controls:

• Name filter — Type to filter by agent name (150 ms debounce, case-insensitive).
• Status chips — Click a chip (Running, Waiting, Error) to show only agents in that state. Chips display a count badge and only appear when at least one agent matches the status.

Clicking any row or card navigates to the agent's detail view at /squad/{squadId}/agent/{agentId}.

When no agents are configured, an empty state message is shown. When filters are active but match nothing, a "no match" message appears instead.

Execution Timeline¶

Below the agent activity section, the Execution Timeline shows each agent's state transitions as horizontal swimlanes. Each colored block represents one transition, sized proportionally to how long the agent spent in that state.

Colors correspond to agent states: green for running, red for error, yellow/amber for created, blue for completed, and gray for idle. Hover over a block to see a tooltip with the state label, duration, timestamp, and error cause if applicable.

A time axis below the swimlanes shows relative timestamps from the earliest recorded event to now. When no state transitions have been recorded yet, a placeholder message appears and the timeline populates automatically as agents run.

Activity Feed¶

A chronological log of squad events, including:

• Agent session started/stopped
• Task assigned, started, completed, or failed
• Memory updated
• Workspace file changed
• Budget warnings and overages

The feed updates in real time and keeps the most recent 200 entries. The following event types appear in the feed:

• Agent started, completed, or errored
• Task created or completed
• Full execution completed

Budget Meter¶

The budget meter (shown at the top of the Overview tab) displays real-time progress toward the squad's configured token and cost limits. It animates while the squad is executing. See Budget & Safety for details on setting limits.

Chat Tab¶

The Chat tab provides a conversational interface for interacting with the squad. Use it to:

• Send a new task or question to the squad
• Monitor streaming responses from agents as they execute
• Review the conversation history for the current session

Task Board¶

The Task Board tab provides a Kanban-style view of all tasks in the current execution:

Each task card shows:

• Task title and assigned agent
• Priority level (color-coded)
• Dependencies on other tasks
• Result summary or error message (when applicable)

Click a task card to open the Task Detail panel with the full description, output, logs, and token usage. From this panel you can also manage the task directly:

• Edit the title, description, priority, dependencies, and retry ceiling, while the task is pending, ready, or assigned. Once an agent is running the task, only the description, the priority, and the retry ceiling remain editable.
• Retry a failed or cancelled task. Once a task has used up its retry budget, the button switches to an extra-attempt retry that must be chosen explicitly.
• Reassign a pending, ready, or assigned task to a different agent, or unassign it.
• Delete a task. Deleting a task an agent is actively holding asks for confirmation to cancel that work first.

Workspace Tab¶

The Workspace tab provides a file browser for the squad's workspace directory. You can:

• Browse directories and preview files created by agents
• View logs, plans, task outputs, and generated artifacts

Discussion Room Tab¶

The Discussion tab is the landing for the squad's discussions: a structured, turn-based conversation space where the squad's agents take turns responding to a shared topic, with the orchestrator enforcing turn order and budget. The tab holds the create panel, the in-progress list, and the completed history. Opening a discussion navigates to its own full-height page at /squad/<squad-id>/discussion/<discussion-id>, so the transcript gets the whole content area instead of sitting inside a card inside a tab.

Creating a Discussion¶

The Start a new discussion card on the left of the tab is the creation form. Type the question or task in the Discussion topic field (it is focused when the tab opens; up to 1 024 bytes), choose a mode, and set a turn budget (1 to 100 turns per run cycle). Participants default to all squad agents but can be narrowed to a subset. Click Create discussion to open the room. Creating a room does not start it: press Start in the room's header, or the Start action shown in the empty transcript, when the agents should begin.

The Room Page¶

The room is a single header line above a full-height transcript, matching the per-agent chat page.

The left of the header carries identity: a back button that returns to the Discussion tab, the topic (click it to switch to another discussion in this squad, in-progress ones listed above completed ones), the status badge, the turn counter, and a participant avatar stack. The agent currently speaking is ringed in the stack, so you can follow the turn order with the outputs panel closed.

The right of the header carries actions: a settings chip summarising mode, turn budget, and streaming, which opens a popover holding all four controls; exactly one lifecycle button for the room's current state (Start or Resume with a play glyph, Pause while running, and none once the room has finished); an overflow menu with Stop, Refresh, Export, and Delete, the same menu control used elsewhere in the app; and a toggle for the outputs panel. An idle or paused room whose transcript is still empty repeats the Start or Resume action in the transcript itself.

A finished discussion shows no disabled controls on the header line. Its settings chip still opens, read-only, so you can see how the room was configured.

The Transcript¶

Each agent turn renders as a speaker byline above the reply. With streaming on, the reply appears token by token while the agent writes it. A turn that used tools, or that carried inline thinking, gets one collapsible Activity Capsule above its prose, the same capsule the chat surfaces use: it lists the tool calls with their results, and while the turn is still running it shows each call as in progress from the moment the agent invokes it, so a long tool call is visible rather than a blank wait. The capsule collapses once the turn finishes and stays out of the way until you open it.

The URL is what decides which room is open, so a room link can be pasted into a new window or bookmarked. An unknown or already-deleted id shows a not-found message with a link back to the squad.

The Outputs Panel¶

The right-hand panel holds the four Phase 3 deliverables (Conclusion, Handoff, Export, Analytics) described below. It collapses to a narrow strip through the header toggle, and its state is remembered across restarts.

Until you toggle it for the first time, the room's status picks the default: a running or paused room opens with the panel collapsed, because reading the transcript is the point, and a finished room opens with it expanded, because the conclusion is. After your first toggle your choice applies to every room, so a discussion that finishes while you are reading it will not reopen the panel on you.

Below 960px wide the panel becomes an overlay drawer rather than a second column. There it opens only when you ask for it: a drawer covers the transcript, so neither the room's status nor a collapse you chose on a wider window opens one on its own.

Discussion Modes¶

Two mode presets are available:

Strategy Selector¶

Below the mode toggle, an optional Strategy selector lets you override the engine the orchestrator uses to pick the next speaker. When set to Default, the mode determines the engine automatically. Explicit options:

The Default setting (no explicit override) maps Moderated mode to the Moderator strategy and Brainstorm mode to the deterministic Brainstorm (legacy) strategy. Setting an explicit strategy overrides this mapping for the lifetime of the room (until the user resets it to Default or the room is stopped).

Discussion Status¶

A status badge reflects the orchestrator's state machine: idle, running, paused, awaiting user, completed, cancelled, or error. The room header offers exactly the transition the current state allows: Start, Pause, or Resume as the primary button, with Stop in the overflow menu while the room has not yet terminated.

User Injection¶

While a discussion is running you can type a message in the input box and inject it into the agent turn queue. The message is delivered at the next turn boundary. Up to 10 messages may be queued at once. Queued messages appear in a strip above the input box; click the cancel icon on any entry to dequeue it before it is consumed.

Termination and Automatic Completion¶

A discussion ends when any of the following conditions is met:

• The turn budget is exhausted (status transitions to awaiting user; the user may inject a message to re-arm another budget cycle).
• The user clicks Stop (status: cancelled, reason: UserStopped).
• The consensus gate fires: in Moderated mode the facilitator agent is asked every 3 turns whether the group has converged. If it reports high confidence (≥0.8) the room transitions to completed with reason ConsensusReached.
• The idle watchdog fires: a room that has had no new message and no queued input for 5 minutes auto-completes with reason IdleTimeout.
• A room parked in awaiting user with no queued messages for 10 minutes auto-completes with reason BudgetExhausted.

The termination reason is shown as a status badge on the discussion card in the History panel.

Conclusion Synthesis¶

Once a discussion has at least one message, click Synthesize Conclusion in the Phase 3 panel to trigger an LLM call against the facilitator agent. The facilitator reads the full transcript (or a head-plus-tail excerpt for very long discussions) and returns a structured conclusion with four sections: a short summary, key points, decisions, and action items (each with an optional suggested owner). The conclusion is persisted on the room and rendered in the Conclusion tab of the outputs panel. You can re-synthesize at any time; each call overwrites the previous conclusion in place.

Handoff to Squad Execution¶

After a conclusion is synthesized, click Start Execution to hand the discussion outcome off to the squad's execution engine. The backend assembles the topic, summary, decisions, and action items into a request string and submits it to submit_squad_request. The request string is capped at 8 kB so it never trips the execution planner's length validator. A success notification shows the new execution's ID; click it to navigate to the execution view.

The Auto-approve toggle (default: off) controls whether the planner's decomposition goes straight to execution or pauses for your review.

Transcript Export¶

Open the outputs panel's Export tab (the header's overflow menu has an Export shortcut that opens it) and choose a format:

The downloaded file is named discussion-{short-id}-{sanitized-topic}.{ext}. The topic fragment is limited to 40 alphanumeric characters.

Discussion Analytics¶

The Phase 3 panel shows a per-discussion analytics card with:

• Total messages and agent turns
• Per-agent turn count and token usage (prompt + completion)
• Total transcript token usage
• Synthesis token usage (separate from the transcript total, so you can see what the conclusion call cost)
• Discussion duration (only shown once the room is in a terminal status)
• Strategy change history (which strategy was active at each turn)

Discussion History¶

The Discussion tab lists all completed, cancelled, and error rooms for the squad, newest first, below the in-progress ones. Each card shows the topic, status badge, termination reason, participant count, message count, and timestamps. Click a card to open that room's page with its full transcript and conclusion. The list is paginated (up to 50 entries per page) and refreshes automatically after a room reaches a terminal status. Because the tab subscribes to discussion events for the whole squad, an in-progress row keeps updating while you are on the tab, including for rooms you have never opened.

Runs Tab¶

The Runs tab is a two-column surface: a run library rail on the left lists this squad's past executions, and the right side shows the full detail view for whichever run is selected.

Run Library Rail¶

The rail lists executions newest first, each row showing a status icon, the plan title (or the original request when no plan title was recorded), and a timestamp. Type in the search box to filter by request text, plan title, or status. The list refreshes automatically every 30 seconds, and a Load more button pages through older runs.

The rail is a listbox, not a stack of clickable cards. It holds a single tab stop that moves with the arrow keys (roving tabindex): Up and Down move to the adjacent row, Home and End jump to the first or last row, and Enter or Space selects the focused row. This makes the rail fully operable without a mouse.

Deep Linking¶

Selecting a run writes its execution id to the ?execution=<id> query parameter, alongside the #runs hash the tab itself uses, so a particular run's URL looks like .../squad/<squad-id>?execution=<execution-id>#runs. The write replaces the current history entry rather than pushing a new one, so paging through several runs does not fill the browser's back stack. Loading a URL with the query parameter preselects that run; an id that no longer matches any execution shows the "run not found" state on the right instead of an error.

Run Detail¶

The right side renders one run's detail in seven sections, top to bottom:

1. Header: the plan title (or request), the execution id with a copy button, a status badge, and three tiles: total tokens, duration, and a completed / total task count.
2. Execution trace: one row per task, plus a planner row when the run recorded a planner model, laid out on a time axis and colored by model. Tasks that ran in the same wave overlap on the axis; a later wave starts only after the earlier wave's tasks finish. Counters above the trace report model calls, ledger events, task count, and wall-clock duration, and a model legend maps colors to model ids. A "Trace as a table" toggle offers the same rows as an accessible table for readers who cannot use the bar chart. A run recorded before task timestamps existed falls back to laying bars end to end by duration, with a note explaining that the positions show order rather than real timing.
3. Replay: a scrubber over the run's persisted event ledger, with play/pause, 1x/2x/4x speed, and restart controls. Moving the scrubber dims trace events after the cursor and updates a selected-event inspector showing the event's decision text, actor, model, task, wave, tokens, duration, native event name, and timestamp. A run that finished before the event ledger existed shows an explanatory empty state here instead of a scrubber with nothing to scrub.
4. Tasks: one card per task, showing title, status badge, task id, agent, time window, duration, tokens, model, and a collapsible output or error.
5. Source records: the raw evidence behind the run, each behind its own disclosure. This includes the generated Markdown report (use Generate Report if one has not been produced yet), the per-task records as pretty-printed JSON, the workspace files the run wrote (click a row to open it in the Workspace tab), and a JSONL download of the event ledger. The ledger download is disabled for a run with no ledger.
6. Execution log: the run's log, filterable by agent and severity.
7. Execution prompt and Execution output: the original request and the final result, shown verbatim with a copy button each.

Analytics Tab¶

The Analytics tab holds the Analytics Dashboard, aggregating trends across every execution. Per-run detail lives in the Runs tab instead.

Analytics Dashboard¶

The Analytics Dashboard aggregates data across multiple executions to reveal performance trends.

Available Metrics¶

• Total executions — Count of completed, failed, and cancelled executions
• Success rate — Percentage of executions that completed successfully
• Average duration — Mean execution time in milliseconds
• Total tokens — Cumulative token consumption

Token Usage by Agent¶

A breakdown showing how tokens are distributed across agents. Identify which agents consume the most resources and whether the distribution matches expectations.

Daily Usage¶

A bar chart showing execution count and token usage per day, useful for spotting usage trends over time.

Period Selection¶

Filter analytics by time period:

• Day — Last 24 hours
• Week — Last 7 days
• Month — Last 30 days
• All — All recorded history