# vibey

> vibey is a free, open-source orchestrator for AI coding agents: it interviews you until the spec is sharp, builds unattended on local or paid agents, stops only for the decisions that are yours, and records every step in an append-only PostgreSQL ledger, so a crashed or out-of-credit agent's work is picked up again rather than lost.

This index is generated from the documentation's navigation by `scripts/llms_txt.py`; every link is the production copy of a page. The source is https://github.com/the-vibey-project/vibey, and the pages there are the same Markdown.

## Start here

- [Home](https://the-vibey-project.github.io/vibey/main/): The documentation home — what vibey is, who it is for, what makes it different, how to try it, and how to contribute in your first hour.
- [Current estimate](https://the-vibey-project.github.io/vibey/main/estimate/): This page is a generated, append-only-ledger-backed forecast.
- [Research paper](https://the-vibey-project.github.io/vibey/main/paper/): A single autonomous coding session is not autonomous software delivery: sessions lose context across crashes, exhaust one vendor's capacity mid-task, and carry no structure for the human decisions delivery legally and…

## Guides

- [Downloads](https://the-vibey-project.github.io/vibey/main/guides/downloads/): The ready-built files attached to every vibey release, for each user interface and platform, with what is signed and how to install each.
- [VS Code extension](https://the-vibey-project.github.io/vibey/main/guides/vscode-extension/): The extension is called krypton, the name every app carries (sub-doctrine 9.e), and its id is the-vibey-project.krypton; its commands and settings keep their vibey.* names.
- [Kubernetes](https://the-vibey-project.github.io/vibey/main/guides/kubernetes/): This guide takes vibey from a laptop process to a long-lived deployment: a containerized worker, a Helm chart, an in-cluster PostgreSQL, and queue-depth autoscaling via KEDA.
- [Greeter live demo](https://the-vibey-project.github.io/vibey/main/guides/greeter-live-demo/): This runbook drives one small project ("a CLI greeter") end to end on real *loop binaries: DESIGN through the interactive interview, BUILD on engine-selected sessions, REVIEW with real automated gates, and DONE(local).
- [Local models on Ollama](https://the-vibey-project.github.io/vibey/main/guides/local-models-ollama/): Sub-doctrine 8.a makes the sovereign path the preferred way to run vibey, not the fallback.
- [Convergence-Driven Development](https://the-vibey-project.github.io/vibey/main/guides/convergence-driven-development/): Convergence-Driven Development (CDD) is the delivery loop above Specification-Driven Development (SDD) and Test-Driven Development (TDD).
- [What gets published](https://the-vibey-project.github.io/vibey/main/guides/ledger-publication/): vibey ledger export never publishes your ledger.
- [Continuous delivery estimate](https://the-vibey-project.github.io/vibey/main/guides/delivery-estimate/): vibey-gh forecast maintains the current delivery estimate from real repository history.
- [Self-hosted sovereign surfaces](https://the-vibey-project.github.io/vibey/main/guides/self-hosted-surfaces/): vibey orchestrates software delivery end-to-end on sovereign defaults: every operational dependency — issue tracking, documentation, secrets, files, email, SMS, messaging, configuration store, caching, message bus…
- [The Sabbath](https://the-vibey-project.github.io/vibey/main/guides/sabbath/): From sundown on Friday to sundown on Saturday, vibey rests.
- [Sovereign review runner](https://the-vibey-project.github.io/vibey/main/runbooks/sovereign-review-runner/): How to stand up, verify and remove the self-hosted runner that runs pr-review.yml's review-sovereign job on [self-hosted, vibey-local-vibey] (sub-doctrine 8.a).
- [Host optimization](https://the-vibey-project.github.io/vibey/main/runbooks/host-optimization/): How the machine vibey runs on is kept healthy and fitted to its workload, with every change declared in the repository, applied under a gate, measured week after week, and reversible.

## What do you want to do?

- [Overview](https://the-vibey-project.github.io/vibey/main/guides/outcomes/): Six short guides, each answering one question people bring to AI coding agents, with the commands, the evidence behind every claim, and the limits.
- [Run agents on your own hardware](https://the-vibey-project.github.io/vibey/main/guides/outcomes/run-agents-on-your-own-hardware/): Run vibey on its default engine, GPT-OSS 20B on Ollama, and allow only that engine; the queue, the ledger and the model then stay on one machine, and the measured sovereign path needs no internet at runtime.
- [Cap and trace agent spending](https://the-vibey-project.github.io/vibey/main/guides/outcomes/cap-agent-spending/): Set a per-cycle dollar or turn cap with vibey budget set; the brake reads it before every BUILD session and parks a gate when it trips, and vibey cost shows each engine's spend from the ledger.
- [Keep a tamper-evident record](https://the-vibey-project.github.io/vibey/main/guides/outcomes/keep-a-tamper-evident-record/): vibey appends every decision, question, answer, handoff and cost to a PostgreSQL ledger that its application role cannot rewrite, and each export walks a SHA-256 chain over every event to show an edit.
- [Review AI changes before merge](https://the-vibey-project.github.io/vibey/main/guides/outcomes/review-ai-changes-before-merge/): vibey stops at a REVIEW gate that waits for your verdict, and vibey-gh binds every check and review on a GitHub pull request to its exact head commit, so the merge train merges only what passed on that commit.
- [Deploy without holding cloud secrets](https://the-vibey-project.github.io/vibey/main/guides/outcomes/deploy-without-storing-secrets/): Partly, and not yet for production; vibey's opt-in Azure stages keep no cloud credential, act as the az CLI identity you signed in with, and change nothing until you consent, but no real-Azure run is proven yet.
- [Use vibey in a regulated environment](https://the-vibey-project.github.io/vibey/main/guides/outcomes/take-vibey-into-a-regulated-environment/): vibey holds no certification, but it gives an assessor concrete mechanisms to examine, each linked to its evidence, and it says plainly which controls stay with you.

## Case studies

- [How vibey survives a crashed agent](https://the-vibey-project.github.io/vibey/main/case-studies/how-vibey-survives-a-crashed-agent/): When an AI coding agent crashes mid-task, vibey loses no job and commits no job twice — leases, an append-only ledger and parked human gates, with the chaos test that proves it and the costs it pays.

## Reference

- [CLI](https://the-vibey-project.github.io/vibey/main/reference/cli/): Every vibey command and subcommand, written by hand against src/vibey/cli/main.py and checked against it as of 2026-09-29.
- [Configuration](https://the-vibey-project.github.io/vibey/main/reference/configuration/): The schema below is fully implemented and unit-tested in src/vibey/domain/config.py (VibeyConfig, parse_config, parse_toml_string) and src/vibey/infrastructure/config_loader.py (load_config_from_path). vibey new reads…
- [Hub API](https://the-vibey-project.github.io/vibey/main/reference/hub-api/): The hub is vibey serve (ADR-0068): one HTTP API that every krypton client -- desktop, mobile, web, the VS Code extension -- reaches.
- [System requirements](https://the-vibey-project.github.io/vibey/main/reference/system-requirements/): What a machine needs to run vibey and its krypton clients, and how each figure is known.
- [Distance from full autonomy](https://the-vibey-project.github.io/vibey/main/reference/autonomy/): How far vibey is from running its whole delivery loop without a person, stage by stage, measured weekly from the forge, the review canary, the code and the local queue.
- [Host health](https://the-vibey-project.github.io/vibey/main/reference/host-health/): How healthy is the machine vibey and krypton run on, and how long until it needs replacing?
- [Context microslices](https://the-vibey-project.github.io/vibey/main/context-microslices/): This is the implementation contract for proposed doctrine 10.k and ADR-0075.

## Design

- [The design system](https://the-vibey-project.github.io/vibey/main/design/): Every colour, face, size, space, radius, shadow, curve and sound cue that a vibey surface uses comes from one place: design/tokens/.
- [Motion](https://the-vibey-project.github.io/vibey/main/design/motion/): Motion in vibey and krypton explains.
- [The Beauty Bar](https://the-vibey-project.github.io/vibey/main/design/beauty-bar/): The checkable bar that sub-doctrine 12.k (beauty is the first measure) cites.

## Architecture — Decision records

- [0001 — Orchestrate the *loop runners; do not reimplement them](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0001-orchestrate-do-not-reimplement/)
- [0002 — PostgreSQL, not SQLite, for the queue and ledger](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0002-postgres-not-sqlite/)
- [0003 — An event-sourced ledger is the conversation's source of truth](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0003-event-sourced-ledger/)
- [0004 — Handoffs are gated by a deterministic no-loss predicate](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0004-no-loss-gate-on-handoff/)
- [0005 — Smooth weighted round robin, not modulo rotation](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0005-smooth-weighted-round-robin/)
- [0006 — A normalized effort ladder with saturating per-engine projection](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0006-normalized-effort-ladder/)
- [0007 — Rotate at boundaries, never mid-turn](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0007-rotate-at-boundaries/)
- [0008 — Git worktree per work item; containers for real isolation](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0008-worktree-isolation/)
- [0009 — Human gates park jobs; they never block workers](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0009-human-gates-are-parked-jobs/)
- [0010 — Review loops back to design by default, to build on the fast path](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0010-review-loopback-routing/)
- [0011 — One source of truth, materialized into every engine's guidance files](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0011-agent-surface-provisioning/)
- [0012 — Deployment is a separate CLI built on azure-bootstrap](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0012-deploy-is-a-separate-cli/)
- [0013 — Deployment is a three-phase stage set in the core lifecycle](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0013-deployment-is-a-three-phase-stage-set/)
- [0014 — Optional visual design and deployment opt-in gates](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0014-optional-visual-design-and-deployment-opt-in/)
- [0015 — qwenloop is an opt-in local engine — a standby tier for BUILD, the sovereign provider for DESIGN](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0015-qwenloop-standby/)
- [0016 — Code lives in classes, and every class has an interface beside it](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0016-classes-behind-interfaces/)
- [0017 — If the family already does it, the family does it here](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0017-dogfood-the-family-first/)
- [0018 — If it can be declared in the repository, it is declared in the repository](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0018-everything-as-code/)
- [0019 — Vibey is installable wherever its users already are](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0019-installable-wherever-its-users-are/)
- [0020 — A governing rule belongs in the canon, ratified, or it is not a rule](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0020-governing-rules-are-ratified-subdoctrines/)
- [0021 — One tree, history preserved — the family is absorbed as subtrees in a uv workspace](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0021-one-tree-history-preserved/)
- [0022 — An absorbed package keeps every gate it was already held to](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0022-absorbed-packages-keep-their-own-gates/)
- [0023 — Four layers, four floors — 100% branch coverage per layer, each its own gate](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0023-four-layers-four-floors/)
- [0024 — Every bounded ladder ends in a park that can grant more](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0024-every-bounded-ladder-parks-with-a-grant/)
- [0025 — Kubernetes — a chart, KEDA on claimable work, and an operator that never grows its own logic](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0025-kubernetes-operator-crd-keda/)
- [0026 — tini is PID 1, and the SIGTERM latch is armed before the first import](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0026-tini-pid1-and-the-sigterm-latch/)
- [0027 — A sovereign DESIGN provider — phase one runs without paid credit](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0027-sovereign-design-provider/)
- [0028 — vibey-gh owns provenance and release; release-please is retired](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0028-vibey-gh-owns-release-and-provenance/)
- [0029 — Integrates are serialized by a Postgres advisory lock, and contention is a Defer](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0029-integrate-serialized-by-advisory-lock/)
- [0030 — The live harness has two modes — faked by default, paid by explicit choice](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0030-two-mode-live-harness/)
- [0031 — Skills context is a packet compiled over a process boundary, shadow before inject](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0031-skills-context-packets-over-a-process-boundary/)
- [0032 — The documentation ships as a research paper and a book, findable everywhere and built to outlive the site](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0032-the-docs-ship-as-a-paper-and-a-book/)
- [0033 — Governance in plain sight — the law is as easy to find and as visible as possible, on every human-readable surface](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0033-governance-in-plain-sight/)
- [0034 — One Claude Code marketplace at the repository root, rendered from the workspace members](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0034-one-marketplace-at-the-root/)
- [0035 — Verify independence is the default, not an absolute](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0035-independence-is-the-default-not-an-absolute/)
- [0036 — The merge queue is declared, not clicked](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0036-the-merge-queue-is-declared-not-clicked/)
- [0037 — One distribution, one version — the whole family ships inside vibey](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0037-one-distribution-one-version/)
- [0038 — Local engines are preferred first (8.a) — claudeloop-local, tiered selection, and sovereign DESIGN/DECOMPOSE by default when enabled](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0038-local-engines-are-preferred-first/)
- [0039 — Convergence-Driven Development (CDD) encloses specification and test-driven development](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0039-convergence-driven-development/)
- [0040 — Evidence-bounded status for runs, features and research claims](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0040-evidence-bounded-status/)
- [0041 — Software organisms are alive in the digital realm](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0041-software-organisms-alive-in-the-digital-realm/)
- [0042 — Sovereign self-hosted defaults on every surface; paid platforms are declared-only relays](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0042-sovereign-self-hosted-defaults-and-declared-paid-relays/)
- [0043 — Sovereign operational surfaces deploy into the Kubernetes cluster with reconciled health](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0043-sovereign-surfaces-install/)
- [0044 — The job queue is a port; RabbitMQ dispatches and every loop runs as one service](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0044-job-queue-port-and-loop-services/)
- [0045 — Every deployment measures the machine it runs on and fits itself to it](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0045-fitted-to-the-iron/)
- [0046 — Standing authority to act unattended is bounded by a gate a human defined](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0046-unattended-authority-is-bounded-by-a-gate/)
- [0047 — Anything that can be fully automated to make a developer's life better is](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0047-the-toil-is-automated/)
- [0048 — A job that consumes an accumulating record reads every datum in the gap](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0048-the-unbroken-read/)
- [0049 — A named agent may approve an unattended change, and is never its author](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0049-the-delegated-approver/)
- [0050 — The harness and every automation are kept fast, and speed never buys less measurement](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0050-the-machinery-does-not-waste-a-persons-time/)
- [0051 — Configuration is declared in TOML, never written into a source file](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0051-nothing-is-compiled-in-that-could-be-declared/)
- [0052 — A tracker is kept true by the machinery that changes what it describes](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0052-the-tracker-tells-the-truth/)
- [0053 — An unattended run takes direction only from the operator's account](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0053-the-unattended-run-admits-no-stranger/)
- [0054 — A bumped job runs next, first in first out, and only the operator or a declared source may bump](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0054-a-bumped-job-runs-next/): accepted (cited by #1089, the storm's priority lane, and by #1091, vibey's job queue; the storm conforms to items 4–7 once #1092 merges — see Conformance below) · Date: 2026-09-24 · Cites: sub-doctrines 8.c, 12.j, 12.h…
- [0055 — The ledger is append-only by the database, not by convention](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0055-the-ledger-is-append-only-by-the-database/)
- [0056 — Everything a queue guards is reaped by measurement](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0056-everything-a-queue-guards-is-reaped-by-measurement/)
- [0057 — Storm work lives on durable storage, is committed and pushed often, and a tool refuses volatile paths](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0057-the-work-outlives-the-machine/)
- [0058 — Concurrent runs of a local model are measured on each device, and unmeasured or stale means one](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0058-concurrent-local-runs-are-measured-per-device/)
- [0059 — The editor drives the family's own loops, on a copy, and adds no loop of its own](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0059-the-editor-drives-the-familys-own-loops/)
- [0060 — The heartbeat tells the truth, and passes the gate by the gate's own rule](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0060-the-heartbeat-tells-the-truth-and-passes-the-gate-by-its-rule/)
- [0061 — Every PostgreSQL connection authenticates with scram-sha-256](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0061-every-postgresql-connection-authenticates-with-scram-sha-256/)
- [0062 — The Beauty Law and its bar](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0062-the-beauty-law-and-its-bar/)
- [0063 — ULTRA: effort without a ceiling](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0063-ultra-effort-without-a-ceiling/)
- [0064 — gptossloop is the sovereign engine, and qwenloop is its opt-in Qwen twin](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0064-gptossloop-is-the-sovereign-engine/)
- [0065 — vibey and krypton](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0065-vibey-and-krypton/)
- [0066 — One design system for every surface](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0066-one-design-system-for-every-surface/)
- [0067 — One TypeScript core for every krypton client](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0067-one-typescript-core-for-every-krypton-client/)
- [0068 — The hub: vibey serve](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0068-the-hub/)
- [0069 — Two packages, vibey-engine and krypton-app](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0069-two-packages-vibey-engine-and-krypton-app/)
- [0070 — Failover to the sovereign engine, and handback on a recorded probe](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0070-failover-to-the-sovereign-engine-and-handback-on-a-recorded-probe/)
- [0071 — Hub pairing and trust](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0071-hub-pairing-and-trust/)
- [0072 — The Sabbath, kept where the machine stands](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0072-the-sabbath-kept-where-the-machine-stands/)
- [0073 — krypton desktop in C, on GTK 4 and libadwaita](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0073-krypton-desktop-in-c-on-gtk/)
- [0074 — Measured dispatch for every service-bus surface](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0074-measured-service-bus-dispatch/)
- [0075 — Context-bearing surfaces are linked microslice graphs](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0075-context-microslices-and-linked-surfaces/)
- [0076 — Discoverability and the first hour are deliverables](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0076-discoverability-and-the-first-hour-are-deliverables/)
- [0077 — Outcome guides: the project answers the questions its users search for](https://the-vibey-project.github.io/vibey/main/architecture/decisions/0077-outcome-guides-answer-the-questions-users-search-for/)

## Governance

- [The Constitution](https://the-vibey-project.github.io/vibey/main/governance/constitution/): The permanent, living governance of this project and its family.
- [The Twelve Doctrines](https://the-vibey-project.github.io/vibey/main/governance/doctrines/): There is no thirteenth and there never will be: anything new files as a sub-doctrine under one of the twelve.
- [The Ten Commandments of Software Engineering](https://the-vibey-project.github.io/vibey/main/governance/commandments/): Binding on every agent that works here — human and machine alike.
- [The Bill of Rights of the Human Software Engineer](https://the-vibey-project.github.io/vibey/main/governance/bill-of-rights/): Nothing is ever added beyond these; from their sealing forward, only refinements of the existing ten are made — refinements that may strengthen a right, never weaken one.
- [Subdoctrine SD-01 — Counterparties, Trust, and Verification](https://the-vibey-project.github.io/vibey/main/governance/sd-01-counterparties-trust-verification/): This page carries a standing rule of this project: how any agent acting for it treats every counterparty — people, companies, executives, states, and other software.

## Offline forms

- [Research paper (PDF)](https://the-vibey-project.github.io/vibey/main/paper.pdf): The design as a journal-formatted paper.
- [The book (PDF)](https://the-vibey-project.github.io/vibey/main/book.pdf): Every page of this site, in navigation order, as one book.
- [The book (EPUB)](https://the-vibey-project.github.io/vibey/main/book.epub): The same book for e-readers.
