README.md

---

Table of contents

• Quick start
• Why it exists
• What it is
• Ready in one command
• Why local-first
• How a run works
• Rules, not suggestions
• Full coverage, full control
• Documentation
• Built with
• Contributing
• Versioning
• License

◆ Quick start

Install Vibestrate - the command is vibe:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/guyshonshon/vibestrate/main/install.sh | sh

# …or with npm directly (macOS, Linux, or Windows)
npm install -g vibestrate

The -g matters. Vibestrate is a command-line tool, not a library: a plain npm install vibestrate adds it as a dependency of whatever project you are standing in and never puts vibe on your PATH. Nothing is published for you to import.

Vibestrate runs natively on macOS, Linux, and Windows - the full core loop (install, providers, runs, diffs, merge) works in PowerShell or cmd with no WSL. The one Windows-only exception is the in-app terminal tab; use WSL if you want an in-app shell. Details: Native Windows support.

Then point it at any git repo:

cd your-project
vibe ui

That opens Mission Control on 127.0.0.1:4317, and it is the whole setup. In a folder with no .vibestrate/ yet you land on an onboarding screen with one button, Initialize project; More > Setup then walks the same checks vibe doctor runs, with Fix what's safe for the ones that need no decision from you. New run starts the first task.

Prefer the terminal? Everything the dashboard does has a command behind it:

vibe init                     # scaffold .vibestrate/ - touches nothing else
vibe setup                    # the same wizard, as questions
vibe run "Add audit logging to the settings flow"

Ready in one command explains what gets detected and wired up for you.

↑ back to top

◆ Why it exists

Running one model is easy. Running three is a job.

You paste the same context into the second tool, because it has never seen the project. You keep the worktrees straight yourself. You carry the plan from one model to the next and explain it again, in your own words, every time. You watch each one closely enough to catch it drifting off the task you actually asked for. And when something lands wrong, there is no record of how it got there.

None of that is the work. It is the cost of doing the work in three places at once, and it grows with every model you add.

Vibestrate absorbs it. The plan lives in one place. The rules live in one place. Each model reads both, does its part in a throwaway git worktree, and hands off to the next with its output attached. Your own tests are the referee. Every prompt, diff, decision, and token is on the record, and nothing reaches your branch without you.

Same models you already pay for. Your machine. Your call at every gate.

↑ back to top

◆ What it is

Vibestrate is a local-first control layer for coding agents. It gives the AI CLIs already on your machine the three things they never get on their own:

• A plan. One brief, one spec, one roadmap. Written once, read by every model on the task and carried across each handoff, so nobody starts from zero and nothing gets re-explained.
• Rules. Your project's standards, stated as policy the run enforces, not advice a model can talk itself out of.
• A frame. Each model works in a throwaway git worktree, in the role you gave it, with the permissions you set, and stops at the gates you chose.

The rules are yours, so the strictness is yours. Tighten it until nothing moves without your sign-off, or loosen it to a single plain-language run. Both are the same tool.

You give it a task in plain language. It walks a planner → architect → executor → reviewer → verifier crew through the change, runs your validation commands, records every step, and stops at merge_ready, blocked, or failed. It never pushes and never merges. You stay in the chair.

You pick the crew: Claude Code, Codex, Gemini, Aider, Ollama, OpenCode, or a local model. Plan with one, implement with another, review with a third. Swapping a model never changes the flow.

↑ back to top

◆ Ready in one command

No keys to paste, no YAML to hand-author. Point Vibestrate at a repo and it figures out the rest:

• Finds your agents. Detects the coding-agent CLIs already on your machine - Claude Code, Codex, Aider, Ollama, OpenCode - wires up the best one, and assigns the whole crew to it.
• Reads your project. Detects the language, package manager, and project type, then suggests the real validation commands (typecheck · test · build) it should run as ground truth.
• Uses logins you already have. No API key ever lives in Vibestrate; it rides the CLIs you've already authenticated, so prompts and code go straight to those vendors.

vibe doctor is the superpower - the one command that tells you, in plain language, exactly where you stand, and --fix closes the gaps for you:

vibe doctor checks	vibe doctor --fix does
git present · you're inside a repo	configures the detected provider
.vibestrate/ initialized · config valid	assigns the crew to it
project detected (name · type · package manager)	fills validation commands from your project
which provider CLIs are installed - and which aren't	restores any missing scaffolding
every role points at a real provider, with safe permissions
validation commands are set

Green across the board means you're ready to run. Want the dashboard? Add --ui to any run:

vibe run "Tighten retry handling" --ui    # opens Mission Control

Full walkthrough → vibestrate.com/docs/getting-started/installation

↑ back to top

◆ Why local-first

