vibesolve CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Working conventions

• Never commit without explicit user approval. Always show the proposed commit(s) and wait for the user to say "go ahead" before running git commit. See also AGENTS.md — a guide for AI coding agents covering the same pipeline plus generated-project conventions and debugging shortcuts; keep the two in sync when architecture changes.

Overview

Multi-agent system that generates complete Timefold Solver projects from natural language problem descriptions. Uses OpenAI API with a sequential pipeline (up to 9 agents) where each agent specializes in one aspect of code generation. Generated projects are validated via Docker (Maven compile + execution) and automatically fixed by a feedback loop. An optional interactive user-validation step lets users review and correct the parsed problem spec before code generation begins.

Setup

# Create the environment and install the package (do this once, or after adding dependencies)
uv sync --extra dev

# Activate it — once per shell; puts `vibesolve` and `pytest` on PATH
source .venv/bin/activate

# Configure API key
# Create .env.local with OPENAI_API_KEY=your-key

# Build the Docker validator image (first run only)
docker build -t timefold-validator docker/

Important: This project requires Python 3.11+ for modern type annotations. All commands below assume the venv is activated. In a shell where it isn't, prefix the command with uv run (e.g. uv run vibesolve run) — uv picks the project environment automatically.

Running the Pipeline

# Single problem (default: user_input/timetable.txt)
vibesolve run

# Specific input file
vibesolve run user_input/hospital-rostering.txt

# Skip the Docker validation/fixer loop
vibesolve run --no-validation-loop

# Pause after parsing to review and correct the problem spec before code generation
vibesolve run --user-validate

# Custom reasoning effort and fixer iterations
vibesolve run --reasoning-effort medium --max-iterations 5

# Emit a Dockerfile + docker-run.sh into the generated project
# (only happens on success; the script is NOT started automatically)
vibesolve run --serve

# Parallel batch across all *.txt in user_input/
vibesolve batch

# Batch with more workers
vibesolve batch --workers 5

# Batch + emit Dockerfiles so the benchmark can also measure "Docker works"
vibesolve batch --serve