# Kaapi A dark workspace for coding agents: terminals the color of filter-coffee decoction sit inside near-black roasted chrome, with milky cream text, a brass focus ring, and status colors drawn from jaggery, chilli, steel and banana leaf. Spaces and agents stay visible on the left; the active work fills the center. The palette takes inspiration from Indian coffee: a South Indian filter kaapi poured between a steel tumbler and dabara. This is a brief another agent can build from an empty folder in a current Herdr installation. The adjacent files are one implementation, based on Herdr desktop 0.1.11. ![Kaapi](preview.png) ## What you see The window has no separate system title bar. At zoom 1, arrange it as a horizontal row with a 1px border-colored divider: 1. A 268px-wide left sidebar, resizable from 44 to 480px, on the darkest roast (`chrome`). Its top 46px holds Herdr's brand, search and sidebar control. Below it, Spaces and Agents share the remaining list area equally, each at least 90px tall. The bottom 69px holds Settings and Add machine. The list container has no extra divider. 2. A flexible work column. A 42px tab strip sits at the top. The body has 8px padding and 8px gaps on the near-black canvas. Terminals fill the space; an optional panel on the right starts hidden, is 368px wide when open, and resizes from 280 to 900px. A 28px status bar sits at the bottom. 3. Every terminal pane, including a lone one, is a card: 10px corner radius, 1px brown border, 8px gap to its neighbours, and a 30px always-visible header. The focused pane's border is brass. Terminal padding is 14px vertically and 12px horizontally. Use the person's font settings. With Herdr's defaults, terminal text is JetBrains Mono at 14px and UI text is Geist. The screenshot uses 15px terminal text. Don't bundle fonts or fix the zoom. On macOS, leave room for the native window buttons at `[12, 16]`. The palette is warm and brown without going muddy or orange: | Color role | Value | | --- | --- | | Terminal background (decoction) | `#1C1612` | | Foreground (milk foam) | `#EADFCB` | | Canvas behind panes | `#120E0B` | | Sidebar and bars (`chrome`) | `#17120F` | | Surface | `#221B16` | | Popover | `#2A211B` | | Raised surface | `#30261F` | | Hover | `#2B231D` | | Selected UI row | `#3E2C25` | | Border | `#45382E` | | Input | `#2A211B` | | Muted text | `#C2B39C` | | Dim text / unknown status | `#A69580` | | Accent, solid button (brass) | `#D9A566` | | Text on accent / solid button | `#1C1612` | | Cursor | `#E2AE68` | | Terminal selection | `#3D3026` | | Working (jaggery) | `#E3A857` | | Blocked (chilli) | `#EA7D65` | | Done (steel) | `#93B5CC` | | Idle (banana leaf) | `#A8C385` | ANSI colors, in index order 0–15: ```text 0 #4D4037 1 #EA8069 2 #A9C385 3 #E3B46C 4 #8FB2CB 5 #D49AAE 6 #86C1B1 7 #D9CDB8 8 #A89782 9 #F28E76 10 #BCD49A 11 #F0C682 12 #A8C4DA 13 #E2AFC1 14 #9CD3C3 15 #F4EBDC ``` Keep the color families recognizable (red errors, green additions, yellow warnings, blue links) but softened toward the coffee palette. ANSI 0 is a dark roast brown, deliberately close to the background because programs use it as a fill; ANSI 8 (bright black, used for comments and hints) must stay readable. ## How it behaves Use the standard Herdr workspace behavior. Spaces select their work; tabs select a task; agents focus their terminal. The sidebar tracks live data, including agents in other spaces and reported child agents. Agent order and grouping belong to the built-in Agents panel and keep the person's choices. | Agent status | Appearance | | --- | --- | | Working | Jaggery-amber group label and the native spinning ring, also on the tab pill and pane header | | Blocked | Chilli-red "Needs you" group with a count, an exclamation badge on the row, "1 needs you" in the status bar | | Done | Steel-blue group label and dot; becomes idle once seen, with Herdr's normal list-stability behavior | | Idle | Banana-leaf green outlined ring | Statuses come from the terminal program's reports (OSC 7501), not from screen text. A program that doesn't report stays a plain terminal. Hovered rows get the hover fill; the selected space and focused agent get the reddish-brown selected fill. The focused pane's brass border stands clear of the neutral brown borders. The sidebar resizes and folds with its normal controls; below 160px the built-in panels draw their compact rail. Tabs keep the standard + menu. Files and Changes open from the tab bar and are remembered per space. Pane headers keep split, zoom and close. Split panes keep Herdr's drag and resize. Native popups, menus and dialogs use the same semantic colors. Install no key overrides. Existing shortcuts keep working; with the standard macOS bindings, Command-B toggles the sidebar and Command-Shift-L cycles layouts. The command palette is authoritative. Kaapi creates no terminals, runs no agents and doesn't rearrange existing tabs. Switching layouts changes the view of the same work. ## Built from Create `themes/kaapi.json` with `background`, `foreground`, `selection`, `cursor`, a 16-entry `ansi` array, and a `colors` object holding the semantic palette above (`background`, `foreground`, `canvas`, `chrome`, `surface`, `popover`, `raised`, `hover`, `selected`, `border`, `input`, `muted`, `dim`, `accent`, `accent_foreground`, `solid`, `solid_foreground`, `selection`, `working`, `blocked`, `done`, `idle`, `unknown`). All values are six-digit hex. Put the terminal colors at the top level and repeat them as semantic entries. Create `layouts/kaapi-workspace.json` by cloning Herdr's shipped `main` layout (`herdr-app do layout.clone '{"name":"main","as":"kaapi-workspace"}'`), then set the root `theme` to `"kaapi"` and `preview` to `"layouts/kaapi-workspace.svg"`. Keep `cloned_from`. Apart from those two fields the tree is identical to `main` in 0.1.11. Keep these node IDs; built-in controls target them: ```text root (row, titlebar: none, traffic_lights: [12, 16], background: canvas, terminal_padding: [14, 12], divider 1px border) ├── sidebar (column, 268px, min 44, max 480, background: chrome, resizable: false) │ ├── brand → workspace-chrome (46px, window_drag) │ ├── sidebar-lists (column) │ │ ├── spaces → spaces (weight 1, min 90) │ │ └── agents → agents (weight 1, min 90) │ └── sidebar-footer → workspace-chrome, props: {footer: true} (69px) └── work (column, resizable: false) ├── tabs → tabs (42px, window_drag) ├── work-body (row, padding 8, gap 8) │ ├── main → content: {tab: "active", pane: {...}} │ │ pane: background "background", border 1px "border", │ │ focus 1px "accent", radius 10, gap 8, lone: true, │ │ header: {content: {mod: "pane"}, height 30, position "top", reveal "always"} │ └── panel (column, 368px, min 280, max 900, hidden) │ └── panel-body (stack, active: "files") │ ├── files → files │ └── changes → changes └── status → workspace-status (28px) ``` Use theme color names (`chrome`, `canvas`, `border`, `accent`) in the layout, not hex, so the theme file stays the single source of color. The eight mods ship with Herdr: `workspace-chrome`, `spaces`, `agents`, `tabs`, `pane`, `files`, `changes`, and `workspace-status`. They bring Herdr's shipped menus, pickers, icons and dialogs. There is no custom JavaScript; `mods/README.md` lists these dependencies. Reuse the installed versions and never overwrite shipped mod folders. Their data comes from Herdr's live spaces, agents, panes and terminals; their controls run the standard `space.*`, `tab.*`, `pane.*`, `agent.*`, `layout.*` and app commands. The theme and layout run no programs and fetch no URLs. The built-in Files, Changes and workspace panels keep Herdr's normal filesystem, git and machine behavior. Draw a 640×400 SVG thumbnail in the palette (sidebar with "Kaapi", a selected space row, three status dots, a brass-bordered focused card beside a neutral one, colored code bars) and save it as `layouts/kaapi-workspace.svg`. The full-size `preview.png` must be a screenshot of the real app (`herdr-app shot`). Use synthetic demo spaces, ANSI-colored code, a diff, and reported demo statuses (one each of working, blocked, done, idle) so the colors show without personal terminal content. ## Watch out - This targets the desktop app (`herdr-app`), not the older Herdr TUI. Read the installed `AGENTS.md` and type files when adapting it. - Shipped layouts and mods are replaced on every start. Keep the layout in its own file; don't edit shipped mods. - Preserve the person's settings, keys, saved layout state and live terminals. Don't distribute `view.json`, `shared.json`, `layouts/.state/`, machine config or session IDs. - Layout (`kaapi-workspace`) and theme (`kaapi`) have different names so the theme can be picked on its own in any layout. Copy both for the full look. - A theme-picker choice can override the layout's root theme. Run `herdr-app do app.theme --name kaapi` after switching if the colors don't change. The theme is for the dark appearance; someone in light appearance must switch to Dark (Settings → Look) to see it. - Don't overwrite an existing `kaapi.json` or `kaapi-workspace.json`. If a name is taken, rename the new file and update the layout's `theme` and `preview` references. - Contrast figures are for this palette only. Foreground is 13.6:1 on the terminal background and 9.7:1 on selection. ANSI 1–15 are at least 6.3:1 on the background and 4.5:1 on the selection fill. ANSI 0 is 1.8:1 by design; text printed in plain black will be faint. UI dim text is at least 4.5:1 on every UI fill. Truecolor output, dim attributes, reverse video and app-chosen backgrounds can differ. Don't force Herdr's minimum-contrast setting. - Don't let the browns drift orange or grey. Every neutral is a red-leaning brown; the selected row (`#3E2C25`) is slightly redder than hover (`#2B231D`) so selection reads as a choice, not a highlight. - Space avatar colors (the lettered squares) come from Herdr's per-space color picker, not from this theme. - A sandboxed preview window shows a one-time "Updated to …" pill after first launch; restart that window before taking the screenshot. The screenshot is a 1440×961 logical-pixel window captured at 2880×1922. - At narrow widths, rely on sidebar folding and pane zoom. Don't add horizontal scrolling. - If newer built-in panels expect different node IDs or structure, re-clone the current `main` and reapply the two root fields. ## Done when - Installing into a Herdr home adds Kaapi to the theme list and Kaapi workspace to the layouts; existing layouts still work. - `herdr-app status` reports `layout: "kaapi-workspace"` and an empty `errors` list after switching. - Spaces, tabs, agents and live terminals render; picking a space, tab or agent shows its terminal. - Four demo agents reporting working, blocked, done and idle show amber, red, blue and green as described, and a non-reporting shell stays a terminal. - The focused pane has a brass border, the other pane a brown one; both have headers, even when a tab has one pane. - The sidebar hides and shows; Files and Changes open from the tab bar; a split pane can be focused and zoomed. - The eight built-in mods each pass `herdr-app check `. - `preview.png` is a real screenshot with synthetic content only.