This is the part that matters, so it gets no asterisks:

🔑 No APIs of ours	Vibestrate never holds an API key. It spawns the vendor CLIs you already logged into and reads their output - your prompts and code go straight to those vendors. Vibestrate is not in the middle.
💸 No payments, ever	Vibestrate is free. You pay only for the models you choose to run, billed by the vendor, exactly as before.
📡 No cloud, no telemetry	Everything runs on your laptop and nothing phones home. Beyond the calls your provider CLIs already make, Vibestrate reaches the network only when you ask it to: searching or installing from the flow hub, and vibe telemetry export, which is off by default and posts to a collector you run.
🔒 Your code stays put	Edits happen in an isolated worktree under your control. No auto-push, no auto-merge.
📖 Genuinely open source	Apache-2.0 licensed, all of it. Read it, fork it, run it offline.

↑ back to top

◆ How a run works

Every run executes a flow - an ordered recipe of steps, each performed by a role on a provider. A plain vibe run runs the built-in default flow:

plan → architecture → implement → validate → review → fix → verify
                                      ↑                  │
                                      └──── (loops) ─────┘

Each step is filled by a named Role with one job, so when something goes wrong you can read exactly where the chain broke. Validation is its own step - it runs the commands in .vibestrate/project.yml (your typecheck, tests, build) as ground truth between "I wrote it" and "looks good to me." The review→fix loop repeats until the review passes or hits its bound. Approval gates can pause a run for a human at any step.

A Flow declares the Seats it needs (planner, implementer, reviewer…); your Crew supplies the Roles that fill them, each running on a Profile (provider + model + power). Higher-stakes work runs a different flow through the same engine - for example one where multiple models arbitrate each other:

vibe run "Refactor provider permissions" --flow quality-arbitration --crew default
# run one step on a stronger Profile without changing the Role:
vibe run "Implement auth crypto" --flow quality-arbitration --step-profile implement=opus-deep

Stuck mid-run? Rewind instead of restarting - fork a fresh run that reuses the earlier steps and picks up from a chosen stage:

vibe run "<same task>" --resume-from <runId> --resume-stage executing

Concepts · Task lifecycle · CLI reference

↑ back to top

◆ Rules, not suggestions

Telling a model "stop using em-dashes" works right up until the run where it doesn't. You can't audit an instruction the model merely agreed to. So write the rule down once, at the project level, and every run gets checked against it - whichever supervisor is on duty, whichever model is in the chair.

vibe policies add no-em-dash "do not use em-dash characters" --fix "use a hyphen"
vibe policies add no-eyebrow "no eyebrow labels" --block --matcher "SectionEyebrow"
vibe policies list

Two tiers, and the difference between them is the whole point:

Tier	How it's enforced	What it's for
advise	The reviewer reads your rule alongside the diff. A violation is flagged and rides the normal review → fix loop, same as a correctness note.	Judgment calls - "no eyebrow labels", "match our design language", "don't over-engineer this". A model catches the paraphrase a regex would miss.
block	A regex over the run's changed lines. Match, and the run lands blocked with the reason shown - even if the reviewer approved it.	Rules with a shape you can name. It's not a model verdict, so it can't be reasoned with, softened, or forgotten.

Here's the part that matters: a block is owner-only. The supervisor can propose a rule from a consult, but that path is hard-constrained to advise, and the proposal sits pending doing nothing until you confirm it. A model can never author its own hard merge-cap. The gate scans from the run's fork point (so mid-run commits are caught), skips secret-shaped files, and fails closed - if it can't read the diff, it blocks rather than waving the change through.

The dashboard Policies page does all of it too: create either tier, confirm or reject what the supervisor proposed, remove. And a plain vibe run needs zero policies - this is an additive layer, not a tax.

Policies · CLI reference

↑ back to top

◆ Full coverage, full control

Easy to start is only half of it. The trade Vibestrate makes is unusual: maximum convenience and maximum visibility. Every run is a glass cockpit, not a chat log.

• Watch it happen. Live, token-by-token output from each agent - the same stream you'd see in the terminal, surfaced in the dashboard.
• Everything on the record. Plan, architecture, diff, review findings, fix, verification - each phase writes a named artifact you can read, inspect, and replay.
• Real cost, real tokens. A per-step and per-run ledger of tokens and dollars, plus a daily spend cap that can warn, downgrade the model, or stop the run when you hit it.
• Validation as referee. Your own typecheck / tests / build run between "I wrote it" and "looks good," so review stands on ground truth - not vibes.
• Your call at every gate. Approval gates pause for a human; nothing pushes, nothing merges. A run ends at merge_ready, blocked, or failed - you decide what lands.
• Merge from a tree you can see. The dashboard Git tree draws your branches as a graph: pick any source and target, predict the merge and its conflicts before applying, let the supervisor propose a resolution per conflict (secret-safe - secret-shaped files are never sent to a provider), apply on an explicit click, and undo with one guarded click. Every merge is human-initiated, gated through the Action Broker, --no-ff, local, and never pushed.
• OS sandbox when you want it (off by default). The worktree, the diff gate, and human-review-before-merge already bound what a run can do, so confinement is opt-in, not a tax on every run. Flip execution.isolation: sandboxed for an untrusted task or an unattended run and each turn runs under the provider's own OS sandbox (codex's Apple Seatbelt / Linux Landlock - a write outside the worktree is refused by the OS). A provider without a real sandbox warns once and runs unsandboxed rather than pretending; the run records only what was actually enforced.
• Cut the network too (off by default). With the container backend, execution.container.egress.mode: allowlist puts the run container on a Docker network with no gateway - so there is no route out except an allowlisting proxy that refuses any host you didn't name (the model APIs are allowed out of the box; refusals are logged with the exact host). The enforcement is the missing route, not a HTTPS_PROXY variable a hostile turn could ignore, and if the network or proxy can't be created the run is refused rather than quietly running wide open. Honest limit: a TLS tunnel to an allowed host is opaque, so this narrows exfiltration to hosts you chose - it doesn't eliminate it.
• Limits you can't accidentally lose. Policies are default-allow with a veto - so the broker is where you impose rules, and a rule that silently failed to load would be worse than none. A run refuses to start while any policy file is malformed or a rule id is defined twice (the duplicate is dropped, so your stricter rule would have vanished). require_approval is accepted only where something can actually pause, instead of quietly meaning deny. And an unattended run with no ceiling and no confinement tells you so before it starts.
• Ask the orchestrator. vibe consult "should this use a heavier review?" (or the dashboard Consult button) answers from your project's real context - config, recent runs, validation evidence, and a committed VIBESTRATE.md manual - and is honest about what it could not verify. It also carries Vibestrate's own documentation, compiled into the build and selected per question by deterministic keyword retrieval (no model call, no search service, silent on questions that aren't about Vibestrate), so "how do I make a crew" is answered from the real commands. It never touches your code: no run, no repository edit, no merge. The one thing it writes on its own is a pending policy proposal in project.yml, forced to the advise tier and inert until you run vibe policies confirm <id>.
• It learns your codebase, deterministically. vibe learn (also run best-effort by vibe init) scans stack, scripts, layout, languages, best-effort HTTP routes, and tooling into a machine-owned, regenerable map (.vibestrate/CODEBASE.md + codebase-map.json - no model call, secret-redacted, atomic). It grounds the planner and Consult, refreshes itself at run terminal outcomes, and marks itself stale once HEAD moves - vibe learn show prints it, and the dashboard's Codebase page has a Map view with a Refresh action.
• The Flow is never hidden. Every run shows Flow: <name> · <source>. Pin a default with vibe flows use <id>, force one with --flow, or let the orchestrator pick for the task with --select (it states a confidence + reasons and records why).
• Author a Flow or a Crew in the dashboard, or describe one and get a draft. The Flow Editor (Flows page) re-runs the real flow schema on every keystroke and pins each violation to the step, seat, or field that caused it - Save is disabled while one stands, and it posts the schema's own parsed output, so a Flow that looked valid in the form cannot be refused on the way to disk. The Crew Editor (Crew page) edits Role parameters and instructions in place and is explicit that the structural half - adding, removing, or renaming a Role, and creating a Crew from scratch - is a project.yml edit it hands you the exact bytes for, rather than one it makes behind your back. Or start from English: vibe flows draft / vibe crew draft (and the same panels in both pages) return an editable draft and write nothing; accepting it is a separate, explicit action.
• Fill your project once. A Flow declares typed params: (name, niche, brand color…); Vibestrate remembers your answers as durable project parameters and seeds every later run, so you stop re-typing them. vibe params set / a VIBESTRATE_PARAM_* env var is the clean CI seed (a missing required param fails fast, never hangs); the dashboard form prefills, and an optional Generate button can have a provider draft a value you review. Secrets are stored as an env:NAME reference, never the raw value - and a run fails fast if that env var is unset.
• A supervisor with a posture. The orchestrator ships a default skeptical staff-engineer persona (Supervisor: <name>, pick per run with --supervisor or in the composer; vibe supervisor list). It earns its keep, not by tone: a risk-tagged task (auth, payment, migration, secrets…) is deterministically upgraded to heavier review and logged - upgrade-only, never softening a gate. Personas are advisory (pinned below every code-enforced gate, no confidence inflation); the run-assurance badge labels review independence honestly (cross-model vs same-model single-profile).
• Parallel review when it's worth it. A Flow can declare a dependency graph; the built-in panel-review fans out three read-only reviewers (correctness, tests, security/risk) over the same diff at once, then an arbiter joins their findings into one verdict. Parallel steps are hard-enforced read-only (one writer per worktree), bounded, and the fan-out cost is stated up front - never silent.
• Parallel agents per checklist item. The graph can also live inside the per-item band: the built-in pickup-analysis works a card item-by-item, and for each item two read-only analysts (risk/impact + test-surface) study it in parallel before the implementer writes it - "think in parallel, then build", a commit per item. The Flow Builder graph (and vibe flows show, and the TUI) show the band and that it repeats per item.
• Supervised tasks - author a feature as coordinated steps. A supervised task (vibe tasks add --supervised) holds ordered steps, each with a scoped objective, a done-when check, and file hints. Author the full decomposition of a feature in one card, then hand it to the Conductor (vibe tasks run / vibe tasks sequence), which sequences the steps one at a time - each planned, implemented, and reviewed before the next begins, with a between-steps supervisor that can proceed, re-ground the plan, or halt cleanly.
• Scriptable, on your terms. The dashboard is backed by a stable HTTP API (versioned /api/v1, loopback by default). Drive it from scripts; bind it to the network only behind a bearer token. Share recipes with single-flow import/export (vibe flows export/import, or the dashboard) - portable because Flows name Seats, not your local crew.

That's the category in one line: Vibestrate is a supervisor, not an autopilot.

↑ back to top

◆ Documentation

Everything lives at vibestrate.com/docs - getting started, concepts, workflows, troubleshooting, and a source-aware reference for every command, config key, provider, and Flow (generated straight from the code, so it never drifts).

↑ back to top

◆ Built with

↑ back to top

◆ Contributing

Contributions are genuinely welcome - this is a learning project, and a better one with you in it.

• 🐛 Found a bug? Open an issue - what you ran, what happened, and the runId if you have one.
• 🔐 Security concern? Please don't open a public issue - see SECURITY.md for private disclosure.
• ✨ Want to build something? Features come in as pull requests - that's the path we encourage most. A quick issue first to sketch the idea is welcome but optional. See CONTRIBUTING.md.

Run the checks before you push:

pnpm install && pnpm typecheck && pnpm test && pnpm build

↑ back to top

◆ Beta

Vibestrate is in beta. Not a disclaimer - a description of which parts have settled and which have not, so you can decide what to build on.

Settled. The CLI command names and their flags. The run model: a run works in its own git worktree, stops at merge-ready, and never pushes or merges on its own. Your code and your runs stay on your machine - no cloud backend, no relay, no telemetry. The one call out is the Flow Hub, when you go looking for a flow. The .vibestrate/ layout for runs, tasks and events.

Not settled. The config schema, and the policy schema in particular - one release refused a require_approval effect that the one before it accepted at load. Flow and crew YAML. The HTTP surface outside /api/v1. Internal modules under src/ are not an API at all.

What you get before something breaks. Every breaking change leads its release notes with the migration, in the words you would need to fix it - see CHANGELOG.md for the shape. Loud is the point: a config Vibestrate can no longer honour is refused at load rather than silently ignored, because a rule you believe is holding and never fires is worse than an error.

If you need it to stop moving, pin an exact version rather than a caret range:

"vibestrate": "0.3.0"

Beta ends at 1.0.0, when the config and policy schemas go a release cycle without a breaking change.

◆ Versioning

Vibestrate is on 0.x, and briefly wasn't. It reached 1.0.0 before the config and policy schemas stopped moving, which is a promise a 1.x number makes and this one could not keep, so the numbering was corrected back down to where the project actually is. The 1.x line is retired: latest resolves to the current 0.x release, so a plain install gets the right thing. If you pinned a 1.x during that window, move to the current version - same product, better tested.

Within 0.x, Vibestrate versions by the SIZE of the change. A patch (0.1.1) is ordinary work: a merged branch, a fix, a feature that fits the shape already there. A minor (0.2.0) is a big change, something that alters how you work with the product. 1.0.0 means beta is over, not that something broke.

That last part is the deliberate difference from strict SemVer: a breaking change does not on its own earn a major here. When one ships, it leads the release notes with its migration. Pin an exact version if you need that guarantee rather than a caret range.

The public surface is the CLI commands and their flags, the config schema, and the versioned HTTP API (/api/v1). Internal modules under src/ are not a public API and can change in any release. The version lives in package.json only, and flows into vibe --version and the generated docs reference.

◆ License

Distributed under the Apache License 2.0. Use it, fork it, ship it.

---