{"id":46510442,"url":"https://github.com/simion/reviewd","last_synced_at":"2026-03-10T20:01:57.114Z","repository":{"id":341931999,"uuid":"1172050430","full_name":"simion/reviewd","owner":"simion","description":"The review daemon — local AI code reviewer for GitHub and BitBucket pull requests, powered by Claude Code / Gemini CLI subscriptions.","archived":false,"fork":false,"pushed_at":"2026-03-06T16:21:50.000Z","size":182,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T17:56:29.600Z","etag":null,"topics":["ai-code-review","ai-project","bitbucket","claude-code","code-review","code-review-automation","gemini-cli","github-pull-request","pr-review"],"latest_commit_sha":null,"homepage":"","language":"Python","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/simion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-03-03T22:27:41.000Z","updated_at":"2026-03-06T16:21:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simion/reviewd","commit_stats":null,"previous_names":["simion/nea-claudiu","simion/reviewd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/simion/reviewd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simion%2Freviewd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simion%2Freviewd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simion%2Freviewd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simion%2Freviewd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simion","download_url":"https://codeload.github.com/simion/reviewd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simion%2Freviewd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30222338,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T14:02:48.375Z","status":"ssl_error","status_checked_at":"2026-03-07T14:02:43.192Z","response_time":53,"last_error":"SSL_read: 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-code-review","ai-project","bitbucket","claude-code","code-review","code-review-automation","gemini-cli","github-pull-request","pr-review"],"created_at":"2026-03-06T16:05:12.294Z","updated_at":"2026-03-07T17:00:38.452Z","avatar_url":"https://github.com/simion.png","language":"Python","readme":"# reviewd\n\n[![PyPI](https://img.shields.io/pypi/v/reviewd)](https://pypi.org/project/reviewd/)\n[![Python 3.12+](https://img.shields.io/pypi/pyversions/reviewd)](https://pypi.org/project/reviewd/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![CI](https://github.com/simion/reviewd/actions/workflows/ci.yml/badge.svg)](https://github.com/simion/reviewd/actions/workflows/ci.yml)\n\n**The review daemon** — local AI code reviewer for GitHub and BitBucket pull requests, powered by Claude Code / Gemini CLI subscriptions.\n\n- Watches your repos for new PRs, reviews them using Claude or Gemini CLI, and posts structured comments\n- All from your machine — no CI pipeline, no cloud service, no new accounts\n- Secure by default — can only access repos you already have locally, as secure as your machine\n\n\u003e If you already have `claude` or `gemini` CLI and local git clones, you're 5 minutes away from automated code reviews.\n\n## Features\n\n- **Reuses what you already have** — your local git repos, your Claude/Gemini CLI subscription, your existing credentials. Nothing new to install or pay for.\n- **Full codebase context** — reviews run on your actual local repos, not shallow CI clones. The AI can read any file, follow imports, and understand the full picture.\n- **Fast via git worktrees** — isolated checkouts that share `.git`. No re-cloning. Reviews start in milliseconds.\n- **Runs real commands** — configure linters, type checkers, and test suites to run during review. Failures are included in the AI's analysis.\n- **Structured output** — severity-tagged findings with inline comments on specific lines and a summary comment.\n- **Daemon or one-shot** — background polling across all repos, or single PR reviews on demand. Dry-run mode to preview.\n- **Multi-repo, multi-AI** — different repos can use different AI backends, models, and review instructions.\n- **Smart re-reviews** — new commits on a PR trigger a fresh review; old comments are deleted automatically.\n- **Draft-aware** — skips draft PRs by default. Add `[review]`, `[claudiu]`, `[ask]`, or `[bot review]` to the title to request a review anyway.\n- **Auto-approve** — automatically approves PRs that pass configurable gates (diff size, severity, finding count) and AI-evaluated rules. Shows approval rationale in the summary comment.\n- **Critical tasks** — optionally creates a BitBucket PR task on critical findings to block merge.\n- **Spam protection** — configurable diff size thresholds, cooldowns, and title/author skip patterns.\n- **Auto-sync config** — automatically pulls `.reviewd.yaml` from remote when the working copy is clean.\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install reviewd\n```\n\nOr with [`uv`](https://docs.astral.sh/uv/):\n\n```bash\nuv tool install reviewd\n```\n\nRequires Python 3.12+. You also need `claude` or `gemini` CLI installed and authenticated.\n\n### 2. Configure\n\n```bash\nreviewd init   # set up global config + per-project .reviewd.yaml\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGitHub setup\u003c/b\u003e\u003c/summary\u003e\n\n1. Create a [Personal Access Token](https://github.com/settings/tokens) with the **`repo`** scope.\n2. Export it: `export GITHUB_TOKEN=ghp_...`\n3. Config:\n\n```yaml\ngithub:\n  token: ${GITHUB_TOKEN}\n\nrepos:\n  - name: my-repo\n    repo_slug: owner/my-repo\n    path: ~/repos/my-repo\n    provider: github\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBitBucket setup\u003c/b\u003e\u003c/summary\u003e\n\n1. Create an [App Password](https://bitbucket.org/account/settings/app-passwords/) with **Pull requests: Read** and **Write**.\n2. Export it: `export BB_AUTH_TOKEN=ATCTT3x...`\n3. Config:\n\n```yaml\nbitbucket:\n  your-workspace: ${BB_AUTH_TOKEN}\n\nrepos:\n  - name: my-project\n    path: ~/repos/my-project\n    provider: bitbucket\n    workspace: your-workspace\n```\n\n\u003c/details\u003e\n\nBoth providers can be used in the same config.\n\n### 3. Review\n\n```bash\nreviewd pr my-project 42           # one-shot\nreviewd pr my-project 42 --dry-run # preview\nreviewd watch -v                   # daemon mode\n```\n\n## How It Works\n\n```\nPoll API → Check State (SQLite) → Fetch \u0026 Worktree → AI Review (Claude/Gemini) → Parse JSON → Post Comments → Cleanup\n```\n\n1. Fetches open PRs from GitHub/BitBucket\n2. Skips already-reviewed commits, drafts, cooldowns, and small diffs\n3. Creates a git worktree, runs configured test commands\n4. Invokes the AI CLI with a structured prompt and JSON output schema\n5. Posts inline comments + summary comment, tracks state in SQLite\n\n## Configuration\n\n### Global (`~/.config/reviewd/config.yaml`)\n\n```yaml\npoll_interval_seconds: 60\n\ngithub:\n  token: ${GITHUB_TOKEN}\n\nbitbucket:\n  your-workspace: ${BB_AUTH_TOKEN}\n  other-workspace: ${OTHER_BB_TOKEN}\n\ncli: claude                    # or \"gemini\"\n# model: claude-sonnet-4-5-20250514\n\n# review_title: \"Code Review by Nea' ~~Caisă~~ Claudiu\"\n# footer: \"Automated review by ...\"\n# skip_title_patterns: ['[no-review]', '[wip]', '[no-claudiu]']\n# skip_authors: []\n\ninstructions: |\n  Be concise and constructive.\n  Every issue must include a concrete suggested fix.\n\nrepos:\n  - name: gh-backend\n    repo_slug: owner/gh-backend\n    path: ~/repos/gh-backend\n    provider: github\n\n  - name: bb-frontend\n    path: ~/repos/bb-frontend\n    provider: bitbucket\n    workspace: your-workspace\n    cli: gemini\n    model: gemini-2.5-pro\n```\n\n### Per-project (`.reviewd.yaml` in repo root)\n\n```yaml\ninstructions: |\n  Python 3.12+, Django 5.x.\n  Check for missing select_related/prefetch_related.\n\ntest_commands:\n  - uv run ruff check .\n  - uv run pytest tests/ -x -q\n\nskip_severities: [nitpick]       # options: critical, suggestion, nitpick, good\ninline_comments_for: [critical]  # rest goes in summary\n# max_inline_comments: 5         # skip all inline if exceeded\n# min_diff_lines: 0              # initial review threshold (0 = disabled)\n# min_diff_lines_update: 5       # re-review threshold for pushed commits\n# review_cooldown_minutes: 30\n# critical_task: true            # create PR task on critical findings (BitBucket)\n```\n\n### Auto-Approve\n\nreviewd can automatically approve PRs that pass all configured gates. The AI is asked to evaluate the PR against your rules and provide an approval reason, which is shown in the summary comment.\n\n```yaml\n# in .reviewd.yaml\nauto_approve:\n  enabled: true\n  max_diff_lines: 50        # block approval if diff exceeds this\n  max_severity: nitpick     # highest allowed severity (good \u003c nitpick \u003c suggestion \u003c critical)\n  max_findings: 3           # block if more findings than this (excludes \"good\" findings)\n  rules: |                  # custom rules sent to the AI for the approval decision\n    Only approve safe, simple changes:\n    - Minor refactors, renames, typo fixes\n    - Small bug fixes with obvious correctness\n    - Config/settings tweaks, dependency bumps\n    Never approve changes with migrations or complex business logic.\n```\n\n**How it works:**\n\n1. The AI reviews the PR normally, producing findings\n2. The AI evaluates your `rules` and sets `approve: true/false` with a reason\n3. reviewd checks the gates: `max_diff_lines`, `max_severity`, `max_findings`\n4. If all gates pass **and** the AI approved, the PR is approved via the provider API\n5. The approval reason is included in the summary comment\n\nAll gates must pass — if any one blocks, the PR is not approved. The `rules` field is sent verbatim to the AI as part of the review prompt, so write it as instructions.\n\n`auto_approve` can also be set in the global config and will be inherited by all repos. Per-project settings override global ones.\n\n## CLI Reference\n\n```bash\nreviewd init                                  # set up global + project config\nreviewd ls                                    # list repos and open PRs\nreviewd watch -v                              # daemon mode\nreviewd watch -v --dry-run                    # preview, no posting\nreviewd watch -v --review-existing            # review not-yet-reviewed open PRs\nreviewd pr \u003crepo\u003e \u003cid\u003e                        # one-shot review\nreviewd pr \u003crepo\u003e \u003cid\u003e --force                # re-review (bypasses draft/skip)\nreviewd status \u003crepo\u003e                         # review history\n```\n\n## Architecture\n\n- **Polling, not webhooks** — no tunnel or public endpoint needed\n- **Git worktrees** — near-instant isolated checkouts\n- **Full AI tool access** — the AI reads files, runs commands, explores code\n- **JSON schema** — structured findings, the tool just parses and posts\n- **SQLite state** — tracks `(repo, pr_id, commit)` to avoid duplicates\n- **Provider abstraction** — GitHub and BitBucket, extensible\n\n## Security\n\n\u003e reviewd gives the AI CLI full tool access in git worktrees on your machine. Only watch repos where you trust the contributors.\n\n**Claude CLI (recommended)** is the more secure option. It runs with:\n- `--print` mode — read-only, no tool use, no code execution. The AI only sees the prompt and returns text.\n- `--disallowedTools Write,Edit` — explicitly blocks file modification tools as an extra layer\n- `--mcp-config '{\"mcpServers\":{}}' --strict-mcp-config` — disables all MCP servers, preventing external tool access\n- `CLAUDECODE` env var is unset — prevents nested Claude Code sessions\n\n**Gemini CLI** runs with `--approval-mode yolo` because it has no equivalent print-only mode. This means Gemini can execute commands and modify files in the worktree during review. Mitigated by:\n- `-e none` — disables all extensions (no web access, no file tools beyond built-in)\n- But it's inherently less sandboxed than Claude's `--print`\n\n**General mitigations (both CLIs):**\n- Reviews run in isolated git worktrees, not your working copy\n- The prompt includes a security scope block forbidding file writes, network access, and secret access\n- Per-project config (`.reviewd.yaml`) is read from the main repo, not the worktree — PR authors can't inject instructions\n- `test_commands` come only from the repo owner's config, not from PR content\n\n## Roadmap\n\n- [ ] Parallel PR review queue — currently PRs are reviewed sequentially, which is fine for most teams since each review takes 1-3 minutes and the poll loop catches up quickly\n- [ ] GitLab support\n\n## Disclaimer\n\n\u003e Built entirely with AI-assisted development (Claude Code), with thorough human review and guidance at every step. Because we have production code to ship and no time to hand-craft internal tooling.\n\u003e\n\u003e Why is that fine? It's a read-only tool that posts PR comments. The worst it can do is post a bad review.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimion%2Freviewd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimion%2Freviewd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimion%2Freviewd/lists"}