# Herdsidian Herdsidian puts an Obsidian vault inside Herdr, in its own layout: the Graphite Glass look. Sidebars and bars are tinted glass over a gradient of the active theme, and panes are solid cards. Every color comes from the theme, so each of the eight themes has its own tint. On the left, the spaces and agents lists show the shortcut to each row. On the right, a Notes sidebar browses, renders and edits the Markdown notes of an Obsidian vault. ![Herdsidian](preview.png) ## What you see Left to right: Root row: `titlebar: "none"`, macOS `traffic_lights` at [16, 19], `terminal_padding` [10, 6]. 1. **Sidebar**, 248 px (min 44, max 480, not resizable): a 52 px `brand` block (`herdsidian-chrome`, `window_drag`), `guide-spaces` and `guide-agents` stacked with equal weight (min 90 each), and an 80 px `sidebar-footer` block (`herdsidian-chrome` with `props: { footer: true }`). `herdsidian-chrome` is a clone of Herdr's `workspace-chrome`. The header shows the app icon (18 px, `image()`, gap 7, then the name "Herdsidian" in 13 px medium `muted`), and the hide-sidebar button (28 px), right-aligned over a neutral top sheen and the dot texture (see Header dots). The icon is `herdsidian.svg`: a hexagon of grey glass facets whose lower-right facet is split off by a thin dark crack (`#16181b`), inside the outline. It is always grey (full color, never tinted) and the collapsed rail does not show it. On macOS the header leaves 84 px on the left for the traffic lights. The footer has two 32 px rows, Settings and Add machine. - Header dots: all three 52 px header blocks (sidebar brand, toolbar, Notes header) carry a field of tiny dots, strongest at the top and fading out at the bottom edge. `header-dots.svg` (2400×52, dots of radius 0.7 every 6 px, the fade is an SVG mask) ships in `herdsidian-chrome`, `herdsidian-tabs` and `herdsidian`. It is drawn by `headerDots(k, mod, blockX)` in `lib/ui.js`: `svg(...)` 2400×52, absolute, top 0, `left(-dotOffset(blockX))`, tinted `k.dot`, inside the 52 px block, which clips (`overflow_hidden`). It sits over the glass and the top sheen, under the controls. `dotOffset(blockX)` is `blockX mod 6`: 0 for the brand, the visible sidebar width plus the root divider's width (`divider.width`, 1) for the toolbar (0 when the sidebar is hidden). Notes uses the window width (`globalThis.window.viewport_size().width`, in screen px, so divided by Herdr's `settings().zoom`, 1 when unknown) minus Notes' own layout width, or 0 when either is unknown. Notes does not re-render by itself on a window resize, so its grid can sit up to 5 px off at this seam until the next render (measured; accepted, a seam at Notes is tolerated). At a fractional zoom Herdr rasterizes the SVG with a rounded pitch (6.5 px at zoom 1.1, not 6.6), so both seams jump 2 to 4 px there; a mod cannot correct it. Notes draws it only when expanded, not on the rail. - Spaces header: 24 px high, `Spaces` (11 px semibold `muted`), then the number of spaces (11 px `muted`) and a 22 px `+` button. The hint `⌃ 1–9 · ⌥⌘[ ⌥⌘]` is the tooltip of the `Spaces` title (with key hints on). - Agents header: `Agents` + `⌥⌘ 1–9 · ⌘[ ⌘]`. Each of the first 9 agent rows shows `⌥⌘N` in 11 px `muted` text, under the status pill or the duration. - Spaces row (quiet rows): 32 px (28 px for a worktree), radius 8: avatar, name (flex 1, truncates), signals on the right. Avatar 20 px, radius 6, background the mark color at 20 % (`alpha(mark, 0.2)`), the letter 11 px bold in `markLetter(mark, t)`. Signals: ahead/behind pills (h 18, radius 5, padding 0 6, 11 px): `↑N` in `ansi2` on `ansi2` at 16 %, `↓N` in `ansi1` on `ansi1` at 16 %; a 6 px `blocked` dot when the space is blocked; and on each of the first 9 rows, always, the `⌃N` key cap (h 18, radius 4, 1 px `line` border, 10.5 px `muted`; hidden when `keyHints` is off). The row tooltip is ` · · ↑2 ↓1 · ⌃N` (the branch always, the repo only when unusual, the parts that do not apply left out). The selected row keeps `accentSoft` and medium weight; hover keeps `pill`. Worktree rows are unchanged. - Rows (agents): 7 px of vertical padding, radius 8 and a status line (11.5 px `muted`; for a blocked agent "Needs you" in `blocked`, weight 500). The selected row is an `accent` pill at 18 %. Hover is `foreground` at 6 %. - Agent icon tile: 20 px, radius 6, `foreground` at 6 % (10 % on the focused row), with the 13 px program icon centered (tinted SVGs in `foreground`, pictures as is). No icon: the first letter of the program name (11 px semibold `muted`). The status is an 8 px `statusDot` badge at the tile's bottom-right corner (a 12 px badge at right/bottom -4, so the dot's edge sits at -2) inside a 2 px ring of `chrome`; working pulses, idle is a ring. Blocked is not a dot: it is the 12 px "!" mark (`alertMark`) in a 16 px ring at right/bottom -6. Sub-agent rows and the wide rail (60 px or more) use a 16 px tile with an 11 px icon and no badge (their status shows at the right). - No border between the lists or above the footer. 2. **Work column**: - `herdsidian-tabs` toolbar (52 px, `window_drag`, `canvas` at 35 %): a rounded track holding the tabs as a segmented control (28 px tabs, radius 7, the active one `raised` with a 1 px top highlight), a new-tab button, a spacer, then at the right a 220 px Search box (`⌘K`), one 30 px icon button (radius `RADIUS.control`, id `sidebar-toggle`, the `panel-right` icon) that shows or hides the right sidebar (`layout.toggle` on `herdsidian`), and the window buttons. It is lit (`foreground` at 10 %, `foreground` icon) while the sidebar is shown, else `muted`. There are no Files or Changes icons and no Changes dot: those are tabs of the sidebar. The tooltip is "Right sidebar", with no key (the tab keys are in the sidebar's tab tooltips). There is no Usage control in the toolbar (it moved to the status bar). The Search box opens the palette (item 4). A 14 px program icon leads each tab name (`foreground` on the selected tab, `muted` otherwise for tinted SVGs; pictures as is). The top sheen fills the whole toolbar (180°, `foreground` 5 % at the top to transparent at the bottom edge). The tab track shrinks and scrolls when there are many tabs. - The active tab's panes as solid cards (radius 8, gap 6, padding 4, `lone: true`, background `background`, 1 px hairline border, 1 px `accent` border on focus). No shadow. - Pane header `herdsidian-pane`: 30 px, 10 px side padding, always shown. It has the agent name or terminal title (`foreground`, medium) after a 14 px program icon (`muted`), the folder (`muted`), a 6 px status dot for done only (working shows the bar), the "Needs you" pill for blocked (see "Needs you" below), and split, zoom and close buttons on hover. - Working bar (`workingBar` in `lib/ui.js`): while a pane's status is `working`, a 2 px track along the top edge of the pane header (the card's top), inset by `BAR_INSET` = 4 px on each side (half of `PANE_RADIUS` = 8, which equals the layout's `radius`): 4 px is where the corner's curve meets the bar's 2 rows, and `overflow_hidden` clips to a rectangle, so the bar cannot reach further without poking out of the curve. It is absolute (no layout space), `accentTrack`, at `top(-1)`: the header's 1 px top border pushes `top(0)` one pixel down, so -1 puts the bar right under the card's border. On it, an indicator 35 % of the track length (header width minus 2 x 4), painted as 3 gradient segments (transparent to `accent`, `accent` to `ansi5`, `ansi5` to transparent), looping `left` from minus its width to the track length, period 3200 ms, `ease-in-out` (it goes there and back). The width comes from `on_size_change`. No yellow: it uses the theme's `accent` and ANSI magenta. Done, blocked, idle and plain shells show no bar. A working pane has no status dot: the bar says it. - "Needs you": one signal in every place, the words "Needs you", a "!" mark (`alertMark(t, size, surface)`: a filled `blocked` circle with "!" 8-9 px, weight 800, in the color of the surface under it) and the `blockedSoft` tint. `needsPill(t, k, surface, label = "Needs you")` is the pill: h 18, radius 5, padding 0 7, gap 5, `blockedSoft` background, no border, 11 px weight 500 `blocked` text, an 11 px "!" first. Used by the pane header, the agents list (the full-width pill; the compact one is a 14 px "!" mark), the status bar and the palette's agent row. Blocked reads without color, by the "!" shape. - `herdsidian-status` bar: the blocked agents are a pill, a button: "Needs you", or "Needs you · N" when N is more than 1, with a `⌘J` key cap. A click does what `⌘J` does: it focuses the next blocked agent (`guide-agents.next-blocked`, after the focused one, wrapping). Tooltip "Go to the blocked agent". - There is no second right column. Files and Changes are tabs of the right sidebar (item 3); the layout has no `panel` column. `mods/herdsidian-tabs/sidebar.js` and `lib/sidebar.js` turn `herdsidian-tabs.files`/`.changes`/`.notes` into `layout.show`/`layout.hide` of the `herdsidian` block plus the selected tab. - `herdsidian-status` bar (28 px, `canvas` at 35 %): machine, branch, the agent count or "N working" (and the "Needs you" pill), and on the right the **Usage** control (h 20, radius `RADIUS.control`, 11 px): the provider of the focused pane in full (12 px icon, main percent, a 40×4 bar, window label), a divider, then every other installed provider compact. Hover or click opens a 280 px card above the bar with every provider, the focused one first and tagged "focused pane", and opencode's 7-day cost, Kiro's and Grok's monthly use. From 90 % the percent and the bar use `blocked`. The theme name is not here (it lives in Settings). `⇧⌘P` still opens commands. 3. **Right sidebar** (the `herdsidian` block), 380 px (min 44, max 720), hidden until `⇧⌘O`, `⇧⌘E` or `⇧⌘G`. Same glass as the left sidebar. Header 52 px with a segmented control of three equal tabs, **Notes · Files · Changes**, then the collapse button. Each tab's tooltip carries its key ("Notes ⇧⌘O", none when Key hints is Off). The Changes tab shows a count badge when there are changes. The chosen tab is remembered (stored in `shared("herdsidian.sidebar")` and kept across restarts, default Notes; a stored `settings` reads as Notes). The rail (44 px) shows one icon per tab. The key of the tab already shown hides the sidebar. The palette row "Right sidebar tab" cycles the tabs. - **Files tab**: the file tree and preview, code moved from Herdr's `files` mod into `files-view.js` and `files-tree.js` (a mod cannot host another mod's view). The folder path is a 30 px `muted` line under the tabs. - **Changes tab**: our own list from `git status --porcelain=v1 -z` and `git diff --numstat` for the focused pane's repo: path, +N in `ansi2`, −N in `ansi1`, rows 28 px. A click opens the file in the Files tab. - **Settings** are in ⌘K → Settings, not in the sidebar: **Theme** (four family rows, Carbon, Midnight, Catppuccin and Nord, each showing its dark and light half; a row runs `app.theme` for `hs_` and `hs__light`, so both halves are set; one appearance row opens Herdr Settings → Look, because a mod cannot set light or dark), **General** (Key hints: Always / On hover / Off; "On hover" because a mod cannot see modifier keys while a terminal has the keyboard) and **Layout** (Right sidebar with no key cap, its tab, Sidebar width, Usage in the status bar On / Off). - **Notes tab** (below). - Header (Notes tab) with the dot texture (expanded only): vault folder name (semibold), then 28 px icon buttons: search, new note, choose vault, collapse (`panel-right`). - No vault yet: the title is "Notes", the search button is hidden, and the body reads "Choose a folder of Markdown notes, or create an empty one to start. An Obsidian vault works too; Obsidian is not needed." above a `solid` "Choose a vault" button (`pickFolder`). The graph section is not shown until a vault is chosen. - Search box (when open): 30 px, radius 8, no border, `foreground` at 6 % fill. - Tree rows 28 px, radius 7, 16 px indent per level: chevron + a 16 px folder icon (`accent`, filled body), or a file icon and the note's name without `.md`. The selected note is an `accent` pill at 18 %, with an `accent` file icon. - Note view: back arrow, note name and its path (10.5 px `muted`), a copy button (`copy.svg`, copies `/`, toast "Path copied"); a bar with `Read` / `Edit` pills (22 px, radius 5), `⌘E` cap, a 7 px `working` dot when there are unsaved changes, `Save` and `⌘S` cap. - Rail (width under 160 px): expand, search and new-note icons in a column. - Graph section at the bottom: a header with a hide toggle, a `1 | 2` hops pill, "+N more" when nodes were cut, and a fit button. The body is the local graph of the open note (or the first context note): up to 40 nodes, edges and the center node. Hop-2 labels show on hover or at zoom 1.5 or more. - Agent context block: the focused agent's label, its linked notes (chips with unlink), faded suggestions (one click pins), "Add current note", a picker (`Find a note to link…`, which also holds "Add current note ⌘L") and the **Send to agent** button: `+ Add note` (raised, h 28) on the left, Send on the right (h 28, `solid` background, `solid_foreground` weight 600, a `⌘↵` key cap). Disabled, it is a muted pill with the reason as its tooltip. - The graph folds to its 32 px header ("Graph · N notes · folded while reading") while a note is open; back at the tree it returns to the person's own choice. The fold is not saved; `graph.hidden` stays the explicit setting. 4. **The ⌘K palette**, a popup (`mod.json` `overlay`: `kind: "popup"`, `at: "top"`, `offset: 40`, `width: 680`, `frame: "none"`). It is the `herdsidian` mod started a second time with `props().overlay` set. The card is 680 px wide, radius 14 (`RADIUS.overlay`), padding 16, the opaque theme `popover` color, a 1 px `line` border. Its height fits the content. - Header: a 14 px search icon and the search field (placeholder "Search notes, agents and commands…"), then the tabs All / Notes / Agents / Commands / Settings (24 px, radius 6; the active one `accentSoft` with `foreground` text, the others `muted`). With no vault there is no Notes tab. - Top hit (text typed, All tab): a 56 px row. The title is 14 px semibold `foreground`. A note's second line is 12 px `muted`: " · linked to · edited