Monitoring & Analytics¶

Squad provides real-time monitoring, detailed execution history, and analytics to help you understand how your squads 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, time, and task 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 history of the current conversation

Task Board¶

The Tasks 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 active and saved executions, and the right side shows the evidence available for the selected run. Select View run in Chat to open the active execution directly without clearing the mounted Chat state.

Run Library Rail¶

Active executions appear first with their actual Planning, Awaiting approval, Running, Paused, Interrupted, or Aggregating status. Saved executions follow, newest first, with a status icon, plan title (or original request), timestamp, and saved verdict mark. A run appears only once while it moves from live state to saved history. Type in the search box to filter by request text, plan title, or status. A Load more button pages through older saved runs. Live polling pauses while the tab is hidden.

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¶

For a live run, the detail updates genuine execution facts: trace timing, resolved models and providers, waves, reported token usage, tasks, and the growing event-ledger replay. Missing model, usage, or timing stays Unknown. A pending task with no start time has no invented timeline bar. Replay polling continues from the last event sequence, preserves the cursor as the ledger grows, and offers Jump to latest. If a refresh fails, the last trustworthy evidence remains visible with Retry.

Open Live execution progress to inspect the same wave and task tracker used in Chat. This copy is read-only, so pause, resume, retry, skip, and steer actions remain in Chat. An execution waiting for plan approval shows Review plan in Chat instead. The action restores that exact execution and its live conversation, including a draft already entered in Chat, so the approval panel is ready when the tab opens.

When the execution ends, its last live snapshot stays visible until the saved history record is available. The view then switches in place, preserves the selected id and replay cursor, and announces the transition. Verdict, export, audit, source records, and execution logs are available only from the saved record.

The saved detail renders ten 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. Usage and routing: recorded task tokens by agent, planner tokens as a separate total, and observed task-completion and planner activity by model or agent. Missing and truncated evidence is identified instead of being counted as zero.
3. Audit: submission-time budget limits and terminal tracker usage, the recorded failure, and the files that are currently available as evidence. Details of this section are below.
4. 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. Recorded timestamps show actual overlap and ordering. Counters report model-resolved tasks, ledger events, task count, and wall-clock duration. A "Trace as a table" toggle offers the same rows as an accessible table. For a run saved before task timestamps existed, duration-only bars share the origin, the table labels each start as Not recorded, and the trace does not invent wave chronology.
5. Replay: a scrubber over the event ledger, with play/pause, 1x/2x/4x speed, restart, and Jump to latest controls. Moving the scrubber dims trace events after the cursor and updates the selected-event inspector. A run that finished before the event ledger existed shows an explanatory empty state.
6. Tasks: one card per task, showing title, status badge, task id, agent, time window, duration, tokens, model, provider, and a collapsible output or error.
7. Source records: the raw evidence behind the run. If replay reached a persistent or display cap, the JSONL action is explicitly labelled as a partial download; use Export run for the complete saved bundle.
8. Execution log: the run's log, filterable by agent and severity.
9. Execution prompt and Execution output: the original request and the final result, shown verbatim with a copy button each.
10. Verdict: choose Good, Partial, or Bad, add an optional note, then select Save. The verdict is not inferred from run status and does not change until Save succeeds. Clear removes the saved verdict, note, and timestamp. A failed save keeps the draft and offers Retry; switching between runs keeps each run's draft separate.

Audit evidence¶

Budget at submission compares terminal usage with the limits captured when the run was submitted. Budget tokens include planner usage. Active execution time excludes planning, approval waits, operator pauses, and budget pauses. Task usage is the number of tasks created in the accepted plan. A percentage may exceed 100, while the visual meter stops at its full width. Limits changed later can affect the running execution but do not rewrite this historical snapshot. Older records show Limit not recorded or Usage not recorded instead of using the squad's current configuration.

Configured concurrency and idle timeout appear for reference with Not enforced. AI:GO records these settings but does not enforce them, so the Audit section does not present them as compliance measurements.

Recorded failure shows the typed failure kind, owner, and available message for failed, cancelled, or partially completed runs. A legacy terminal run with no typed classification says that failure details were not recorded. It is not presented as a successful run.

Evidence availability now checks the application-owned logs/history.json, logs/<execution-id>.events.jsonl, logs/<execution-id>.jsonl, and artifacts/reports/<execution-id>-report.md files when the detail is opened. Available, Missing, and Unknown describe the current inspection, not what existed when the run finished. An unsafe file or a file that cannot be inspected is Unknown rather than Missing.

Export a run¶

Select Export run in the detail header to save a JSON bundle containing the execution record, the complete saved event ledger, log entries, and an existing Markdown report. The export reads the saved files rather than the replay panel's event page. eventsRecorded and logRecorded distinguish missing artifacts from empty files, and eventsTruncated preserves the ledger's truncation marker. Missing reports are null. Credential fields and recognizable secrets are redacted before download.

In the desktop app, canceling the save dialog cancels the download. A failed export or write shows an error beside the button, and you can retry.

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