vibecoder

# VibeCoder **Create GitHub issues from your phone, get PRs (Pull Requests) automatically, review and request fixes with a thumbs up.** VibeCoder is an automated GitHub issue worker driven by a coding-agent CLI. It monitors your repositories, picks up issues, writes code, runs quality checks, and opens pull requests — all without you touching a keyboard. It is **provider agnostic**: `claude` ([Claude Code](https://docs.anthropic.com/en/docs/claude-code)) is the default, and `codex` (the OpenAI Codex CLI), `gemini` (the Gemini CLI) and `deepseek` (DeepSeek, served through the Claude Code CLI) are built in and chosen by configuration. ## How It Works 1. You create an issue on GitHub (e.g., from your phone). 2. The VibeCoder Worker detects and self-assigns the issue. 3. The worker creates a feature branch and delegates the work to the configured Coding Agent. 4. The agent writes code changes. 5. The worker runs quality checks (linting, testing, formatting). 6. If checks pass, the worker opens a Pull Request on GitHub. 7. You review the PR, leave comments, or give a thumbs-up to trigger fixes. 8. The worker applies feedback and pushes updates. 9. You approve and merge the PR. ## Choose your coding agent The coding agent is a separable layer. Four providers are built in: | Provider id | Agent | Credential file | | --- | --- | --- | | `claude` (default) | Claude Code | `claude/provider.env` | | `codex` | Codex CLI | `codex/provider.env` | | `gemini` | Gemini CLI | `gemini/provider.env` | | `deepseek` | DeepSeek (via Claude Code CLI) | `deepseek/provider.env` | Select one with the `agent_provider` key in `.config.json`. Mixed hosts can opt into quota-aware selection. ## Key Features - **Issue-to-PR pipeline**: Write an issue, get a PR. The worker handles branching, coding, testing, and PR creation. - **Review feedback loop**: Leave comments on the PR, thumbs-up to trigger fixes. - **Clarification & refinement**: If the issue is unclear, the worker asks questions before starting. - **Planning mode**: Add the `planning` label to get task breakdowns and sub-issues instead of direct implementation. - **Question answering**: Add the `question` label to get answers about the codebase without implementation. - **Spelling auto-fix**: Failed spelling checks on PRs are automatically corrected. - **CI failure auto-fix**: Failed CI checks on open PRs are automatically diagnosed and fixed. - **Idle-task framework**: When no claimable work exists, the worker files low-priority idle tasks (security, best-practices, etc.). - **Security scans**: Idle-runs security scans against monitored repos. - **Priority-based work queue**: Prioritizes PR feedback, then spelling fixes, CI remediation, etc. - **Cost optimisation**: Phase-based model selection, prompt caching, and token usage tracking. - **Post-run callbacks**: Optional executables run after successful/failed runs. - **Per-repo configuration**: Customize worker behavior per repository. - **Milestone enhancements**: Progress notifications, automatic roll-back of stuck branches. - **Self-healing**: Shadow-copy execution, automatic repo resets, disk cleanup, crash resilience. - **Safe by default**: Only processes issues from allowed authors with configured labels. - **Extendable**: Add new functionality via Deno/TypeScript commands. ## Quality and control Nothing goes to the default branch (prod) without your review. Every change arrives as a PR; you review, request fixes, and approve before merge. The worker follows TDD, KISS, DRY, and runs full quality gates (`deno test`, `deno lint`, `deno check`, `deno fmt --check`, and semgrep). ## Quick Start ### macOS / Linux ```bash # Clone the repository gh repo clone <your-org>/VibeCoder cd VibeCoder # Configure via environment variables VIBE_ALLOWED_AUTHOR=myusername \ VIBE_REPOS="myorg/repo1,myorg/repo2" \ ./setup.sh # Start the worker ./run.sh ``` ### Windows (PowerShell) ```powershell # Clone the repository gh repo clone <your-org>/VibeCoder cd VibeCoder # Configure $env:VIBE_ALLOWED_AUTHOR = "myusername" $env:VIBE_REPOS = "myorg/repo1,myorg/repo2" .\setup.ps1 # Start the worker .\run.ps1 ``` ## Architecture The worker uses a thin launcher + Deno TypeScript architecture. Entry points are minimal shell/PowerShell scripts that delegate to Deno for all business logic. Cross-platform: macOS, Linux, and Windows. The worker runs inside a least-privilege container. Containment is mandatory. GitHub is the sole normal remote control plane. ## Requirements - A supported container runtime: Apple `container` on macOS, Docker or Podman on Linux and Windows. - [Deno](https://deno.com/) 2+ — the launcher's only host tool. - `bash` (macOS/Linux) or PowerShell (Windows) to run the launcher. - For setup only: Git and an authenticated GitHub CLI. ## Documentation - [Overview](docs/OVERVIEW.md): Single-page walkthrough. - [Label Flows](docs/workflows/label-flows.md): Which label when. - [Usage Guide](docs/USAGE.md): Creating issues, PR workflow. - [Workflows Overview](docs/workflows/README.md): User manual for repo owners. - [Quorum](docs/QUORUM.md): Running several providers at once.