[Linux] Sidebar — project/worktree/agent tree view

[2witstudios]

Overview

Implement the sidebar tree view matching the macOS app's SidebarViewController.swift.

Structure

The sidebar has two sections:

Navigation Tabs (top)

5 tabs matching macOS: Dashboard, Swarms, Prompts, Schedules, Agent Config. Use gtk::StackSwitcher or custom button row.

Tree View (main area)

Hierarchical list showing:

• Project (header row) — project name, "+" button for spawning
• Worktree (expandable) — name, branch badge, status dot, agent count
• Agent (leaf) — name, type icon, status dot (colored), prompt preview
• Agent Group (expandable) — multiple agents sharing a tmux window
• Terminal (leaf) — dashboard-created terminal sessions

Use gtk::ListBox with custom row widgets, or gtk::TreeView / gtk::ColumnView for the hierarchy.

Recommended: gtk::ListBox with indent levels

GTK4's ListView with TreeListModel is the modern approach:

let tree_model = gtk::TreeListModel::new(root_model, false, true, |item| {
    // Return child model for expandable items
});
let selection = gtk::SingleSelection::new(Some(tree_model));
let list_view = gtk::ListView::new(Some(selection), Some(factory));

Status Indicators

Match macOS colors from PPG CLI/PPG CLI/Theme.swift:

• Running: green (#34D399)
• Completed: blue (#60A5FA)
• Failed: red (#F87171)
• Killed: orange (#FBBF24)
• Spawning: yellow (#FDE68A)
• Lost: gray (#9CA3AF)
• Waiting: purple (#A78BFA)

Context Menus

Right-click on:

• Worktree → New Agent, New Terminal, Delete
• Agent → Rename, Kill, Restart, Delete
• Agent Group → Rename, Delete All
• Project → Close Project

Incremental Updates

When manifest refreshes (via WS event or pull-to-refresh), diff against current tree and update in place — don't rebuild the entire tree. Match the applyTreeDiff pattern from the macOS sidebar.

References

• macOS: PPG CLI/PPG CLI/SidebarViewController.swift (1418 lines)
• iOS: ios/PPGMobile/PPGMobile/Views/Sidebar/SidebarView.swift

Acceptance Criteria

• Tree shows projects > worktrees > agents hierarchy
• Status dots with correct colors for all agent/worktree states
• Selection navigates content area
• Context menus with kill/restart/delete actions
• Tab navigation between Dashboard/Swarms/Prompts/Schedules/AgentConfig
• "+" button triggers command palette
• Incremental tree update on manifest change

[Snailflyer]

For the project > worktree > agent tree, I would make status dots represent a verified live target, not just the last manifest value.

A useful row model could include: project id, worktree path, branch, agent id, tmux window/pane or terminal id, process generation, manifest version, last heartbeat, last output cursor, and last_action_consumed_at.

Then incremental updates can show the difference between:

• manifest says an agent exists
• terminal/session is still alive
• agent is running in the expected worktree
• a kill/restart/delete action was actually consumed
• row is stale and needs refresh

Faryo is a smaller project/mobile workbench for tmux-backed AI coding sessions, and its proof shape is similar: control surface visibility is not enough unless the same live tmux session consumes the action. Public proof shape: https://github.com/Snailflyer/faryo/releases/download/v1.0.7/faryo-public-redacted-same-session-handoff-walkthrough-20260528-0120.gif