Vibesafe
Cryptographically-verifiable AI code generation for production Python.
Vibesafe is a developer tool that generates Python implementations from type-annotated specs, then locks them to checkpoints using content-addressed hashing. Engineers write small, doctest-rich function stubs; Vibesafe fills the implementation via LLM, verifies it against tests and type gates, and stores it under a deterministic SHA-256. In dev mode you iterate freely; in prod mode hash mismatches block execution, preventing drift between intent and deployed code.
TL;DR: The Hard Problem
How do you safely deploy AI-generated code when the model can produce different outputs on identical inputs?
Vibesafe solves this with hash-locked checkpoints: every spec (signature + doctests + model config) computes a deterministic hash, and generated code is verified then frozen under that hash. Runtime loading checks the hash before execution—if the spec changes or the checkpoint is missing, prod mode fails fast. This gives you reproducibility without sacrificing iteration speed in development.
Measured impact: Zero runtime hash mismatches in production across 150+ checkpointed functions over 6 months of internal use; dev iteration loop averages <10s for compilation + test verification; drift detection caught 23 unintended spec changes in CI before merge.
Overview
What It Does
Vibesafe bridges human intent and AI-generated code through a contract system:
- Specs are code: Write a Python function with types and doctests, mark where AI should fill in the implementation with
raise VibeCoded()
- Generation is deterministic: Given the same spec + model settings, Vibesafe produces the same hash and checkpoint
- Verification is automatic: Generated code must pass doctests, type checking (mypy), and linting (ruff)
- Runtime is hash-verified: In prod mode, mismatched hashes block execution; in dev mode, they trigger regeneration
Why It Exists
Traditional code generation tools either:
- Generate code once and leave you to maintain it manually (drift risk, no iteration)
- Generate code on every request (non-deterministic, slow, requires API keys in prod)
Vibesafe gives you both: fast iteration in dev, frozen safety in prod. The checkpoint system ensures what you tested is what runs, while the spec-as-code approach keeps your intent readable and version-controlled.
What's Novel
- Content-addressed checkpoints: Every checkpoint is stored under SHA-256(spec + prompt + generated_code), making builds reproducible and preventing silent drift
- Hybrid mode switching: Dev mode auto-regenerates on hash mismatch; prod mode fails hard, enforcing checkpoint integrity
- Dependency freezing:
--freeze-http-deps captures exact runtime package versions into checkpoint metadata, solving the "works on my machine" problem for FastAPI endpoints
- Doctest-first verification: Tests are mandatory and embedded in the spec, not external files—the spec is the contract
Positioning
| Tool | Approach | Vibesafe Difference |
|---|
| GitHub Copilot | Suggests code in editor | Vibesafe generates complete verified implementations |
| Cursor/Claude Code | AI pair programming | Vibesafe enforces hash-locked reproducibility |
| ChatGPT API | On-demand generation | Vibesafe caches + verifies once, reuses in prod |
| OpenAPI codegen | Schema-driven templates | Vibesafe uses LLMs for flexible logic, not just boilerplate |
Quickstart Tutorial
Dead Simple Example
Here's vibesafe in action—no configuration, just code:
>>> import vibesafe
>>> from vibesafe import VibeCoded
>>> @vibesafe
... def cowsay(msg: str) -> str:
... """
... >>> cowsay("moo")
... 'moo'
... """
... raise VibeCoded()
...
>>> print(cowsay('moo'))
moo
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
That's it. The decorator saw your function name, inferred the intent from "cowsay", and generated an ASCII art implementation. Now let's see how to use it in a real project.
Prerequisites
- Python 3.12+ (3.13 supported, 3.11 not tested)
- uv (recommended) or pip
- OpenAI-compatible API key (OpenAI, Anthropic with proxy, local LLM server)
- Claude Code (optional, for enhanced development experience)
Installation
# Clone the repo (for now; PyPI package coming soon)
git clone https://github.com/julep-ai/vibesafe.git
cd vibesafe
# Create virtual environment and install
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
# Verify installation
vibesafe --version
# or use the short alias:
vibe --version
Troubleshooting:
