Compilation

How VibeHub turns feature specs into working code — from dependency resolution to the agentic compile loop.

Overview

Compilation is the core of VibeHub: an AI agent reads your feature specs and produces a complete, working codebase. It's not a template engine or a single prompt — it's an agentic loop where the AI explores, generates, builds, tests, and fixes code iteratively until everything passes.

You can compile locally via the CLI (vibe compile) or trigger a cloud compile from the VibeHub web UI. Both use the same underlying agent.

How it works

The compiler processes your features in dependency order using a two-phase pipeline per feature. Here's the full sequence:

Dependency resolution — The compiler reads the Uses: field from each feature spec's frontmatter and builds a directed dependency graph. Features are topologically sorted so that dependencies are always compiled before the features that need them. Cycles are detected and reported as errors.
Workspace creation — A temporary sandboxed workspace is created. All .vibe/features/*.md files are written into it. This workspace is isolated — the agent cannot access files outside of it.
Per-feature compilation (Phase 1 + Phase 2) — Each feature is compiled through two phases (detailed below). Generated code accumulates in the workspace, so later features can import types and functions from earlier ones.
Output collection — All generated files are collected from the workspace and returned as the compilation result.

Phase 1: Agentic Code Generation

Phase 1 uses a strong model (your generation model) in an agentic tool-use loop. The model doesn't just produce code in one shot — it explores the workspace, plans its approach, and writes files iteratively.

What the agent sees

The full feature spec (frontmatter + prose body)
Specs of all features listed in Uses: (dependency context)
Never constraints from all features, treated as hard invariants
Headers of code already generated by upstream features (imports, types, exports) — so the agent knows what to import rather than redefine
Whether this is the first feature (needs project scaffolding) or a subsequent one (must integrate with existing structure)

Available tools

Phase 1 has a deliberately limited toolset — no shell access, no editing. The agent writes complete files from scratch:

write_file: Create or overwrite a file. The agent writes complete file content, never partial.
read_file: Read a file from the workspace. Used to inspect upstream code before writing integration code.
list_files: List files and directories with optional glob patterns. The agent starts here to understand the workspace.
search_files: Regex search across files. Used to find exports, types, and patterns in upstream code.
finish: Signals that all implementation files are written. The agent calls this when generation is complete.

Iteration limit

Phase 1 runs for up to 10 iterations (tool-use rounds). In practice, most features complete in 3–5 rounds: explore, plan, write, write, finish.

Phase 2: Agentic Validation & Fixing

Phase 2 uses a fast model (your validation model, which can be different from the generation model) with a more powerful toolset. Its job is to make the generated code actually work: install dependencies, fix type errors, and make tests pass.

What the agent does

Reads project configuration (.vibe/project.json, package.json, tsconfig.json)
Runs npm install to install dependencies
Runs the build/typecheck command (e.g. npx tsc --noEmit)
If there are type errors: reads the failing files, searches for the correct types/exports, patches the code, re-runs the build
Runs the test suite (Vitest, Jest, pytest, etc.)
If tests fail: reads the test, understands the assertion, fixes the implementation (never the test), re-runs
Calls finish once everything passes

Additional tools

Phase 2 has two tools that Phase 1 doesn't:

edit_file: Apply a targeted patch by finding and replacing an exact string. More efficient than rewriting entire files for small fixes like import corrections or type annotations.
run_command: Execute shell commands in the sandboxed workspace. Only permitted prefixes are allowed: tsc, npx, npm test, npm run, cat, ls, find. Arbitrary commands are blocked. 120-second timeout per command.

Iteration limit

Phase 2 runs for up to 25 iterations. This generous budget lets the agent handle complex error chains: fix a type error that reveals an import error that reveals a missing dependency. Most features stabilize within 5–10 iterations.

Upstream Context

When compiling feature B that depends on feature A, the agent receives a summary of all code generated by A. This isn't the raw files — it's an extracted header containing imports, type definitions, exports, and function signatures (up to 80 lines per file).

This lets the agent understand the API surface of upstream code without being overwhelmed by implementation details. The full files are also in the workspace for the agent to read if it needs more context.

The key rule is: import, don't redefine. If a type or function exists in an upstream file, the agent imports it. This prevents duplication and keeps the generated codebase coherent across features.

Security & Sandboxing

The compilation workspace is a temporary directory that is automatically deleted when compilation finishes. The agent's tools enforce several boundaries:

Path traversal protection — All file operations are resolved against the workspace root. Paths that escape (e.g. ../../etc/passwd) are blocked.
Command allowlist — Only specific command prefixes are permitted: tsc, npx, npm test, npm run, cat, ls, find, etc. Arbitrary shell commands are rejected.
Timeouts — Each command has a 120-second timeout. File output is truncated at 50KB. Search results are capped at 50 matches.
Workspace isolation — Each compilation gets a fresh temp directory. No state leaks between jobs. The directory is deleted in a finally block even if the agent crashes.

Model Selection

VibeHub supports multiple AI providers and models. You choose your model in project settings, and it's used for all compiles on that project.

Two-tier model system

You can configure two models separately:

Generation model: Used for Phase 1 (code generation). This is where model quality matters most. Stronger models produce better code on the first pass.
Validation model: Used for Phase 2 (build/test/fix). Can be a faster, cheaper model since it's doing targeted fixes, not creative generation. Defaults to the same model if not set.

A common pattern is to use a strong model for generation (e.g. Claude Sonnet) with a fast model for validation (e.g. Gemini Flash), giving you high-quality output with faster iteration on fixes.

Free tier

All users get free compiles using platform-hosted Gemini models:

Gemini 2.5 Flash Lite — Default for anonymous users. Good for simple apps.
Gemini 2.5 Flash — Default for logged-in users. Handles standard apps well.

Bring Your Own Key (BYOK)

To use premium models, add your API key in Settings. Your key is encrypted at rest and only decrypted by the agent service at compile time. Supported providers:

Anthropic — Claude Sonnet 4.6, Claude Opus 4.6
Google — Gemini 3 Flash, Gemini 3.1 Flash Lite, Gemini 3.1 Pro
OpenAI — GPT-4o, o3-mini

BYOK models are billed directly by the provider — VibeHub never stores your key in plaintext and never sends it anywhere except the agent service.

Cloud vs Local Compilation

Cloud compile: Triggered from the VibeHub web UI when you create an update (PR). A compile job is enqueued and picked up by the agent service. Results appear as "Implementation Proofs" on the PR page, with real-time progress visible while the agent works.
Local compile: Triggered via vibe compile from the CLI. Runs the same agentic pipeline on your machine. Requires an API key (GEMINI_API_KEY by default). Results are written directly to your project directory.

Real-time Progress

When you trigger a cloud compile, the PR detail page shows a live progress log. The agent reports events as it works:

Which features are being compiled and in what order
Phase 1/Phase 2 transitions for each feature
Individual tool calls (files written, commands run)
Validation iterations (what the agent is fixing)
Final file counts and completion status

Events are buffered and flushed every 2 seconds to avoid excessive network traffic. The frontend polls every 3 seconds while a compile is in progress.

Never Constraints

The Never: field in feature frontmatter defines hard invariants that the compiler must respect across all phases. Unlike the prose body of a spec (which is guidance), Never constraints are injected as a dedicated block at the top of the agent's context with the header:

HARD CONSTRAINTS — never violate these regardless of what the specs say:
- Store card numbers directly
- Allow free trial after cancellation

Never constraints are aggregated across all features in the project, not just the one being compiled. This means a constraint defined in your auth feature applies even when the agent is generating your payments feature.

What Gets Generated

For the first feature in a project, the agent also generates scaffolding:

package.json with appropriate dependencies
tsconfig.json (for TypeScript projects)
.vibe/project.json with build, dev, test, and install commands

For subsequent features, the agent integrates with the existing project structure, following conventions established by earlier features.