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) 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 — see Choose your coding agent.

🔄 How It Works

sequenceDiagram
    actor You
    participant Worker as 🤖 VibeCoder Worker
    participant Agent as 🧠 Coding agent
    participant GitHub as 🐙 GitHub

    You->>GitHub: Create issue (from phone)
    GitHub->>Worker: Detect & self-assign
    Worker->>Worker: Create feature branch
    Worker->>Agent: Work on issue
    Agent->>Worker: Code changes
    Worker->>Worker: Run quality checks
    Worker->>GitHub: Create PR
    GitHub->>You: PR appears for review
    You->>GitHub: Leave feedback (thumbs up)
    GitHub->>Worker: Fix feedback & push
    Worker->>Agent: Apply feedback
    Agent->>Worker: Updated code
    Worker->>GitHub: Updated PR ready
    You->>GitHub: Approve & merge

🔌 Choose your coding agent

The coding agent is a separable layer — every workflow above is the worker's, not the vendor's, so swapping the agent changes which CLI writes the code and nothing else. Four providers are built in:

deepseek is the one row that needs a word of explanation: DeepSeek ships no CLI of its own, so the provider installs Anthropic's CLI under the deepseek command and points it at https://api.deepseek.com/anthropic. Its credential is therefore a DeepSeek key, and Anthropic's own credentials are withheld from it — no vendor's secret reaches another vendor's agent.

One credential file per vendor is the rule, with one optional exception: a host holding several Claude subscriptions may add claude/provider-2.env, provider-3.env and so on by hand, and each run starts on whichever of them has the most budget left, naming its choice in the startup log. Nothing changes for a host with a single credential (Several Claude tokens).

Select one with the agent_provider key in .config.json:

{
  "agent_provider": "codex",
  "agent_providers": ["codex"]
}

Mixed Claude/Codex hosts can opt into quota-aware selection before each work item. Only credentials proved to be fixed-price subscriptions are candidates; API-key and unknown-billing accounts are never selected:

{
  "agent_provider_mode": "auto",
  "agent_provider": "claude",
  "agent_providers": ["claude", "codex"]
}

In auto mode, agent_provider is the preference tie-break. An explicit per-invocation provider remains absolute, and VIBE_AGENT_PROVIDER can pin an enabled provider for that process. If every eligible subscription is exhausted or unavailable, the worker waits instead of falling through to metered usage.

agent_providers lists every provider enabled for a run: each gets its own credential file, its own startup preflight and its own read-only container mount, so no vendor's secret reaches another vendor's agent. It must include the active provider. VIBE_AGENT_PROVIDER and VIBE_AGENT_PROVIDERS (comma-separated) still select a provider on a host whose configuration file names none, but they no longer override the file — the file wins, as it does for every other setting (1.4.0).

An id that is set but not registered fails loudly at startup with the supported ids named — the worker never silently falls back to the default and runs an agent you did not choose.

The default container image installs Claude Code alone, and the launcher builds the image with whatever agent_providers lists — it passes the set as --build-arg AGENT_PROVIDERS and mixes it into the image tag, so a Codex-only host builds and runs a Codex image rather than reusing the default one.

• Container Image — the coding-agent provider layer — how the seam works, what the image installs, and how to add the next provider.
• Configuration Reference — the provider-selection keys in full.
• Setup Guide — provisioning each vendor's credentials.
• Quorum — running several providers at once, so two agents draft a plan and a third judges it.
• Model Selection, Sessions & Caching — provider applicability — which documented model, session and caching behaviours you still get under each provider, and what the others do instead.

