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

Lap	Race engineer role	Output
1. Objective review	Product Designer	Product questions
2. Product review	Product Designer	Product spec + design questions
3. Design review	Software Architect	Design spec + plan questions
4. Plan review	Software Engineer	Implementation plan + execution playbook
5. Execute	Software Engineer	Working code, milestone by milestone
6. QA	QA Engineer	QA report
7. Decision	Release Manager	Post-deploy checklist

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

Commands

Command	Description
`vibe-racer init`	Initialize vibe-racer in the current directory
`vibe-racer new <title>`	Create a new task with state.yml + objective template
`vibe-racer pitwall`	View the pit wall — live status for every car in the race
`vibe-racer pitwall --all`	Include completed tasks in pit wall output
`vibe-racer drive`	Drive the next lap — hand the car to the race engineer
`vibe-racer drive --task N`	Drive a specific task
`vibe-racer drive --retry`	Retry tasks in error state
`vibe-racer radio`	Pick up the team radio — open an interactive session with the race engineer at a pit stop
`vibe-racer radio --task N`	Open radio for a specific task
`vibe-racer fasten`	Run dead code analysis and create a cleanup plan
`vibe-racer fasten --force`	Create a new fasten plan even if an active one exists

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

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Claude API key (or `claude login`)

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!