ExperimentalWatches, messages and archives the Copilot app’s sessions; terminals through Ouroboros.
Ouro Shepherd
Shepherd keeps the flock: your GitHub Copilot app’s sessions, as work. It knows which ones are busy and why, sizes their histories, messages and archives them, and runs on the Mac all the time.


What it does today
Fourteen duties are here now, in v0.8.1. Five wait for a config file before they act, and each card says which.
Which sessions are busy, and why
Every local session on one line: busy or idle, and the reason.
How big each history is
How much each session’s history has grown, so the huge ones are easy to spot.
Sending a message
Sends a session a message, and says whether it was accepted, queued or failed.
Archiving
Archives a session, or its workspace with it. A worktree goes too unless you ask to keep it.
Compressing old history
Compresses an archived session’s history, never a live one. Restoring brings it back.
Resuming after a restart or crash
After a restart or crash, sends each session that was running one message to carry on.
The 500 MB cap
A history over 500 MB is held back and never sent, because the app loads all of it on resume.
Size watch and hand-off retirement
Archives sessions that were handed off or finished, and flags oversize histories so their sessions can hand off. Off until retire.json enables it.
Stuck resume
A session whose loop stopped with no next turn gets one message to carry on, at most three times a day. Off until stuck-resume.json enables it.
The six-hour health watch
Follows each session it resumed for six hours, asks a silent or stuck one again, and tells its agent by name only about one that stays broken.
Billing account and quota
Moves a project off a spent Copilot account, and messages the sessions that stopped mid-work. Off until quota.json enables it.
Sidebar tidy
Hides projects nobody is working in, and always shows the homes you list. Off until sidebar.json enables it.
Desk’s wakes
Delivers a wake from Desk to a session, the message sent because something outside the app is due. Off until wakes.json enables it.
Waiting-prompt notices
Says which sessions wait on a person, for an answer or a plan to approve. The agent that talks to you decides what reaches you.
Run it always
shepherd install writes one launch agent, bot.ouro.shepherd, loads it and keeps it alive. Every 60 seconds it runs shepherd watch: one pass of the health watch, the quota balancer, the sidebar tidy, and the retirement, wake and stuck-resume duties its config enables, with no one at a terminal. shepherd install --dry-run prints the launch agent and changes nothing.
Its neighbours
Each one keeps a small, separate job. Housesitter and Butler have their own pages.
Housesitter keeps the house
The Mac, and the GitHub Copilot app as a running process: awake, unlocked, restarted when it freezes, at a safe point it asks each session for through Shepherd, and Ouroboros brought back when it stops. Shepherd never quits or relaunches the app.
Shepherd keeps the flock
The app’s sessions, as work: which are busy, how big, messages, archives, resumes and quota. Its CLI does the same for agents.
Ouroboros is an agent, not their home
It reaches the app only through Shepherd’s CLI, hears its notices, and decides what reaches its person. Housesitter brings it back when it stops.
Butler minds a different house
An Ouroboros agent that looks after a home server, on Unraid and Telegram. It never touches the Mac or the app.
The terminal part, in Ouroboros
Shepherd began inside the Ouroboros harness, for coding agents in terminals (cmux and Herdr). When one hands control back too early, a cheap judge decides it should have gone on, and Shepherd answers it in the terminal. That part still ships in Ouroboros today, as an alpha. How Shepherd decides ↗
Try it
Needs Node 22.18 or newer. It prints one line per local session and changes nothing.
npx github:ourostack/shepherd#v0.8.1 status For agents
Plain ESM, no build step and no runtime dependencies. Every verb takes flags, or one JSON object on stdin with --input -, and --json prints one line of JSON. The contract is in the README ↗, and the library’s guide for agents is its llms.txt.