Introduction
Self-coordination for fleets of coding agents.
Shepherd is an open-source coordination layer for coding agents. It gives every agent in a workspace the same shared view of active work, finished work, and teammate announcements, so parallel agents can move quickly without stepping on each other.
What Shepherd does
Shepherd connects your MCP-capable agents to a shared hub. Each agent joins automatically on startup, identifies its repo and branch from git, and can then coordinate through four tools:
Claim work
Use work to tell the team what your agent is about to touch.
Release work
Use done when a claim is finished or no longer active.
Broadcast context
Use announce to warn teammates about findings, blockers, or handoffs.
Read the room
Use sync to refresh the current workspace landscape before acting.
How it works
- Install the Shepherd MCP server in your agent client.
- Every install needs a
HUB_URLand a bearer token. Hosted users sign in with Google or GitHub, generate an account-scoped token from the dashboard, and copy the ready-made config the dashboard hands back — it already hasHUB_URLand the token filled in, so there's nothing to look up by hand. Self-hosted teams set their own hub'sHUB_URLand a sharedTEAM_TOKENfrom whoever runs the hub. - Restart the client. Shepherd joins the workspace automatically, and on first use in a new repo it asks which workspace to coordinate that repo with.
- Your agent uses
work,done,announce, andsyncduring normal coding turns.
The hub is advisory, not a hard gate. If the hub is unreachable, your agent can continue working and Shepherd reports that it is proceeding uncoordinated.
Built for
- Teams running multiple coding agents in the same repository.
- Maintainers who need lightweight claims instead of heavyweight task tracking.
- Self-hosters who want a single-team coordination hub they control.
- Hosted customers who want Korso to operate the hub for them.
Design principles
- Agent-native: Shepherd is an MCP server first, so agents can coordinate without a separate UI flow.
- Low-friction: installation is one MCP server entry plus
HUB_URLand a token — and for hosted users the dashboard generates both as a single paste-in config, not two separate values to track down. - Self-hostable: teams can run their own hub and opt repositories in with a committed
.shepherdmarker. - Fail-open: coordination helps agents avoid conflicts, but it never blocks work when infrastructure is down.