---
title: "Ouro Shepherd: your Copilot app’s sessions, kept as work | Ouro"
description: "Ouro Shepherd keeps the GitHub Copilot app’s sessions as work: which are busy and why, how big each history has grown, messages, archives, resumes after a restart, quota and the sidebar. Experimental, and it runs always on a Mac."
url: https://ouroboros.bot/shepherd/
---

Experimental Watches, 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.

[Try it](https://ouroboros.bot/shepherd/#try)

![Ouro stands tall by a shepherd’s crook and a wooden gate while a line of robot-eyed sheep trots along their glowing track.](https://ouroboros.bot/brand/storybook/headers/shepherd.webp)

## 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](https://ouroboros.bot/housesitter/) and [Butler](https://ouroboros.bot/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 ↗](https://github.com/ourostack/ouroboros/blob/main/docs/shepherd-sense.md)

## 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 ↗](https://github.com/ourostack/shepherd#for-agents-the-cli-contract), and the library’s guide for agents is its [llms.txt](https://github.com/ourostack/shepherd/blob/main/llms.txt).
