# Recipe: Herdr Task Lists Build a compact task checklist for the user's existing Herdr desktop layout. Read their installed app-home `AGENTS.md`, `herdr.d.ts`, and `gpui-kit.d.ts` first; use APIs matching their app version. Clone shipped layout/tab-bar code before editing. Preserve unrelated settings, keys, mods, panels, and state. ## Package and integration Three native GPUI mods are supplied: - `workspace-tasks`: the checklist and persistence/migration logic. - `workspace-task-lists`: list selection and named-list creation. - `workspace-task-delete`: confirmation and targeted tab closure. Read every file before installing. Explain that mods run programs through Herdr's `exec` API. They do not fetch URLs. Copy only the mod folders; never import another user's state. The mods use `place: none` and require layout integration. If a name conflicts, rename the new mod and all references to it; never silently overwrite. Add the main panel to an existing right-hand Files/Changes stack when appropriate. The supplied collapse button calls `layout.hide { id: "panel" }`. Adapt that target if the user's container ID differs. For the common layout, add a `tasks` block child with `content: { mod: "workspace-tasks" }` in the `panel-body` stack. To show it: ```js run("layout.select", { stack: "panel-body", child: "tasks" }); run("layout.show", { id: "panel" }); // Second click while already shown: run("layout.hide", { id: "panel" }); ``` Add the toggle to a personal tab-bar mod. Ensure any existing per-space panel restore logic accepts `tasks` as an enabled panel; otherwise it can undo the selection. Preserve other panel preferences and unrelated tab-bar behavior. The label is the selected list name and open count: ```js const store = shared("workspace-tasks.v2"); const list = store?.lists?.[store?.bindings?.[activeSpace?.id]]; const count = list?.tasks.filter(task => !task.concludedAt).length ?? 0; const label = list ? `${list.name} · ${count}` : "Tasks · 0"; ``` The panel heading is also ` · ▾`; clicking it opens the list picker. A tab-bar toggle is optional if a key or another control shows the panel. No replacement layout or personal tab-bar file is distributed. ## Tasks and tabs Use native inputs, theme colors, compact spacing, and no redraw timer for static metadata. Enter or plus adds a task; clicking its title edits it. Card layout: title/checkbox/delete row; combined Created/Start/Done timestamps; combined durations when completed; compact agent controls. Full date/time details are available on hover. List existing tabs on the left, one agent icon plus arrow per tab. Clicking returns to that exact tab and space. On the right, keep Claude-plus and Codex-plus buttons for additional tabs, hidden for concluded tasks. Discover installed commands/icons with `knownAgents({on: space.machine})`; do not guess shell commands. Disabled agents have explanatory tooltips. New tabs target the current space/machine and normal working folder, even for a list created elsewhere. Open the agent interactively without submitting any prompt. Omit the `task` argument from `tab.new`; use the task text only for the tab name. Do not append it to the agent argv or send it to the terminal. Name the first tab after the task, then append `(2)`, `(3)`, etc. Number across all agents for a task and retain the counter after tab closure. Use explicit structured arguments without shell interpolation. Capture list, space, and folder before awaiting launch; changing list or focus must not move the result. Prevent repeated clicks while a launch is pending. Record creation and conclusion dates as ISO timestamps. First-agent time is the earliest successful new-tab launch and never resets on subsequent launches. Do not invent missing historical timestamps. User completion is independent of agent status. Show creation-to-conclusion elapsed time and first-launch-to-conclusion elapsed time, including pauses/waiting. Reopening clears conclusion while retaining creation/first-launch time. ## Lists and persistence Use Herdr shared state root `workspace-tasks.v2`: - `lists`: ID to `{ name, machine, folder, tasks, folds }`. - `bindings`: space ID to selected list ID. - `defaults`: space ID to its default list ID. - `migrated`: legacy space IDs already migrated. Default IDs encode `[machine-or-local, folder]` with JSON. On initial association, prefer the first terminal pane's current folder, falling back to the space folder/home marker. Trim trailing separators, preserving roots/case/remote semantics. Bind once rather than following every directory change. A new space with the same identity finds its saved default. All lists remain selectable without any bound space. Named custom lists have independent IDs and can be selected in several spaces. Each task stores ID, text, timestamps, agent-key-to-tab-ID arrays, and launch counter. Resolve open links across every space, not just the currently selected one. Shared lists are local to the app home, not externally synchronized. Migrate old `workspace-tasks.v1` lists once, merging distinct task IDs if machine/folder defaults coincide. Preserve all task fields and legacy folds. Keep lists belonging to closed spaces as recovered lists. Retain legacy storage as a fallback, but migration markers prevent deleted tasks reappearing. Group concluded tasks by local conclusion month/year, then weekday/day, newest first. Show counts and allow each level to fold. Save fold choices on the list, so spaces sharing it share fold state. ## Delete confirmation Clicking delete opens a modal listing the task and related open tab names. Cancel/Escape changes nothing. Confirm closes every linked tab across spaces using explicit tab IDs with `confirmed: true`, then deletes the task from its list. Explain that this ends agents and other terminals in those tabs. Never close an unrelated or implicitly focused tab. Skip already-closed links; if closure fails, retain the task and show that some tabs may already have closed. Do not offer an Undo implying session restoration. Block deletion while a task launch is pending. ## Validation and sharing Run native checks for all mods and any modified tab bar. Inspect `herdr-app status`, take `herdr-app shot`, and visually verify cards, picker, date hierarchy, and confirmation. Use mocks or isolated fixtures for destructive checks; do not end real agents just to test. Distribute code, recipe, documentation, and a safe preview only. Exclude runtime JSON, profiles, settings, task data, generated API files, backups, and live-workspace screenshots. This package's preview is a synthetic illustration using fictional tasks. Public repos with topic `herdr-mod` are discoverable through Herdr's community catalog.