ID Agents Dashboard (Mac App)#

The ID Agents Dashboard is the proprietary macOS desktop application for operating and observing an ID Agents fleet. It gives you a graphical view of your projects, agents, news, tasks, schedules, and library, plus a command palette and a file browser.

Download it from /download. See Quick Start for install steps.

Where this fits. The Dashboard does not run agents itself. It is a graphical client layered on the open-source id-agents core: the manager daemon spawns and tracks agents, and the Dashboard reads that state and drives it. Everything here operates the same teams you would manage from the CLI. The app owns the manager process it starts, so you do not need to launch the daemon separately.

Window Layout#

The window has four persistent regions.

Most views are a sortable table over a detail pane, split by a draggable divider you can also move with ↑ and ↓ when it has focus.

Sidebar Views#

The sidebar has two headed groups. Views holds Projects, Agents, News, Tasks, Calendar, and Heartbeats. Library holds Agents, Skills, and Teams. Projects, Agents, Tasks, and Heartbeats carry a live count badge.

There is no sidebar item for Settings. See Settings for how to reach it.

Projects#

Projects registers local folders and captures their change history. It is the one view that is not team-scoped, so the team selector and agent filter are hidden while it is open.

The list columns are Name, Folder, Capture, and Last snapshot. Folder shows the path with ~ substituted for your home directory. Last snapshot is a relative time that refreshes every 10 seconds. The list is fixed alphabetical by name; there are no sort controls, filters, or search box in this view.

The Capture cell shows a status dot and one of these labels:

A ⚠ icon appears when shadow history nears or hits the limit. The warning threshold is 1.0 GiB and capture pauses automatically at 2.0 GiB.

Above the list is a single Add Project button. The add dialog is titled Add project and states its rule plainly: Pick a folder using the native chooser — the app never accepts a typed-in path. You click Choose folder…, which opens a native picker, then name the project (1 to 80 characters) and click Create project.

The inspector below the list has sections Identity (with a Copy path button), Capture status, Storage (only when the size is known), and Capture policy. The capture policy is fixed and not overridable:

• Excludes .git/, node_modules/, and common build/noise folders — not overridable.
• Secret-looking files (.env*, *.pem, *.key, SSH private keys, …) are never captured — not overridable, no per-project exception.
• Files larger than 10 MiB are omitted from capture; the working file itself is left untouched.
• Also honors the project's own .gitignore.

Below the inspector is the timeline, a newest-first snapshot list with columns Ref, When, Change, and Files. Change badges are Baseline, Catch-up, and File changes. Clicking an entry drills into a detail view with a ‹ Back button, a changed-files list using status glyphs A, M, D, R, and B for Added, Modified, Deleted, Renamed, and Binary, and a diff pane. Escape also goes back. New snapshots are prepended live without disturbing your selection or scroll position.

Agents#

Agents is the view the app opens on. It is a table of every agent over an activity panel for the selected agent.

Table columns, in order, are a health dot with a blank header, then Agent, Team, Runtime, Model, Eff, Status, News, HB, Mem, and Uptime. Eff abbreviates the effort setting to low, med, high, or xhi. HB is the heartbeat interval in seconds, Mem is memory in MB, and Uptime is a duration. Any of these render — when unset.

Click a column header to sort. Clicking the same header toggles ascending and descending; a new header sorts ascending. Sortable columns are Agent, Team, Runtime, Model, Status, News, and Uptime. The default is Agent ascending.

The News column pairs an age label with a colored dot: green under 300 seconds, yellow under 1200 seconds, gray beyond that, and never when the agent has no news.

Eight of the eleven columns can be hidden from Settings. Columns also hide automatically when the window gets narrow, independently of your choice:

When the table has no rows in the current scope it shows No agents in this scope. While data is loading, a banner above the table reads Loading agents….

The activity panel below the table has three tabs: News, Output, and Tasks. With nothing selected it reads Select an agent to see its activity.

• News reuses the News table columns scoped to one agent, with a ‹ Back drill-down. Empty state: No recent news.
• Output lists the files directly inside the agent's output/ directory, with File and Size columns, a Refresh button, and per-file Copy and Reveal buttons. Empty state: No output files for this agent.
• Tasks lists tasks owned by the selected agent with a status dot and the raw status word. Empty state: No tasks for this agent.