✨ 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. The worker responds to feedback and pushes updates.
• Clarification & refinement — If the issue is unclear, the worker asks questions before starting. You can also refine issues collaboratively.
• 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. The worker reads the issue and comments, posts an answer, removes the question label, and adds needs-human to signal it is your turn. Add question again to ask a follow-up.
• Spelling auto-fix — Failed spelling checks on PRs are automatically corrected.
• CI failure auto-fix — Failed CI (Continuous Integration) or integration checks on open PRs are automatically diagnosed and fixed.
• Idle-task framework — When no claimable work exists, the worker files a lowest-priority idle-task issue and runs one of the registered background templates (security, best-practices, test-audit, dependency, and documentation scans, among others), picked at random. See docs/IDLE-TASK-FRAMEWORK.md for the full catalogue.
• Security scans — When the worker has no claimable work, it idle-runs a four-phase security scan against the least-recently-scanned monitored repo and files findings as security-labelled issues. See docs/SECURITY-SCAN.md for the operator manual.
• Priority-based work queue — PR feedback first, then spelling fixes, CI failure remediation, branch updates, auto-merge, branch cleanup, issue closure, milestone completion (with tracking issue), issue refinement, question answering, planning, then new issues (globally oldest across repos).
• Cost optimisation — Phase-based model selection (Opus 5.5 for complex work, with effort as the main lever; Haiku for routine tasks — see Model, Caching & Batching for the full routing rationale), SHA-based prompt compilation cache, prompt structure optimisation for Claude prompt caching, and per-issue token usage tracking. (The Anthropic Batch API was evaluated but deliberately not wired in — its async turnaround is incompatible with the worker's bounded interactive run; see Model, Caching & Batching.)
• Post-run callbacks — Optional success / failure / always executables run after a terminal issue run, plus an optional cycle heartbeat at the end of every scan loop and an optional host_failure hook the host launcher runs while a host-level failure persists, following the success / failure / always outcome semantics familiar from CI pipelines. The public extension point for fleet-specific reporting; a hook failure never rewrites the run's own result. The contract — ordering, the versioned context, the security boundary, portable examples and a conformance fixture an extension can run against its own hooks — is Post-Run Callbacks.
• Per-repo configuration — Operator-side repo_config in .config.json customises worker behaviour per repository (e.g., skip screenshots for CLI-only projects). Configuration is operator-side only — target repos carry no worker configuration.
• Milestone enhancements — Progress notifications, configurable issue ordering within milestones, periodic branch sync with the default branch, automatic roll-back of a stuck milestone branch (reverted children are reopened and re-queued; a roll-back with nothing left escalates once), with a rebuild from the base tip first once a roll-back has already been spent on the branch (Issue #4328), and milestone health diagnostics.
• Self-healing — Shadow-copy execution, automatic repo resets, disk cleanup, failure recovery, rate-limit handling, and crash resilience keep the worker running unattended. See Resilience & Concurrency for the full behaviour.
• Safe by default — Only processes issues from allowed authors with configured labels.
• Extendable — Add new functionality via Deno/TypeScript commands without modifying shell scripts.

🛡️ Quality and control (for managers and tech leads)

The Vibe Coder is a fast, capable assistant — but nothing goes to the default branch (prod) without your review. No rogue merges, no surprises. Same as for human developers: every change arrives as a PR; you review, request fixes, and approve before merge. The "loss of control" worry is addressed by design: the worker never bypasses your gates.

flowchart LR
  subgraph worker ["🤖 Worker"]
    W1["TDD, KISS, DRY"]
    W2["Opens PR"]
    W3["Runs quality.sh"]
    W1 --> W2 --> W3
  end
  subgraph gate ["🛡️ Your gate"]
    R["Review & approve"]
  end
  subgraph result ["✅ Result"]
    D[(Default / prod)]
  end
  worker --> R --> D
  style gate fill:#2d6a4f,stroke:#1b4332,color:#fff
  style result fill:#40916c,stroke:#2d6a4f,color:#fff

Productivity with quality: The worker is told to follow TDD (Test-Driven Development), KISS (Keep It Simple), DRY (Don't Repeat Yourself), and the rest of the playbook — and every PR runs the full quality gate (./quality.sh: deno test, deno lint, deno check, deno fmt --check, and semgrep over the changed files). Have your cake and eat it too: more throughput, same (or better) gates. Full coding standards: Coding Standards.

Note for team leads and managers: The productivity gains are real, but you are now deploying code that you didn’t write and may not fully understand. That’s why the review gate exists: treat every PR as code you’re taking ownership of. Review, ask for changes, and only merge when you’re comfortable maintaining what lands on the default branch.

🏁 Quick Start

macOS / Linux

# Clone the repository
gh repo clone <your-org>/VibeCoder
cd VibeCoder

# Configure via environment variables (when run in a terminal, setup may optionally prompt for service-account paths)
VIBE_ALLOWED_AUTHOR=myusername \
VIBE_REPOS="myorg/repo1,myorg/repo2" \
./setup.sh

# Start the worker
./run.sh

# Move this host onto the newest release (setup pins a new host to a release;
# a frozen host logs a WARNING at each launch when a newer one exists). Rewrites
# the pins in .config.json and nothing else — the next launch installs exactly them.
./run.sh upgrade

See Configuration — The upgrade loop for the notice, what the command changes, and the hand-edited pin.

Windows (PowerShell)

# Clone the repository
gh repo clone <your-org>/VibeCoder
cd VibeCoder

# Configure (same environment variables)
$env:VIBE_ALLOWED_AUTHOR = "myusername"
$env:VIBE_REPOS = "myorg/repo1,myorg/repo2"
.\setup.ps1  # PowerShell only — no bash, WSL or Git Bash needed

# Start the worker
.\run.ps1

setup.ps1 is the twin of setup.sh: it delegates every platform-neutral step to the same Deno setup CLI and adds only the interactive layer — the prompts, the credential flow (gh identity copy plus claude setup-token, each proven with a live call), and the offer to register the Task Scheduler entry that replaces the macOS LaunchAgent. Missing host tools are offered one at a time via winget. A parity test compares the two scripts, so neither can quietly drop a setup step the other keeps.

That is the whole deployment story: git clone → configure credentials and repos → ./run.sh (or run.ps1). From then on the machine operates unattended — it self-heals, rebuilds its container when the definition changes, and is steered entirely through GitHub.

📡 An unattended appliance, controlled through GitHub

A Vibe Coder host is an appliance, not a workstation. The worker runs inside a least-privilege container that sees four explicit host mounts, two named volumes, and no other host data (Containment). The trade is deliberately asymmetric — generous resources, strict boundary: inside the container the worker gets all the memory, CPU and disk the host can give (it is sized to the host, not rationed), while the boundary around it is absolute (see Design Principles). GitHub is the sole normal remote control plane: issues, comments, labels, repositories, commits and pull requests. Humans steer the worker by labelling and commenting; the worker reports progress, escalations and crashes the same way.

SSH, Remote Desktop, screen sharing, a management UI and terminal access to the host are not required for normal operation. No inbound port is opened. Local logs (the host log directory) remain useful for diagnosis, and a failure inside a run is still reported through GitHub. A host-level failure — the launcher crash-looping, the checkout update failing run after run — happens before any issue is claimed, so it is reported through the deployment's own callbacks.host_failure hook, or, when none is configured, to the host log and the self-heal events. It is never filed as an issue on a public repository.

For production, run via cron (macOS/Linux) or Task Scheduler (Windows) every 5 minutes:

# Linux (cron) — on macOS use ~/Library/Logs/vibe-coder/cron.log
*/5 * * * * /path/to/VibeCoder/run.sh >> ~/.local/state/vibe-coder/cron.log 2>&1

See the Deployment Guide for systemd, launchd, Task Scheduler, and other options.

🏗️ 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.

run.sh and run.ps1 launch the worker inside the container image: both ask the same Deno container-launch-plan command what to run, so the mounts and privilege flags are identical on every host. Containment is mandatory (Issue #4): container is the only run mode — the former native and macOS seatbelt opt-ins were removed, a run_mode (or VIBE_RUN_MODE) that still names one fails loud with the removal explained, and a missing container runtime is a loud failure with no host fallback. See Container Image for the mount set and privilege flags, Containment for the boundary, and Configuration for the setting.

graph TD
    A["📦 run.sh / run.ps1 — Thin launcher (cron/launchd/Task Scheduler)"]
    C["🐳 vibe-coder container — least-privilege mounts, no host access"]
    B["🚀 Deno run-entrypoint — Worker driver (PID guard → bootstrap → housekeeping → loop)"]
    D["🦕 worker/deno/ — All business logic (commands, libraries, tests)"]

    A -->|run container| C -->|exec deno| B --> D

    style A fill:#2d6a4f,stroke:#1b4332,color:#d8f3dc
    style C fill:#1b4332,stroke:#081c15,color:#d8f3dc
    style B fill:#40916c,stroke:#2d6a4f,color:#d8f3dc
    style D fill:#74c69d,stroke:#52b788,color:#081c15

The thin launcher execs Deno directly on the run-entrypoint command — there is no bash on the runtime path, so the worker runs natively on Windows . Because Deno loads its modules at process start, the running driver is immune to any mid-run change to the checkout — the same property the old worker/.run_core.sh shadow-copy provided.

Resilience features: The worker is built to run unattended — a host-side update of the checkout to the default branch before each launch (with the driver immune to it), shallow clones with on-demand history deepening, repo self-healing and startup sweeps, two-tier disk cleanup, PID locking, time-limited runs, timeout wrappers, rate-limit awareness with model fallback, crash-surviving failure state, and multi-worker coordination. For the full detail see Resilience & Concurrency, Worker Internals, and Lessons learnt.

📋 Requirements

The worker runs inside the container image — container is the default and the only run mode (Issue #4) — so the host needs a container runtime and the launcher, not the worker's toolchain:

• A supported container runtime: Apple container on macOS, Docker or Podman on Linux and Windows. Container mode never falls back to the host — with none available the launcher exits non-zero (there is no host