{"id":44147225,"url":"https://github.com/cloud-shuttle/drover","last_synced_at":"2026-02-09T02:35:29.900Z","repository":{"id":331734054,"uuid":"1129011550","full_name":"cloud-shuttle/drover","owner":"cloud-shuttle","description":"No task left behind 🐂","archived":false,"fork":false,"pushed_at":"2026-01-19T13:51:11.000Z","size":15439,"stargazers_count":40,"open_issues_count":5,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-19T16:25:06.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-shuttle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-06T13:33:25.000Z","updated_at":"2026-01-19T15:11:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cloud-shuttle/drover","commit_stats":null,"previous_names":["cloud-shuttle/drover"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cloud-shuttle/drover","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fdrover","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fdrover/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fdrover/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fdrover/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-shuttle","download_url":"https://codeload.github.com/cloud-shuttle/drover/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-shuttle%2Fdrover/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29254316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T01:52:29.835Z","status":"online","status_checked_at":"2026-02-09T02:00:09.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-09T02:35:29.054Z","updated_at":"2026-02-09T02:35:29.893Z","avatar_url":"https://github.com/cloud-shuttle.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐂 Drover\n\n**Drive your project to completion with parallel AI agents.**\n\n![Drover](images/drover.png)\n\nDrover is a durable workflow orchestrator that runs multiple Claude Code agents in parallel to complete your entire project. It manages task dependencies, handles failures gracefully, and guarantees progress through crashes and restarts.\n\n\u003e *\"No task left behind.\"*\n\n## Workflow Engine\n\nDrover uses **DBOS (Durable Operating System for Workflows)** as its primary workflow engine:\n\n- **Development**: SQLite-based orchestration (zero setup, works out of the box)\n- **Production**: DBOS with PostgreSQL (set `DBOS_SYSTEM_DATABASE_URL`)\n\nBoth modes provide durable execution, automatic retries, and crash recovery.\n\n## Why Drover?\n\nYou have a project with dozens of tasks. Running them one at a time is slow. Running them manually in parallel is chaotic. Drover solves this by:\n\n- **Parallel execution** — Run 4, 8, or 16 Claude Code agents simultaneously\n- **Durable workflows** — Survive crashes, restarts, and network failures\n- **Smart scheduling** — Respects task dependencies, priorities, and blockers\n- **Isolated workspaces** — Each agent works in its own git worktree\n- **Automatic retries** — Failed tasks retry with exponential backoff\n- **Progress tracking** — Real-time status and completion estimates\n\n## Quick Start\n\n```bash\n# Install (note: use the full package path including /cmd/drover)\ngo install github.com/cloud-shuttle/drover/cmd/drover@latest\n\n# Add Go's bin directory to your PATH if not already configured\nexport PATH=$PATH:$HOME/go/bin\n\n# Initialize in your project\ncd my-project\ndrover init\n\n# Create an epic and tasks\ndrover epic add \"MVP Features\"\ndrover add \"Set up database schema\" --epic epic-a1b2\ndrover add \"Implement user authentication\" --epic epic-a1b2\ndrover add \"Build REST API\" --epic epic-a1b2 --blocked-by task-x1y2\ndrover add \"Add unit tests\" --epic epic-a1b2 --blocked-by task-x1y2,task-z3w4\n\n# Run everything to completion\ndrover run --workers 4\n\n# Or run a specific epic\ndrover run --epic epic-a1b2\n```\n\n## Installation\n\n### Prerequisites\n\n- Go 1.22+\n- Git\n- [Claude Code CLI](https://claude.ai/code) installed and authenticated\n- PostgreSQL (production) or SQLite (local dev, default)\n\n### From Source\n\n```bash\ngit clone https://github.com/cloud-shuttle/drover\ncd drover\ngo build -o drover .\n```\n\n### With Go Install\n\n```bash\ngo install github.com/cloud-shuttle/drover/cmd/drover@latest\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `drover init` | Initialize Drover in current project |\n| `drover run` | Execute all tasks to completion |\n| `drover run --workers 8` | Run with 8 parallel agents |\n| `drover run --epic \u003cid\u003e` | Run only tasks in specific epic |\n| `drover add \u003ctitle\u003e` | Add a new task |\n| `drover add \u003ctitle\u003e --parent \u003cid\u003e` | Add a sub-task to parent |\n| `drover add \"task-123.N title\"` | Add sub-task with hierarchical syntax |\n| `drover epic add \u003ctitle\u003e` | Create a new epic |\n| `drover status` | Show current project status |\n| `drover status --watch` | Live progress updates |\n| `drover status --tree` | Show hierarchical task tree |\n| `drover reset` | Reset all tasks back to ready |\n| `drover reset task-abc task-def` | Reset specific tasks by ID |\n| `drover reset --failed` | Reset all failed tasks |\n| `drover resume` | Resume interrupted workflows |\n| `drover worktree prune` | Clean up completed task worktrees |\n| `drover worktree prune -a` | Clean up all worktrees (incl. build artifacts) |\n| `drover import \u003cfile\u003e` | Import tasks from a `.drover` export file |\n| `drover import-jsonl \u003cfile.jsonl\u003e` | Import tasks from JSON Lines format |\n| `drover export [--format json]` | Export tasks to portable format |\n\n### Bulk Task Creation\n\nFor importing multiple tasks at once, Drover provides several options:\n\n#### 1. JSONL Import (Native CLI)\n\nUse `drover import-jsonl` to import epics, stories, and tasks from JSON Lines format:\n\n```bash\ndrover import-jsonl tasks.jsonl\n```\n\nJSONL format (one JSON object per line):\n```jsonl\n{\"id\": \"EPIC-001\", \"type\": \"epic\", \"title\": \"Project Foundation\", \"description\": \"Set up infrastructure\"}\n{\"id\": \"STORY-001\", \"type\": \"story\", \"epic_id\": \"EPIC-001\", \"title\": \"Initialize Rust Workspace\", \"description\": \"Create workspace\", \"priority\": 10}\n{\"id\": \"TASK-001\", \"type\": \"task\", \"story_id\": \"STORY-001\", \"title\": \"Create cargo structure\", \"description\": \"Set up Cargo.toml\", \"priority\": 5}\n```\n\nSee `examples/gather-project.jsonl` for a complete example.\n\n**Priority values:**\n- Integer: 1-10 (higher = more urgent)\n- String: \"critical\" (10), \"high\" (7), \"normal\" (5), \"low\" (2)\n\n#### 2. AI-Powered Task Generation\n\nUse `drover spec` to generate epics and tasks from design specifications:\n\n```bash\n# Generate from a spec file\ndrover spec design/spec.md\n\n# Generate from a folder of design docs\ndrover spec design/\n\n# Preview without creating\ndrover spec spec.md --dry-run\n```\n\n#### 3. Session Import/Export\n\nExport and import complete Drover sessions:\n\n```bash\n# Export current session\ndrover export session.jsonl\n\n# Import on another machine\ndrover import session.jsonl\n```\n\n## Configuration\n\nDrover uses sensible defaults but can be configured via environment variables or flags:\n\n```bash\n# Database (default: SQLite in .drover.db)\nexport DROVER_DATABASE_URL=\"postgresql://localhost/drover\"\n\n# Or use SQLite explicitly\nexport DROVER_DATABASE_URL=\"sqlite:///.drover.db\"\n\n# Agent selection (default: claude)\nexport DROVER_AGENT_TYPE=\"claude\"  # Options: claude, codex, amp, opencode\nexport DROVER_AGENT_PATH=\"/path/to/agent\"  # Optional: custom agent binary path\n```\n\n### Agent Types\n\nDrover supports multiple AI coding agents through a pluggable interface:\n\n| Agent | Type | Description |\n|-------|------|-------------|\n| **Claude Code** | `claude` | Anthropic's Claude Code CLI (default) |\n| **Codex** | `codex` | OpenAI's Codex agent |\n| **Amp** | `amp` | Amp AI agent |\n| **OpenCode** | `opencode` | OpenCode CLI by Anomaly |\n\n```bash\n# Use Codex instead of Claude\nexport DROVER_AGENT_TYPE=\"codex\"\ndrover run\n\n# Use Amp with a custom binary path\nexport DROVER_AGENT_TYPE=\"amp\"\nexport DROVER_AGENT_PATH=\"/usr/local/bin/amp\"\ndrover run\n\n# Use OpenCode\nexport DROVER_AGENT_TYPE=\"opencode\"\nexport DROVER_AGENT_PATH=\"/usr/local/bin/opencode\"\ndrover run\n```\n\n**Note:** The deprecated `DROVER_CLAUDE_PATH` environment variable still works for backwards compatibility.\n\n### Observability\n\nDrover includes built-in OpenTelemetry observability for production monitoring:\n\n```bash\n# Enable OpenTelemetry (disabled by default)\nexport DROVER_OTEL_ENABLED=true\nexport DROVER_OTEL_ENDPOINT=localhost:4317\n\n# Run with observability\ndrover run\n```\n\n**What you get:**\n- **Traces**: Distributed tracing for workflows, tasks, and agent execution\n- **Metrics**: Task completion rates, duration histograms, error counts\n- **Dashboards**: Grafana dashboards for real-time monitoring\n\n**Quick Start (with Docker):**\n```bash\n# Start the observability stack\ndocker compose -f docker-compose.telemetry.yaml up -d\n\n# Run Drover with telemetry\nexport DROVER_OTEL_ENABLED=true\ndrover run\n\n# View dashboards\nopen http://localhost:3000  # admin/admin\n```\n\nSee [Observability Guide](./scripts/telemetry/README.md) for details.\n\n### Task Options\n\n```bash\n# Set priority (higher = more urgent)\ndrover add \"Critical fix\" --priority 10\n\n# Define dependencies\ndrover add \"Build API\" --blocked-by task-abc,task-def\n\n# Assign to epic\ndrover add \"New feature\" --epic epic-xyz\n```\n\n## Sub-Tasks\n\nDrover supports **hierarchical sub-tasks** with Beads-style task IDs (e.g., `task-123.1`, `task-123.1.2`). This lets you break down complex work into manageable pieces.\n\n### Creating Sub-Tasks\n\nThere are two ways to create sub-tasks:\n\n#### 1. Using the `--parent` flag\n\n```bash\n# Create a parent task\ndrover add \"Implement authentication\"\n# ✅ Created task task-1736123456789\n\n# Add sub-tasks using --parent\ndrover add \"Design schema\" --parent task-1736123456789\n# ✅ Created task task-1736123456789.1\n\ndrover add \"Implement login\" --parent task-1736123456789\n# ✅ Created task task-1736123456789.2\n\ndrover add \"Add OAuth\" --parent task-1736123456789\n# ✅ Created task task-1736123456789.3\n```\n\n#### 2. Using hierarchical ID syntax\n\n```bash\n# Specify sequence number directly in the title\ndrover add \"task-1736123456789.5 Add JWT tokens\"\n# ✅ Created task task-1736123456789.5\n\ndrover add \"task-1736123456789.10 Write tests\"\n# ✅ Created task task-1736123456789.10\n```\n\n### Viewing Sub-Tasks\n\nUse the `--tree` flag for a hierarchical view:\n\n```bash\ndrover status --tree\n```\n\nOutput:\n```\n🐂 Drover Task Tree\n════════════════════\n⏳ task-1736123456789: Implement authentication\n    └── ⏳ task-1736123456789.1: Design schema\n    └── ⏳ task-1736123456789.2: Implement login\n    └── ⏳ task-1736123456789.3: Add OAuth\n    └── ⏳ task-1736123456789.5: Add JWT tokens\n    └── ⏳ task-1736123456789.10: Write tests\n```\n\n### How Sub-Tasks Execute\n\nWhen a parent task is claimed for execution:\n\n1. **Sub-tasks execute first** — All sub-tasks run sequentially (in order)\n2. **Parent executes last** — Only after all sub-tasks complete\n3. **Failure propagates** — If any sub-task fails, the parent task fails\n\nSub-tasks are **never claimed independently** — they only run as part of their parent task's execution.\n\n### Hierarchy Rules\n\n- **Maximum depth**: 2 levels (Epic → Parent → Child)\n- **Sequence numbers**: Auto-incremented when using `--parent`, user-specified when using syntax\n- **ID format**: `parent-id.sequence` (e.g., `task-123.1`)\n\n### Example: Breaking Down a Feature\n\n```bash\n# Create the main feature task\ndrover add \"Build user settings page\" --skip-validation\n\n# Break it down into sub-tasks\ndrover add \"Create settings UI component\" --parent task-xyz\ndrover add \"Add settings persistence\" --parent task-xyz\ndrover add \"Implement validation\" --parent task-xyz\ndrover add \"Add unit tests\" --parent task-xyz\n\n# View the hierarchy\ndrover status --tree\n\n# Run - sub-tasks execute automatically when parent runs\ndrover run\n```\n\n## How It Works\n\n### The Drover Loop\n\n```\nwhile project has incomplete tasks:\n    1. Find all ready tasks (no unmet dependencies)\n    2. Claim tasks up to worker limit\n    3. Execute each task in isolated git worktree\n    4. On success: commit, merge, unblock dependents\n    5. On failure: retry or mark failed\n    6. On blocked: create resolution task (optional)\n\n    Sleep and repeat until complete\n```\n\n### Durability\n\nDrover uses [DBOS](https://dbos.dev) for durable workflow execution. Every step is checkpointed to the database. If Drover crashes:\n\n1. Restart with `drover resume`\n2. DBOS automatically recovers all workflows from their last checkpoint\n3. Partially completed tasks resume, not restart\n\n### Task States\n\n```\nready → claimed → in_progress → completed\n                      ↓\n                   blocked → (unblocked) → ready\n                      ↓\n                   failed (after max retries)\n```\n\n### Git Worktrees\n\nEach worker operates in an isolated git worktree:\n\n```\n.drover/\n└── worktrees/\n    ├── task-a1b2/    # Worker 1\n    ├── task-c3d4/    # Worker 2\n    ├── task-e5f6/    # Worker 3\n    └── task-g7h8/    # Worker 4\n```\n\nChanges are committed per-task and merged back to main upon completion.\n\n## Examples\n\n### Complete a Full Project\n\n```bash\n# You have a project with existing tasks\ndrover init\ndrover run\n\n# Drover discovers all tasks, builds dependency graph,\n# and drives everything to completion\n```\n\n### Parallel Feature Development\n\n```bash\n# Create an epic for a new feature\ndrover epic add \"User Dashboard\"\n\n# Add independent tasks (can run in parallel)\ndrover add \"Dashboard layout component\" --epic epic-dash\ndrover add \"Fetch user stats API\" --epic epic-dash\ndrover add \"User preferences storage\" --epic epic-dash\n\n# Add dependent tasks\ndrover add \"Wire up dashboard to API\" --epic epic-dash \\\n  --blocked-by task-layout,task-api\n\ndrover add \"Add dashboard tests\" --epic epic-dash \\\n  --blocked-by task-wire\n\n# Run with high parallelism\ndrover run --workers 8 --epic epic-dash\n```\n\n### Resume After Interruption\n\n```bash\n# Running a long job...\ndrover run --workers 4\n# ^C (interrupted) or crash\n\n# Later, resume exactly where you left off\ndrover resume\n# All workflows continue from last checkpoint\n```\n\n## Architecture\n\nDrover is built on a pure Go stack:\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| CLI | Cobra | Command-line interface |\n| Workflows | DBOS Go | Durable execution |\n| Database | PostgreSQL/SQLite | State persistence |\n| Agent Interface | Pluggable | Support for Claude, Codex, Amp |\n| AI Agents | Claude/Codex/Amp | Task execution |\n| Isolation | Git Worktrees | Parallel workspaces |\n| Observability | OpenTelemetry | Traces \u0026 metrics |\n\n**Documentation:**\n- [Documentation Index](./docs/index.md) - Complete documentation hub\n- [Design Docs](./design/DESIGN.md) - Detailed architecture documentation\n- [Spec Directory](./spec/) - Feature specifications\n- [Contributing](./CONTRIBUTING.md) - Contribution guidelines\n\n## Comparison\n\n| Feature | Drover | Manual Claude | Cursor Background |\n|---------|--------|---------------|-------------------|\n| Parallel agents | ✅ 1-16+ | ❌ 1 | ✅ Limited |\n| Crash recovery | ✅ Full | ❌ None | ❌ None |\n| Dependency graph | ✅ Yes | ❌ Manual | ❌ No |\n| Auto-retry | ✅ Yes | ❌ No | ❌ No |\n| Progress tracking | ✅ Real-time | ❌ Manual | ⚠️ Basic |\n| Git isolation | ✅ Worktrees | ❌ No | ❌ No |\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.\n\n```bash\n# Run tests\ngo test ./...\n\n# Run with race detector\ngo test -race ./...\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE)\n\n## Acknowledgments\n\nDrover stands on the shoulders of giants. We're grateful to:\n\n- **[DBOS](https://dbos.dev/)** — The durable workflow engine that powers Drover's crash recovery and exactly-once execution. The [DBOS Go SDK](https://github.com/dbos-inc/dbos-transact-golang) makes durable workflows accessible in Go.\n\n- **[Beads](https://github.com/beads-dev/beads)** — Inspired the hierarchical task ID format (`task-123.1`, `task-123.1.2`). Beads' approach to breaking down complex work into manageable pieces heavily influenced Drover's sub-task system.\n\n- **[Geoffrey Huntley](https://github.com/gdhuntley)** — The \"Ralph Wiggum\" concept (using AI agents to handle repetitive, well-defined tasks) inspired Drover's core philosophy: let agents handle the routine work while humans provide direction.\n\n- **[Anthropic](https://www.anthropic.com/)** — Claude Code is the AI agent that powers Drover's task execution. Thanks for building an incredible AI coding assistant.\n\n- **[Cloud Shuttle](https://cloudshuttle.com.au)** — Built and maintains Drover.\n\n---\n\nBuilt by [Cloud Shuttle](https://cloudshuttle.com.au) 🚀\n\n*Drover keeps your tasks moving until they reach their destination: done.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-shuttle%2Fdrover","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-shuttle%2Fdrover","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-shuttle%2Fdrover/lists"}