Shepherd — Orquestração de Múltiplas Sessões Claude Code
agurrrrr/shepherd
Orquestre múltiplos agentes Claude Code simultaneamente em diferentes projetos
Ver no GitHubMCP Server que gerencia múltiplos agentes Claude Code simultâneos via CLI, Web UI ou integração com Claude Desktop. Ideal para executar dezenas de tarefas de codificação em paralelo sem precisar de chaves de API — delega autenticação ao Claude Code CLI.
Instalação
npx convez-ai agurrrrr/shepherd1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar refatorações em múltiplos codebases em paralelo
- Delegar tarefas de codificação a múltiplos agentes simultaneamente
- Gerenciar grande volume de tarefas de desenvolvimento via CLI ou Web UI
Veredito

Shepherd resolve um problema real: coordenação de múltiplos agentes IA em paralelo. Bem arquitetado em Go com interfaces múltiplas (CLI/Web/MCP), mas requer Claude Code CLI instalado e é mais voltado a power users de desenvolvimento.
README
A tradução para o português deste README ainda está na fila.
Shepherd
AI coding orchestration CLI that manages multiple Claude Code sessions — like a shepherd tending a flock.
For Korean version, see README_KO.md.
Overview
Shepherd lets you run multiple AI coding agents simultaneously across different projects. It provides three interfaces to manage your flock:

- CLI — Interactive chat mode and direct commands
- Web UI — Full-featured dashboard with real-time streaming
- MCP Server — Integration with Claude Desktop and other MCP clients
Core Concepts
- Shepherd (Manager): Analyzes tasks and routes them to the right worker
- Sheep (Workers): Individual Claude Code instances, each assigned to a project
- Projects: Codebases that sheep work on
No API keys needed. Shepherd delegates all AI work to the Claude Code CLI, which handles its own authentication.
Requirements
- Go 1.21+ (to build)
- Node.js 18+ (for Web UI build)
- Claude Code CLI installed and available in
PATH
Installation
Quick Install
# Clone and build everything (CLI + Web UI + daemon)
git clone https://github.com/agurrrrr/shepherd.git
cd shepherd
./install.sh
The install script builds the Svelte frontend, compiles the Go binary, installs to ~/.local/bin/, and starts the daemon.
Manual Build
go build -o shepherd ./cmd/shepherd
cp shepherd ~/.local/bin/
Quick Start
# 1. Initialize the current directory as a project
shepherd init
# 2. Set up authentication (for Web UI)
shepherd auth setup
# 3. Start the daemon
shepherd serve -d
# 4. Open the Web UI
# http://localhost:8585
# 5. Or use the interactive CLI
shepherd
One-Liner Task
shepherd "Add login feature to the app"
Interactive Mode
Running shepherd with no arguments enters an interactive chat mode:
$ shepherd
🐑 Shepherd (my-project) > Add dark mode support
🐑 Shepherd (my-project) > status
🐑 Shepherd (my-project) > #42
Built-in commands:
| Command | Description |
|---|---|
help, ? | Show available commands |
status | System overview |
projects | List projects |
flock | List sheep |
log, history | Task history |
clear | Clear screen |
#<id> | View task details |
exit, quit, q | Exit |
Daemon & Server
Shepherd runs as a background daemon that serves both the Web UI and REST API.
shepherd serve # Foreground (for development)
shepherd serve -d # Background daemon
shepherd serve status # Check daemon status
shepherd serve stop # Stop daemon
Flags:
| Flag | Description | Default |
|---|---|---|
-d, --daemon | Run as background daemon | false |
--cors-origin | Allowed CORS origins (comma-separated) | * |
Environment variables:
| Variable | Description |
|---|---|
SHEPHERD_CORS_ORIGIN | Allowed CORS origins (alternative to --cors-origin) |
Files:
- PID file:
~/.shepherd/shepherd.pid - Database:
~/.shepherd/shepherd.db - Config:
~/.shepherd/config.yaml
systemd Service (Optional)
# ~/.config/systemd/user/shepherd.service
[Unit]
Description=Shepherd AI Orchestration Daemon
After=network.target
[Service]
ExecStart=%h/.local/bin/shepherd serve
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target
systemctl --user enable --now shepherd
Authentication
Shepherd uses config-based single-user authentication with JWT tokens and bcrypt password hashing.
# Initial setup (interactive: username + password)
shepherd auth setup
# Change password
shepherd auth change-password
- JWT secret is auto-generated on first server start
- Access tokens expire in 24 hours, refresh tokens in 7 days
- API requests require
Authorization: Bearer <token>header - Health endpoint (
GET /api/health) is public
Web UI
The Web UI is a Svelte SPA embedded in the Go binary. Access it at http://localhost:8585 after starting the daemon.
Pages
| Page | Path | Description |
|---|---|---|
| Dashboard | / | Sheep status cards, running tasks, command input |
| Sheep | /sheep | Create, delete, change provider |
| Projects | /projects | Project list and management |
| Project Detail | /projects/:name | Git log, branches, docs, schedules, skills |
| Tasks | /tasks | Task list with filtering and search |
| Task Detail | /tasks/:id | Full output, modified files, error details |
| Schedules | /schedules | Cron/interval schedule management |
| Skills | /skills | Skill creation, import/export |
| Settings | /settings | Language, provider, configuration |
| Login | /login | Authentication |
Real-Time Updates (SSE)
The Web UI receives live updates via Server-Sent Events:
GET /api/events?token=<access_token>
Events: task_start, task_complete, task_fail, output, status_change, schedule_triggered
External Access via Ingress
For HTTPS access outside your network, use a reverse proxy (e.g., Nginx, Caddy) or Kubernetes Ingress with cert-manager.
Commands Reference
Sheep Management
shepherd spawn # Create sheep (auto-named)
shepherd spawn -n dolly # Create with specific name
shepherd spawn -p opencode # Create with OpenCode provider
shepherd flock # List all sheep
shepherd recall <name> # Terminate a sheep
shepherd recall --all # Terminate all sheep
shepherd set-provider <name> auto # Change provider
Project Management
shepherd init [name] # Register current directory
shepherd project add <name> <path> -d "desc" # Add a project
shepherd project list # List projects
shepherd project remove <name> # Remove a project
shepherd project assign <project> <sheep> # Assign a sheep
Task Execution
shepherd "<task>" # Submit task (auto-routed by manager)
shepherd task "<task>" # Explicit task command
Task Queue
shepherd queue add <project> "<prompt>" # Add task to queue
shepherd queue list # List pending tasks
shepherd queue import-issues <project> <YouTrackProject> [query] # Import from YouTrack
Browser Automation
shepherd browser open <url> [-s sheep] [--headless] # Open URL
shepherd browser get-text <selector> [-s sheep] # Extract text
shepherd browser get-html [--selector <sel>] # Get HTML
shepherd browser screenshot [path] [--selector <sel>] # Capture screenshot
shepherd browser fetch <url> [--selector <sel>] # Fetch and extract content
shepherd browser list [-s sheep] # List open pages
shepherd browser close [-s sheep] # Close session
Status & Logs
shepherd status # System overview
shepherd log # Full task log
shepherd log <sheep> -n 50 # Logs for a specific sheep
shepherd history <project> # Project task history
Sheep Names
shepherd names list # List custom names
shepherd names add Dolly Shaun # Add custom names
shepherd names remove Dolly # Remove a name
Configuration
shepherd config get <key> # Get a config value
shepherd config set <key> <val> # Set a config value
shepherd config path # Show config file path
Other
shepherd tui # Terminal UI dashboard
shepherd recover # Recover stuck sheep/tasks
shepherd mcp # Run as MCP server
shepherd --version # Show version
Scheduling
Schedules are managed via the Web UI (/schedules) or REST API. Two types are supported:
- Cron: Standard cron expressions (e.g.,
0 9 * * MON-FRI) - Interval: Run every N seconds
POST /api/projects/:name/schedules
GET /api/schedules/preview?cron=0 9 * * * # Preview next 5 run times
POST /api/projects/:name/schedules/:id/run # Trigger immediately
Schedules automatically create tasks at the configured times.
Skills
Skills are reusable prompt templates that can be attached to projects or used globally. Managed via the Web UI (/skills) or REST API.
- Global skills: Available to all projects
- Project skills: Scoped to a specific project
- Bundled skills: Pre-installed default skills (auto-seeded on first startup)
- Import/Export: Share skills as markdown files with YAML frontmatter
- Lazy loading: Only skill names and descriptions are injected into prompts; agents load full content on demand via the
skill_loadMCP tool - Sync to project: Skills can be synced to each project's
.claude/skills/directory
Skill Frontmatter
Skills support YAML frontmatter for metadata:
---
name: code-review
description: Code review checklist
tags: [review, quality]
scope: global
effort: medium
max_turns: 10
disallowed_tools: [Write, Bash]
---
(skill content here)
| Field | Description |
|---|---|
effort | Model inference effort (low, medium, high) |
max_turns | Maximum agent turns (0 = unlimited) |
disallowed_tools | List of tools the agent cannot use |
GET /api/skills # List global skills
POST /api/skills/import # Import from file
GET /api/skills/:id/export # Export to file
POST /api/skills/sync-all # Sync all skills to project directories
Configuration
Config file: ~/.shepherd/config.yaml
language: en # en, ko
default_provider: claude # claude, opencode, auto
max_sheep: 12 # Maximum concurrent sheep
db_path: ~/.shepherd/shepherd.db
log_level: info # debug, info, warn, error
server_port: 8585
server_host: 0.0.0.0
auto_approve: true
# Authentication (set via 'shepherd auth setup')
auth_username: admin
auth_password_hash: "$2a$10$..."
auth_jwt_secret: "auto-generated"
Architecture
User Input → Interactive CLI / Web UI / MCP Client
→ Shepherd Daemon (REST API + SSE)
→ Manager (analyzes intent via Claude Code CLI)
→ Routes to appropriate sheep
→ Worker runs Claude Code (--print [--resume SESSION_ID])
→ Queue records result
→ Real-time updates via SSE → all connected clients
Multi-Provider Support
| Provider | CLI | Use Case |
|---|---|---|
claude | Claude Code | Default — code writing, complex tasks |
opencode | OpenCode | Reviews, web search, simple tasks |
auto | Auto-select | Analyzes prompt and picks the best provider |
Project Structure
shepherd/
├── cmd/shepherd/ # CLI entrypoint (~2000 lines, all commands)
├── ent/schema/ # Ent ORM entities (Sheep, Project, Task, Skill, Schedule, SkillLink)
├── internal/
│ ├── agent/ # AI provider abstraction (Claude, OpenCode)
│ ├── browser/ # Browser automation (Rod)
│ ├── config/ # Viper-based YAML config
│ ├── daemon/ # PID file, signal handling, lifecycle
│ ├── db/ # SQLite database
│ ├── i18n/ # Internationalization (en, ko)
│ ├── manager/ # Task analysis & routing
│ ├── mcp/ # JSON-RPC 2.0 MCP server
│ ├── names/ # Sheep name pool
│ ├── project/ # Project CRUD
│ ├── queue/ # Task lifecycle management
│ ├── scheduler/ # Cron & interval scheduling
│ ├── server/ # Fiber HTTP server, SSE, auth, handlers
│ ├── skill/ # File-based skill system
│ ├── tui/ # Bubbletea terminal UI
│ └── worker/ # Sheep execution & session management
└── web/ # Svelte SPA (JavaScript only, no TypeScript)
REST API
All endpoints (except auth and health) require JWT authentication.
Auth
POST /api/auth/login # Returns access + refresh tokens
POST /api/auth/refresh # Refresh access token
Resources
GET|POST /api/sheep # List / Create
GET|DELETE /api/sheep/:name # Get / Delete
PATCH /api/sheep/:name/provider # Update provider
GET|POST /api/projects # List / Create
GET|DELETE /api/projects/:name # Get / Delete
POST /api/projects/:name/assign # Assign sheep
GET|POST /api/tasks # List / Create
GET /api/tasks/:id # Get details (includes cost_usd)
POST /api/tasks/:id/stop # Stop running task
POST /api/tasks/:id/retry # Retry failed/stopped task
POST /api/tasks/:id/retry-from # Bulk retry from this task onwards
Git (Read-Only)
GET /api/projects/:name/git/log # Commit history
GET /api/projects/:name/git/branches # Branches
GET /api/projects/:name/git/commits/:hash # Commit detail
GET /api/projects/:name/git/commits/:hash/diff # Commit diff
GET /api/projects/:name/git/changes # Uncommitted changes
Schedules & Skills
GET|POST /api/projects/:name/schedules # List / Create
GET|PATCH|DELETE /api/projects/:name/schedules/:id # CRUD
POST /api/projects/:name/schedules/:id/run # Trigger now
GET|POST /api/skills # List / Create global
POST /api/skills/import # Import
POST /api/skills/sync-all # Sync all skills to projects
GET|PATCH|DELETE /api/skills/:id # CRUD
GET /api/skills/:id/export # Export
GET|POST /api/projects/:name/skills # Project-scoped skills
System
GET /api/health # Health check (public)
GET /api/system/status # System stats
POST /api/system/restart # Restart daemon
GET /api/events # SSE stream
POST /api/command # Natural language command
POST /api/upload # File upload (10MB limit)
MCP Server
Run Shepherd as an MCP server for integration with Claude Desktop:
{
"mcpServers": {
"shepherd": {
"command": "shepherd",
"args": ["mcp"]
}
}
}
Available MCP tools: task_start, task_complete, task_error, get_history, get_status, skill_load, and 20+ browser automation tools (browser_open, browser_click, browser_type, browser_screenshot, etc.)
Sheep Names
Default name pool (Korean sheep names):
양동이, 양말이, 양철이, 양순이, 메에롱, 깜순이, 흰둥이, 복실이, 숀, 뭉치, 구름이, 몽실이
Add custom names with shepherd names add <name>.
Error Handling & Recovery
- Auto-recovery: Stuck sheep and tasks are recovered on daemon/TUI startup
- Manual recovery:
shepherd recover - Graceful shutdown: Handles SIGINT/SIGTERM, saves state before exit
- Timeouts: 60 sec (task analysis), 30 min (interactive execution)
Rate Limit Retry
When a rate limit error is detected (HTTP 429, "too many requests", etc.), Shepherd automatically retries with exponential backoff:
- Up to 3 retries per task
- Backoff: 30s → 60s → 120s (capped at 5 minutes)
- Retry progress is streamed to the UI in real-time
Circuit Breaker
If a sheep fails 5 consecutive tasks, Shepherd automatically pauses task execution for that sheep to prevent wasting resources.
- Tripped breakers are shown in
statusand the dashboard - Manually retrying a task (
POST /api/tasks/:id/retry) resets the breaker - Successful task completion also resets the counter
Cost Tracking
Task execution costs are captured from Claude Code output and stored per task.
cost_usdfield on each task (returned in all API responses)- Per-project and global cost aggregation
- Total cost displayed in queue status
Development
go build ./... # Build all packages
go test ./... # Run all tests
go test ./internal/worker -run TestName # Run specific test
go generate ./ent # Regenerate Ent ORM code
cd web && npm install && npm run dev # Web UI dev server
cd web && npm run build # Web UI production build
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT License — see LICENSE for details.
"The Lord is my shepherd; I shall not want." — Psalm 23:1