A profile panel opens as a right drawer for the selected agent, on by default and toggleable in Settings. It is headed Profile with a ✎ edit button, and holds the agent's photo, name, team, an optional Project section with a View Project button, a Bio section, and a Handles section. In edit mode you get Change photo, Save profile, and Cancel. The photo also accepts a drag-and-drop of a png, jpeg, or webp while editing.

News#

News is a read-only, system-wide activity log, newest first, capped at 300 items. It has no compose or send controls.

Columns are a heat swatch with a blank header, then From, To, Message, and Age. The heat swatch buckets by age: fresh under 60 seconds, recent under 300 seconds, stale under 1200 seconds, and old beyond that. From and To are derived per item, so an outbound item shows the agent as the sender and the counterparty as the recipient, and an inbound item is reversed. Status rows with no counterparty leave To blank.

Only From, To, and Age are sortable. The default is Age ascending, which reproduces newest-first order.

The detail pane below shows the item type and age, a Copy button that flips to Copied, a directional party chip, and the preview text. Any payload renders through a shared viewer with a Reader and JSON toggle; JSON mode adds Expand all, Collapse all, and Copy all. Empty states are No activity yet in the table and Select a news item in the detail pane.

Tasks#

Tasks lists the manager's tasks across teams. It is read-only: there are no create or edit controls in this view.

Columns are a status dot with a blank header, then Task, Owner, Team, Status, Due, and Updated. Team hides below 900 px, Due below 820 px, and Updated below 760 px.

Status is the raw manager status rendered as a plain word, with a matching dot:

Above the table is a status filter with options All, Doing, To do, and Done. Tasks are additionally narrowed by the toolbar team scope. Sortable columns are Task, Status, Owner, Team, and Updated; Due is not sortable. The default order is lifecycle rank (doing, then todo, then done), then most recently updated, then title.

A task's Due value comes from its first linked calendar event. Tasks with no linked schedule show —.

The inspector has a Task section with the fields Title, Name, ID, Status, Owner, Team, Due, Created, Updated, and Completed, plus an optional Description section and a Linked events (N) section. Empty states are No tasks and Select a task to see its detail.

This is the same lifecycle the rest of the platform uses. The statuses here are the todo / doing / done transitions produced by /task create, /task claim, and /task done. See CLI Reference and First Team.

Calendar#

Calendar shows non-heartbeat schedules only. Heartbeat-kind schedules go to the Heartbeats view instead. It is a flat sortable table, not a month or week grid, and it has no create or edit dialog.

Columns are a status dot with a blank header, then Schedule, Date/Time, Message, Next, and Team. Message hides below 700 px and Team below 900 px. The dot is green when the schedule is enabled and has a next fire, and dim otherwise.

The Next column is a live countdown refreshed every 10 seconds, showing —, now, or in {n}s / in {n}m / in {n}h / in {n}d. Sortable keys are Schedule, Next, and Team, defaulting to Next ascending so the soonest fire is first.

When heartbeat schedules exist, a pointer line appears below the list, for example 3 heartbeat schedules — see the Heartbeats section.

The detail pane has a Schedule section with Title, Kind, Enabled, Date/Time, Next fire, Targets, and Team, plus a Message section when the schedule has one. Empty states are No calendar schedules and Select a schedule to see its detail.

Heartbeats#

Heartbeats shows one row per heartbeat schedule and target agent pair. It has no create or edit dialogs.

Columns are a status dot with a blank header, then Agent, Cadence, HEARTBEAT.md, and Team. HEARTBEAT.md hides below 700 px and Team below 900 px. The dot is green when the schedule is active and dim otherwise.

The HEARTBEAT.md column shows a single-line preview of the agent's HEARTBEAT.md, read from <workingDirectory>/HEARTBEAT.md, with … while it loads. The detail pane repeats Agent, Schedule, Cadence, and Enabled, then renders the full file in a monospace block. When the file cannot be shown you see one of (loading…), (empty), (binary file), (unavailable: {reason}), or (HEARTBEAT.md path unavailable).

Rows are narrowed by the toolbar team scope. Sortable keys are Agent, Cadence, and Team, defaulting to Agent ascending. Empty states are No heartbeat schedules and Select a heartbeat to see its detail.

Library#

The Library group has three sub-sections, Agents, Skills, and Teams, which all render the same browser scoped to that kind.

The Library is read-only. It is an inventory of the manager's agents, skills, and teams. There is no install, deploy, or other mutating action anywhere in it.

Columns are Name and Description, with Description hiding below 720 px and showing — when null. Both columns sort, defaulting to name ascending. There is no search box.

Selecting a row fetches its detail. The detail header is titled Agent, Skill, or Team and carries Reveal (opens the entry's source folder, disabled without a source path) and Copy (flips to Copied). The body is a read-only rendering of the content: for skills, the on-disk SKILL.md; for agents and teams, the manager-provided README or team YAML. Placeholders are (loading…), SKILL.md unavailable for skills, and (empty) for agents and teams.

Empty states are No agents in the library, No skills in the library, and No teams in the library.

Title Strip and Status Indicator#

The title strip is the drag region at the top of the window. It holds only three things: the title ID Agents, the Files toggle, and the manager status indicator at the right end. There is no version or URL in the strip.

Status states#

The indicator is a colored dot with a lowercase text label. Every state it can show:

Health probes run every 5 seconds with a 750 ms timeout per probe. Only live, starting, and restarting pulse, and only when the Blink live indicator setting is on.

When the monitor declares the manager down, a native dialog offers Restart and Not now. It appears at most once per outage.

The Files toggle#

A Files button sits in the title strip to the left of the status dot, with a folder glyph and the tooltip Files (⌘⇧E). It renders as pressed while the browser is open. Clicking it, or pressing ⌘⇧E, toggles the file browser drawer.

File Browser#

The file browser is a right-docked drawer headed Files with a × close button. It is shell-level, so it appears beside any view and is independent of which agent is selected. Nothing auto-closes it. Both its open state and its current directory persist across relaunch. When the profile panel is also open, the profile panel docks to the left of the Files drawer.

What it can browse: your home directory and everything under it. The browse root is set once at startup to your home folder. It is not per-agent and does not follow the selected agent. Going up with ← is capped at the home root, so you cannot browse above ~.

Directories sort first, then files, each by name. Directories show a 📁 icon and a trailing /; files show 📄. Symlinks, sockets, and FIFOs are omitted from listings.

There is no in-app file viewer in this panel. Opening a file hands the path to the OS default application. The browser itself only ever displays the current directory path and the list of entry names, so no size or file-type limit applies to it.

Launch behaviour with protected folders#

macOS gates the contents of Desktop, Documents, and Downloads behind a per-app consent prompt. Listing ~ itself is free, because that only names those folders.

The browser reopens on the directory you last left it in. At launch it falls back to the home root instead of the saved directory when the saved value:

• is missing or empty;
• is the home root itself;
• lies outside the home subtree;
• contains a .. segment;
• has a first segment below home equal to Desktop, Documents, or Downloads.

The match is on the whole segment, so both ~/Documents and ~/Documents/a/b fall back, while a sibling like ~/DocumentsFoo is restored normally.

The effect is that no consent prompt fires at launch. Those folders stay fully reachable, and macOS prompts only when you navigate into one yourself.

Exactly one directory, the current one, is ever read, and only when it becomes current. When a listing fails the list body shows the reason in parentheses, such as (not found); an empty directory shows (empty). If the home directory never resolves, the panel renders File browser unavailable.

Context Menus#

Right-clicking also selects the row you clicked. All context menus open at the cursor, clamp inside the window edges, and close on Escape, a click outside, window blur, or as soon as an action fires. ↑ and ↓ move the highlight and wrap, Enter activates, and Esc closes.

Right-click opens a menu in four places: the Agents table, the Files browser, a project's changed-files list, and the Projects table.

Agent context menu#

Delete renders in red under a separator. Only Start and Stop are ever disabled, and disabled items are skipped by both the arrow keys and clicks.

The confirmation is inline, not a dialog. The first click rewrites the item's own label to Confirm Stop? or Confirm Delete?, and a second click on that item fires the action. There is no typed-retype step and no separate dialog in this menu.

These are real mutations, unlike the read-only command palette. The result appears as a transient toast that auto-dismisses after about 3 seconds, reading <action> → <agent name> on success and <action> failed: <message> on failure.

File context menu#

Used by both the Files browser and a project's changed-files list.

No item is ever hidden or disabled, and none of them confirm; every one fires immediately. In a project's changed-files list, for a file whose status is deleted, Open and Show in Finder silently do nothing because the file is gone from disk, while Copy path still works.

Project context menu#

Remove renders in red under a separator, and its label becomes Removing… while the removal is in flight. Its confirmation is a native macOS message box, not an in-app dialog:

• Message: Remove "<project name>" from Projects?
• Detail: The project folder and its files are NOT touched. Its snapshot history is moved to the Trash.
• Buttons: Remove and Cancel, with Cancel as both the default and the cancel button

If you cancel, a banner reads Removal cancelled — nothing was changed.

Toolbar#

The toolbar row sits below the title strip and holds three controls.

Team scope selector. A segmented control labeled Team scope, with All teams first and then one segment per team, each labeled with the team's own name. ← and → move between segments, wrapping. The scope is passed to the Agents, News, Tasks, and Heartbeats views, and it also determines which team the command palette dispatches against.

Agent filter. A search field with the placeholder Filter agents. It matches the agent's name only, as a case-insensitive substring. It does not match team, runtime, model, status, or any other column.

Command palette button. A button labeled ⌘K that opens the palette.

The team scope selector and the agent filter are both hidden on the Projects section, because Projects is not team-scoped. The command palette button stays visible in every section.

Sorting is not a toolbar control. You sort by clicking the table column headers.

Command Palette#

Open the palette with ⌘K, the toolbar ⌘K button, or ? to land straight on the help sheet. Close it with Esc or by clicking the backdrop. Every open resets the buffer, results, and history cursor.

The input placeholder is Type a command — e.g. /status, /teams, /meta <agent>.

History holds the last 50 submitted lines and de-dupes an immediate repeat.

The read-only rule#

The palette can run five commands. Only /status, /teams, /meta, /list, and the bare list form of /agents actually execute. Every other command is still parsed, classified, and gated for parity with the terminal TUI, but it is never dispatched. Once you accept the gate it resolves to the message Read-only in the desktop app — run this from the terminal TUI or the dedicated view. The main process re-checks the same allowlist, so the guard is not renderer-only.

Even inside the allowlist, a mutating form is refused: /agents <team> stop trips a gate and is therefore not treated as a read.

Commands#

The catalog is shared with the TUI, so the palette lists all 17 commands regardless of which ones it can run.

Confirmation gates#

Powerful and destructive commands are gated before they resolve, even though most of them cannot run here.

• Y/N gate. A dialog reading Confirm: followed by a preview of what the command would do, with Cancel and Confirm buttons. Confirm is autofocused.
• Retype gate. A dialog reading Destructive. then Retype <command line> to confirm. The Confirm button stays disabled until the text you type matches the normalized command line exactly. Enter confirms on a match, Esc cancels.

The main input is disabled while a gate is showing. Accepting either gate only advances the flow; the read-only executor still refuses anything off the allowlist.

Suggested commands and help#

With no result showing, the palette body lists contextual actions: Team status, List teams, Pending queries, Metadata: <agent> when an agent is selected, and Settings, which navigates to the Settings page and closes the palette.

A button inside the palette flips between ? Help and Hide help. The help sheet lists every catalogued command grouped under Safe, Powerful, and Destructive. Each row marks whether the palette can execute it, showing run or view/TUI, followed by · Y/N or · retype when the command has a gate. The sheet is generated from the same shared catalog, so it cannot drift from the palette or the TUI.

While a command runs the body shows Running…. An unrecognised command shows Unknown command: <name>, and with no live manager you get Commands need a live manager connection.

Keyboard Shortcuts#

Global#

The standard Edit, View, and Window menu roles are kept, so the OS defaults for copy, paste, zoom, and minimize still work.

Tables and lists#

Sidebar, segmented controls, and split dividers#

Dialogs and drill-downs#

The JSON payload viewer uses Enter or Space to toggle a node, → to expand, and ← to collapse. Context menu and command palette keys are listed in their own sections above.

Settings#

There is no sidebar item for Settings. There are two ways in:

1. The app menu item Settings…, with the accelerator ⌘,.
2. The command palette, where a suggested action labeled Settings with the hint Open settings navigates there.

A ‹ Back button returns you to the dashboard.

Settings has no Save or Reset buttons. Every control persists immediately, and no setting requires a restart.

Theme is a segmented control with Auto, Light, and Dark. The default is Auto, which follows the OS appearance.

Font size is a segmented control with Default, Large, and Larger, scaling the whole app by 1, 1.15, and 1.3 respectively.

Blink live indicator controls whether the title-strip status dot pulses. It is on by default.

Show agent profile panel controls the right drawer in the Agents view. It is on by default.

Agent columns carries the hint Choose which optional columns appear in the Agents table. A checked box means the column is visible. The optional columns are Team, Runtime, Model, Eff, Status, HB, Mem, and Uptime. By default none are hidden. The health dot, Agent, and News columns are identity columns and can never be hidden.

Restart Manager appears only when the manager is locally managed, and its label becomes Restarting… while in flight. The main process owns a confirmation dialog reading Restart the manager? This restarts all agents. with Restart and Cancel buttons. When you are monitoring a remote manager the button is replaced with the hint Monitoring a remote manager — local restart is unavailable.

Trial gate. The app ships with a 90-day trial. When the gate requires sign-in, has expired, needs a recheck, or errors, a full-screen overlay covers the entire dashboard. Offline grace does not lock the app; it surfaces in the Trial section of Settings instead.

Connect#

Connect is a button pinned to the bottom of the sidebar. It opens a modal that gives you a prompt to paste into a coding agent so that agent can drive your fleet as manager.

The modal opens two ways: by clicking the button, or automatically exactly once on a fresh first launch. After that first auto-open it never pops up on its own again.

The modal is titled Connect a coding agent and explains itself verbatim:

ID Agents lets you run teams of agents as background processes, controlled from standard coding agents like Claude Code, Codex, or Cursor. Use this prompt to connect your coding agent as the manager of all the teams.

Below the lede is the generated prompt and a Copy prompt button that flips to Copied. There are no input fields; the modal is display-and-copy only. Focus moves to the copy button on open, Esc closes, Tab is trapped, and clicking the backdrop closes.

The generated prompt embeds your real manager URL and paths, and it tells the coding agent three things:

1. The desktop app already owns the manager, so do not start, restart, or spawn a second one.
2. Install the admin-control skill from the given path, however that agent loads skills. The prompt is deliberately agent-agnostic and does not hardcode a Claude Code specific install command.
3. Check /agents first. If it lists agents, this is a reconnect, so work with them rather than deploying. Only deploy the default team when there are zero agents.

It closes by pointing at the quickstart doc and the read-only dependency root and writable config root.

Auto-update#

Updates are silent until they are ready to install.

The app checks for updates on startup and then every 4 hours, downloading in the background. Checking, downloading, and update errors are all deliberately invisible; there is no progress bar and no error message.

Updates run only when every one of these holds: the build is packaged, the platform is macOS, the app is not Gatekeeper-translocated, and the app is running from /Applications/. Otherwise the updater stays inert and never touches the network. There is no user-facing setting to enable or disable auto-update.

When a new version has fully downloaded, a toast appears:

• Title: Version <version> is ready
• Primary button: Restart & Update, which shows Restarting… while it works
• Dismiss button: ×

Clicking Restart & Update tears down the manager the app spawned, so port 4100 is freed for the new version, then quits, installs, and relaunches. Dismissing the toast remembers that version for the session so it does not reappear, but a newer version will toast again. Quitting normally with an update already downloaded also installs it.

Related#

• Quick Start -- install the Dashboard or the core
• First Team -- how to structure a team
• CLI Reference -- the commands the palette defers to
• TUI Dashboard -- the terminal monitor for the open-source core
• Configuration -- YAML config, org chart, and scheduling