vibe-coding

vibe-setup

Bootstrap a consistent AI agent environment in any project. Run once to generate config files for Claude Code, Cursor, and Codex — built around your project context.

Usage

npx vibe-setup

Prompts you to select which tools to configure. Or use flags:

npx vibe-setup --all              # set up everything
npx vibe-setup --claude           # Claude Code only
npx vibe-setup --cursor           # Cursor only
npx vibe-setup --codex            # Codex only
npx vibe-setup --claude --cursor  # mix and match

Prerequisites

• Node.js 18+
• Claude CLI (for --claude setup)
• API keys set as environment variables (see below)

API Keys

Set the following as environment variables on your machine. The setup script reads them at install time; no .env file is required.

Variable	Where to get it
GITHUB_PERSONAL_ACCESS_TOKEN	github.com/settings/tokens
CONTEXT7_API_KEY	context7.com
TAVILY_API_KEY	tavily.com

macOS/Linux — add to ~/.zshrc or ~/.bashrc:

export GITHUB_PERSONAL_ACCESS_TOKEN=your_token
export CONTEXT7_API_KEY=your_key
export TAVILY_API_KEY=your_key

Windows — set as User Environment Variables (search "Edit environment variables" in Start), or via PowerShell:

[System.Environment]::SetEnvironmentVariable("GITHUB_PERSONAL_ACCESS_TOKEN", "your_token", "User")
[System.Environment]::SetEnvironmentVariable("CONTEXT7_API_KEY", "your_key", "User")
[System.Environment]::SetEnvironmentVariable("TAVILY_API_KEY", "your_key", "User")

A .env file in your project root also works as a fallback, but environment variables take precedence.

What gets generated

Tool	Files
Claude	CLAUDE.md, .vibe/
Cursor	.cursor/mcp.json, .cursor/rules/, .vibe/
Codex	AGENTS.md, .codex/config.json, .vibe/

Re-running is safe — .vibe/project-context.md is never overwritten. All other files are regenerated.

Workflow

New project

1. Run npx vibe-setup
2. Paste the New Project prompt (below) into your AI agent — it will fill in .vibe/project-context.md
3. Re-run npx vibe-setup to regenerate all config files with your project context baked in

Existing project

1. Paste the Existing Project prompt (below) into your AI agent — it will analyze the codebase and write .vibe/project-context.md
2. Run npx vibe-setup

Prompts

Existing Project

I need you to analyze this codebase and populate `.vibe/project-context.md`.
This file drives all AI agent config — be specific and accurate, as it will be
read on every future session.

Work through the following steps in order:

1. **Explore the codebase**
   - Read the directory structure (top-level and key subdirectories)
   - Read package.json, any lockfiles, config files (tsconfig, eslint, etc.)
   - Identify the stack: languages, frameworks, major libraries
   - Understand the architecture: how is the code organized? What are the main layers/modules?
   - Identify any existing conventions: naming patterns, file structure, import style

2. **Write `.vibe/project-context.md`** with the following sections:

   **Project Context**
   - Name: the project name
   - Stack: the actual languages, frameworks, and key libraries in use
   - Architecture: a concise description of the structure — what the major parts are and how they relate

   **Project Architecture & Directory Map**
   List the real folder structure with a one-line description of each key directory's purpose.

   **Anti-Patterns & "Never Do This"**
   Identify 3–7 patterns that would be easy to introduce but would break conventions, cause bugs,
   or violate the architecture (e.g., bypassing an abstraction layer, mixing concerns, hardcoding values).

   **Git & Workflow Standards**
   Check for a CONTRIBUTING.md, existing commit history, or branch naming patterns. Document what
   you find. If nothing exists, propose a sensible default.

   **Definition of Done**
   A checklist an agent must complete before marking any task done — make it specific to this project
   (e.g., "passes existing test suite", "no new TypeScript errors", "changelog updated if applicable").

   **Useful Project Commands**
   The actual commands to run the dev server, build, and test suite.

Start with step 1 before writing anything. Show me the proposed content before writing to disk
so I can approve or adjust.

New Project

I need you to help me define a new project and write `.vibe/project-context.md`.
This file drives all AI agent config — it will be read on every future session.

Here's what I want to build:
[DESCRIBE YOUR PROJECT HERE — what it does, who it's for, any tech preferences or constraints]

Work through the following steps in order: