{"id":48867379,"url":"https://github.com/ianchenx/reeve","last_synced_at":"2026-04-20T15:00:23.097Z","repository":{"id":351270943,"uuid":"1210298759","full_name":"ianchenx/reeve","owner":"ianchenx","description":"Self-hosted coding agent daemon — Linear tickets to PRs via Claude Code or Codex","archived":false,"fork":false,"pushed_at":"2026-04-19T08:54:17.000Z","size":1216,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T14:03:46.095Z","etag":null,"topics":["ai-agent","autonomous-agent","bun","claude-code","codex","coding-agent","developer-tools","git-worktree","linear","pull-request-automation"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/ianchenx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-14T09:21:09.000Z","updated_at":"2026-04-19T08:54:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"442e9d3b-e58d-4b66-954f-27e3fa9711d0","html_url":"https://github.com/ianchenx/reeve","commit_stats":null,"previous_names":["ianchenx/reeve"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/ianchenx/reeve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchenx%2Freeve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchenx%2Freeve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchenx%2Freeve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchenx%2Freeve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ianchenx","download_url":"https://codeload.github.com/ianchenx/reeve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchenx%2Freeve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32052534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agent","autonomous-agent","bun","claude-code","codex","coding-agent","developer-tools","git-worktree","linear","pull-request-automation"],"created_at":"2026-04-15T19:42:48.483Z","updated_at":"2026-04-20T15:00:23.048Z","avatar_url":"https://github.com/ianchenx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/icon-transparent.png\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/icon-light-transparent.png\"\u003e\n    \u003cimg alt=\"Reeve\" src=\"assets/icon-light-transparent.png\" width=\"120\"\u003e\n  \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003cstrong\u003eReeve\u003c/strong\u003e — Write a ticket, get a PR.\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\nWrite a ticket, grab a coffee, work gets done.\n\n**Your machine · Your keys · Your agent**\n\nEnglish | [中文](README_CN.md)\n\n[Why Reeve?](#what-is-reeve) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Configuration](#configuration) · [Dashboard](#dashboard)\n\n\u003c/div\u003e\n\n---\n\n## What is Reeve?\n\nAI coding agents can now complete engineering tasks independently. But running them, you only have two choices:\n\n**Watch the terminal until it finishes** — CLI tools are powerful but block your foreground. If it crashes, you restart manually.\n**Hand execution to a cloud service** — no babysitting, but your code runs on someone else's infrastructure, billed per seat, with opaque data flows.\n\nReeve is the third option: **self-hosted unattended execution**. Runs on your machine, your API keys, your choice of agent. Write a ticket, grab a coffee — everything flows automatically in the background.\n\n```\n┌──────────────┐      ┌─────────────┐      ┌──────────────┐      ┌───────────┐\n│ Issue Tracker │ ───▶ │   Reeve     │ ───▶ │  AI Agent    │ ───▶ │ GitHub PR │\n│   (any)       │      │  (daemon)   │      │  (any CLI)   │      │           │\n└──────────────┘      └─────────────┘      └──────────────┘      └───────────┘\n```\n\n\u003e Built-in **Linear** adapter. Task sources plug in via the `Source` interface — connecting other trackers only requires a lightweight adapter.\n\n### Core Design\n\n**Three things are decoupled: where tasks come from, who writes the code, where code runs.** Swap out Linear without touching the agent. Swap the agent without touching the workspace. Each layer evolves independently.\n\n- **Ticket-driven, not prompt-driven**. You don't write prompts — you write tickets in the project management tool you already use. Reeve watches for status changes and turns Todo items into agent tasks.\n\n- **The ticket is the single source of truth**. The agent treats the ticket as its only context source, maintaining a live Workpad in the comments to track execution progress. If the process crashes or the agent restarts, the next run picks up from where it left off.\n\n- **Full execution transparency**. Token usage and run duration for every task, visible in real time. You won't run something unattended that you can't see the bill for.\n\n- **Pluggable task sources**. The kernel never calls any platform API directly — all trackers connect through `Source` adapters. Linear is the first built-in adapter, and the interface is fully open.\n\n### Design Philosophy\n\n**The dumber the orchestration layer, the stronger the system.**\n\nMost orchestration tools try to be smart — decomposing tasks, planning steps, managing complex workflows. Reeve makes the opposite bet: **keep the orchestration layer as thin as possible**, and hand all intelligence to the agent.\n\nThe kernel doesn't understand code, doesn't plan, doesn't decompose problems. It does one thing: connect your issue tracker to an AI agent, provide isolation and lifecycle guardrails, and get out of the way.\n\nAgents will only get better. Today's frontier model is next year's baseline. Thick orchestration layers become liabilities — they cap what the agent can do. A thin layer is an asset — every improvement in agent capability flows through with zero friction. Use Claude Code today, switch to a stronger model tomorrow, zero migration cost.\n\n## Quick Start\n\n### Prerequisites\n\n- macOS or Linux\n- [Bun](https://bun.sh) \u003e= 1.0\n- [gh](https://cli.github.com) CLI (authenticated via `gh auth login`)\n- At least one agent CLI: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://github.com/openai/codex)\n- A [Linear](https://linear.app) account (the only built-in task source for now — more adapters coming)\n\n### 1. Install\n\n```bash\ncurl -fsSL https://reeve.run/install.sh | bash\n```\n\nOr with a package manager:\n\n```bash\nbun install -g reeve-ai\nnpm install -g reeve-ai\n```\n\n### 2. Setup\n\n```bash\nreeve init\n```\n\nThe wizard walks you through: Linear API key → select team → import a repo → choose agent.\n\n\u003e You can also skip `reeve init` and run `reeve run` directly — complete setup through the web dashboard at `http://localhost:14500`.\n\n### 3. Start the daemon\n\n```bash\nreeve start                 # Background daemon\nreeve run                   # Or foreground (Ctrl+C to stop)\n```\n\n### 4. Assign a task like you always do\n\nOpen your Linear project, create an issue describing the change you want, and drag it to **Todo**. Then go grab a coffee.\n\nReeve's scheduling kernel takes over automatically:\n\n1. **Isolate** — Creates an independent git worktree for the task, leaving your main workspace untouched\n2. **Dispatch** — Transforms the ticket into structured context and wakes your configured agent\n3. **Execute** — The agent writes code, runs tests, and commits inside the isolated environment\n4. **Validate** — If review is enabled, triggers a cross-agent code review; failures are sent back for retry\n5. **Deliver** — Pushes a PR, advances the ticket status, and waits for your final approval\n\nReeve delivers PRs, not merges. The merge decision is yours.\n\n### From Source\n\n```bash\ngit clone https://github.com/ianchenx/reeve.git\ncd reeve\nmake install                # Install backend + dashboard deps\nmake dev                    # Backend hot-reload + dashboard dev server\n```\n\n## How It Works\n\nEvery scheduling cycle (default 30 seconds), Reeve runs:\n\n1. **Intake** — Poll the task source for dispatchable issues. New items become tasks.\n2. **Reconcile** — For published tasks, check if the issue is still actionable (e.g. a human requested changes).\n3. **Dispatch** — For queued tasks, create a git worktree, build the prompt, spawn the agent.\n4. **Monitor** — Track agent output, detect stalls, enforce timeouts.\n\n### Task Lifecycle\n\n```\nqueued ──▶ active ──▶ published ──▶ done\n                         │\n                         ▼\n                    done (failed) ──▶ [human moves to Todo] ──▶ revived\n```\n\n`published` = PR created, awaiting human review. If changes are requested during review, Reeve detects this and automatically re-dispatches the agent to address the feedback.\n\n### Reliability \u0026 Recovery\n\n| Failure Scenario | Recovery |\n|---|---|\n| **Validation blocked** | Exponential backoff, agent retried up to `maxRetries` times |\n| **Agent process crashes** | Reads Workpad progress, reuses worktree, resumes from checkpoint |\n| **Task fully failed** | Human moves it back to Todo — code state preserved, budget reset, forced revival |\n| **Daemon crash** | On restart, reconciles local state against remote tracker, lossless recovery |\n\n## Configuration\n\n`~/.reeve/settings.json` — created by `reeve init`:\n\n```json\n{\n  \"linearApiKey\": \"lin_api_...\",\n  \"defaultAgent\": \"claude\",\n  \"projects\": [\n    { \"team\": \"ENG\", \"linear\": \"my-project-slug\", \"repo\": \"myorg/myrepo\" }\n  ],\n  \"workspace\": { \"root\": \"~/reeve-workspaces\" },\n  \"polling\": { \"intervalMs\": 30000 },\n  \"dashboard\": { \"port\": 14500, \"enabled\": true }\n}\n```\n\nPer-project settings are managed via the dashboard or `settings.json`:\n\n```json\n{\n  \"projects\": [\n    {\n      \"team\": \"ENG\",\n      \"linear\": \"my-project-slug\",\n      \"repo\": \"myorg/myrepo\",\n      \"agent\": \"claude\",\n      \"setup\": \"bun install\",\n      \"post\": { \"review\": \"codex\" }\n    }\n  ]\n}\n```\n\n## Skills\n\nAgents learn how to commit, push, and manage ticket state through Skills — here are the built-in defaults, which you can override or extend:\n\n```\nskills/\n├── reeve-commit/SKILL.md   # Well-formed git commits\n├── reeve-push/SKILL.md     # Push branch + create/update PRs\n├── reeve-pull/SKILL.md     # Sync with origin/main, resolve conflicts\n└── reeve-linear/SKILL.md   # Linear GraphQL queries + state management\n```\n\n## Dashboard\n\nThe agent continuously syncs progress to the ticket Workpad, so Reeve runs fully in headless mode.\n\nThe dashboard (`http://localhost:14500`) provides system-level observability:\n\n- **Trace view**: Real-time observation of agent reasoning and tool call flows\n- **Concurrent board**: Overview of all isolated tasks dispatched by the kernel\n- **Cost attribution**: Token consumption per task — decide which tasks are worth automating\n- **Full logs**: When retries or blocks occur, provides far more detail than the Workpad\n\n## CLI Reference\n\n```\nreeve init                  Interactive setup wizard\nreeve start                 Start daemon in background\nreeve run                   Start in foreground (Ctrl+C to stop)\nreeve stop                  Stop daemon\nreeve restart               Stop + start\nreeve status                Task state summary\nreeve tasks                 List active tasks\nreeve log \u003cid\u003e              Session log for a task\nreeve cancel \u003cid\u003e           Cancel a running task\nreeve history               Past task results\nreeve clean [id]            Remove task state + worktree\nreeve doctor                Check environment health\nreeve import \u003corg/repo\u003e     Import a GitHub repo as a project\nreeve edit \u003cslug\u003e           Update project settings\nreeve remove \u003cslug\u003e         Remove a project\n```\n\n## Development\n\n```bash\nmake install            # Install all dependencies\nmake dev                # Backend watch + dashboard dev server\nmake test               # Run all tests\nmake check              # Typecheck + tests\nmake smoke              # Verify npm package in clean Docker\nmake e2e                # End-to-end tests (requires Linear sandbox)\nmake help               # Show all make targets\n```\n\n## What's Next\n\n- [ ] More task source adapters\n- [ ] Custom task source adapter guide\n- [ ] Multi-agent collaboration\n\nStar or Watch this repo to follow progress.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianchenx%2Freeve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianchenx%2Freeve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianchenx%2Freeve/lists"}