Developers

Make Woolshed yours.

Almost everything you see in Woolshed is a layout or a mod: plain files in ~/.config/woolshed that you, or your agent, can copy and change. The complete reference ships inside the app and always matches your version.

❯ Read ~/.config/woolshed/AGENTS.md, then make me a layout where my agents are cards in columns: needs you, working, done.

Layouts

A layout arranges the window. It is a JSON tree of rows, columns and stacks whose cells hold mods, the active tab, a terminal or an agent. Woolshed ships three: Woolshed, Terminals and Woolshed 98. Duplicate one before you change it; your copy stays yours and the window reloads it when you save.

Mods

A mod is a folder in ~/.config/woolshed/mods/ with a main.js that draws a panel, menu or dialog. Mods get the app's data from the herdr module, which keeps that name so mods written for Herdr run unchanged. This one shows how many agents are waiting on you:

// ~/.config/woolshed/mods/needs-you/main.js
import { View, div } from "gpui-kit";
import { h_flex } from "gpui-base";
import { agents, theme } from "herdr";

export default class NeedsYou extends View {
  render() {
    const t = theme();
    const waiting = agents().filter(a => a.status === "blocked");
    return h_flex().gap(8).px(12).items_center().text_color(t.muted)
      .child(div().size(8).rounded(4).bg(waiting.length ? t.blocked : t.dim))
      .child(waiting.length ? `${waiting.length} waiting on you` : "All quiet");
  }
}

Check a mod before you use it with woolshed check ~/.config/woolshed/mods/needs-you. The type declarations in herdr.d.ts and gpui-kit.d.ts, installed beside the guide, describe the whole API.

Keys and commands

Every action has a command name. Bind any of them in keys.json, call them from a mod with run(), or send them from a terminal:

# every command, its arguments and what it does woolshed commands # what the window shows right now, and any errors woolshed status # run a command in the open window woolshed do app.palette

Agents that drive the window

Woolshed's terminals run in herdr-core, the hc command. Agents use it to start helpers, read their output, wait until one is done or blocked, and send them more work. The terminals keep running when the window closes.

hc run --bg --name web npm run dev # start it and return hc ls # live terminals hc read web --lines 100 # read without attaching hc --skill # the manual, written for agents

woolshed --skill prints the matching manual for driving the window itself.

The Herdr community

Woolshed is a fork of Herdr and keeps its formats, so layouts and mods from the Herdr community gallery work in Woolshed. When someone's instructions mention ~/.config/herdr-app, use ~/.config/woolshed instead.

Woolshed Voice

Voice dictation is in development. Mods and agents will be able to react to what you say and offer their own voice commands. This page will describe that API when it ships.