Concepts

A feature spec is a markdown file that describes what a piece of your software should do, without prescribing how. Specs live in .vibe/features/ and are the source of truth for your project.

Each spec has YAML frontmatter with structured metadata:

Uses

Dependencies on other features. Controls compilation order (topological sort).

Data

Data entities this feature touches (e.g., User, Task). Helps the compiler understand the data model.

Never

Hard constraints the compiler must respect. These are treated as invariants during code generation.

Connects

External integrations this feature depends on (e.g., Stripe, Google Sheets). References integration specs in .vibe/integrations/. VibeStudio can generate these for you.

The body of the spec uses free-form markdown: what the feature does, its behavior rules, and acceptance criteria. Write for a human reader — the AI compiler understands natural language.

Every VibeHub project has a .vibe/ directory at its root. This is where all spec-level information lives:

meta.json

Project name, creation date, and version.

project.json

Build manifest — language, framework, and commands for install, dev, build, and test.

features/

Feature spec markdown files. Supports nested directories for grouping.

requirements/

YAML files defining tech stack, infrastructure, and environment constraints.

mapping.json

Maps each feature spec to its corresponding source file globs. Updated during compilation.

remote.json

Remote connection config — links this local project to a VibeHub project for push/pull. See Remote Config below.

The .vibe/remote.json file links a local project to its VibeHub counterpart. It's what enables push and pull between your machine and the web.

{
  "owner": "your-handle",
  "repo": "my-project",
  "webUrl": "https://getvibehub.com"
}

How it gets created:

• vibe clone — automatically created with the correct owner, repo, and web URL.
• VibeStudio — created when you connect an existing local project to a VibeHub project through the app.
• Manually — you can create this file yourself if you initialized with vibe init and later created a matching project on VibeHub. Just set owner to your VibeHub handle and repo to the project name.

The owner field must match the authenticated user when pushing. The server rejects writes where the bearer token's user doesn't match the project owner — editing remote.json to point at someone else's project won't grant write access.

Compilation is the process of turning specs into working code. Features are sorted by their dependency graph, then each feature goes through a two-phase agentic loop: a strong model generates the code, then a fast model builds, typechecks, tests, and fixes errors iteratively until everything passes.

You can compile locally via the CLI (vibe compile) or trigger a cloud compile from the VibeHub web UI. Cloud compiles show real-time progress as the agent works.

For a deep dive into how the agent works — dependency resolution, the two-phase loop, tool sandboxing, model selection, and more — see the Compilation docs.

A snapshot is an immutable capture of all your feature specs at a point in time. Snapshots are created automatically when you:

• Merge an update (PR)
• Edit a feature on the web
• Create or fork a project

Each snapshot can be compiled independently. This means you can recompile an older version of your specs with a newer model, or compare outputs across models for the same spec version.

Updates are VibeHub's equivalent of pull requests, but at the spec level. When someone proposes a change, the review page shows two views of what changed:

Intent changes

The default view. An LLM analyzes the spec files and extracts what behavioral intent actually changed — new capabilities, removed constraints, modified rules. Rewording, formatting, and clarifications that don't alter meaning are filtered out. Each change is shown as a one-sentence summary.

Content diff

A traditional line-level diff of the raw markdown, with added/removed highlighting. Available as a toggle for when you want to see exactly what text changed.

Intent diffing reduces cognitive load: instead of reading through full spec files to figure out what's different, reviewers see a clear list of what the change actually means. For new files, every discrete intent is extracted. For modified files, only genuine behavioral changes are surfaced.

Each update also includes implementation proofs: the AI-generated code that would result from the spec change. Reviewers can evaluate whether the intent is right without reading implementation details.

If specs have been modified on both sides, VibeHub detects conflicts and offers three resolution options: accept the main version, accept the incoming version, or use AI to intelligently merge both versions (called “feathering”). The conflict resolver shows a side-by-side diff of each version against the common ancestor, with per-line change highlighting.

Any public project on VibeHub can be forked. Forks maintain lineage — a link back to the original snapshot they were created from.

Lineage tracking enables two things: understanding where a project came from, and pulling upstream spec changes into your fork. This works at the spec level, not the code level, so even projects compiled with different models can share spec improvements.

VibeHub is model-agnostic. You choose which AI model compiles your specs. Currently supported providers:

• Gemini (default for CLI and free-tier cloud compiles)
• Claude (available for cloud compiles)
• OpenAI (available for cloud compiles)

Free tier: If you don't configure your own keys, VibeHub uses platform Gemini keys with reduced concurrency (1 active compile at a time).

Bring your own key (BYOK): Add your own API key for any supported provider in your account settings on the web. Keys are encrypted at rest (AES-256-CBC) and never exposed to clients. BYOK users get higher concurrency limits (up to 3 active compiles) and access to all supported models.

Model selection is per-project and can be changed in project settings. Different models may produce different implementations from the same spec — that's expected and useful for comparison.

Updates can also be managed from the command line using vibe updates. You can list, close, reopen, retry compilation, and revert updates without leaving the terminal. See the CLI Reference for details.