vibe-racer

vibe-racer is built with vibe-racer. Every feature in this repo is planned, designed, and executed through the same pipeline you're reading about.

Your AI race engineer. Seven laps from objective to shipped code — you call the pit stops.

📚 Documentation  ·  🧑‍💻 GitHub

What is vibe-racer?

Your project is the car. Every pipeline stage is a lap. Every human checkpoint is a pit stop. vibe-racer is the race engineer in your ear — it does the heavy work, calls the strategy, and hands you the final say on every decision.

The AI agent pre-fills its recommended answers to every question. You only edit what you disagree with.

Get Started

Prerequisites

• Node.js 20+
• Anthropic API key (set ANTHROPIC_API_KEY env var, or run claude login)

Install

npm install -g vibe-racer

Quick start

# 1. Initialize in your project
cd your-project
vibe-racer init

# 2. Create a task
vibe-racer new "Add user authentication"

# 3. Write your objective in plans/0001_add-user-authentication/00_objective.md
#    Then tick the checkbox: - [x] Ready to advance to Objective Review

# 4. Drive the first lap
vibe-racer drive

The race engineer picks up the task, generates product questions pre-filled with its recommended answers, and commits them. Review the answers, edit only what you disagree with, tick the checkbox, and run vibe-racer drive again. Repeat through all seven laps.

The Seven Laps

Each task races through 7 laps, producing 7 documents:

Lap 1          Lap 2          Lap 3         Lap 4        Lap 5
Objective  ->  Product    ->  Design    ->  Plan     ->  Execute
    |              |              |             |            |
  pit stop       pit stop       pit stop     pit stop       |
                                                            v
                                                   Lap 6        Lap 7
                                                   QA       ->  Decision
                                                    |              |
                                                  pit stop      finish line

Small tasks can be flagged as trivial during objective review, skipping product and design laps.

Commands

How It Works

• State management: Pipeline state is tracked via state.yml files in each task's plan folder
• Pit stops: The human signals readiness by ticking - [x] Ready to advance to ... at the bottom of each document
• Radio calls: If the race engineer needs more info, it appends follow-up questions and unchecks the checkbox
• Git-native: Branches are created per task, commits happen after each lap. No push — you control merging
• Pre-filled answers: The race engineer recommends answers to every question. You review and edit only disagreements

Configuration

.vibe-racer.yml (created by vibe-racer init):

repo: "https://github.com/owner/repo"  # optional - enables share links
plans_dir: "plans"                       # default
context:                                 # files loaded into Claude's context
  - README.md
  - CLAUDE.md
skills:                                  # optional - per-lap skill overrides
  qa: ["security-review"]
  execute: ["simplify"]

Security

vibe-racer runs Claude sessions with autonomous permissions but enforces a multi-layered security system:

• Path containment — file operations restricted to the project directory and /tmp
• Sensitive path blocklist — ~/.ssh, ~/.aws, etc. are always denied
• Bash filtering — 19 dangerous commands blocked, with interpreter-aware network detection
• Pre-commit secret scanning — blocks commits containing API keys, private keys, or credentials
• Audit log — all guard denials logged to .vibe-racer/audit.log

For sensitive workloads, run inside Docker with --network none. See Security for the full assessment.

Documentation

Full documentation available at the vibe-racer docs site.

Environment Variables

Attribution

Built on Claude Code SDK by Anthropic.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

If vibe-racer helps your crew get to the finish line, give us a ⭐ on GitHub!