Installation

You need Node.js 24 or newer and a git repository.

npm install -g vibestrate     # or: curl -fsSL get.vibestrate.com | sh
cd your-project
vibe ui

vibe ui serves the dashboard on http://127.0.0.1:4317, opens your browser and starts the scheduler. The rest happens in More > Setup: the vibe doctor checks as numbered steps, with Initialise this project and Fix what’s safe on the page.

Works on macOS, Linux and Windows, no WSL required.

A codebase map is not part of this. .vibestrate/CODEBASE.md, the auto-derived map that starts an agent oriented, comes from vibe learn, which vibe init runs at the end of the CLI path and the dashboard’s initialise skips. Run vibe learn once if you want it.

• Node.js 24 or newer. Check yours with node --version.
• git 2.5 or newer. Each run gets a second checkout of your repo, torn down after; older git can’t do that.
• npm or pnpm, to install the package.
• At least one coding-agent CLI on your PATH: Claude Code, Codex, Gemini, Aider, Ollama, OpenCode or another supported provider. The Setup page names what’s missing.

npm install -g vibestrate
# or
pnpm add -g vibestrate

The -g matters. Without it, npm install vibestrate installs into the project you’re standing in and never puts vibe on your PATH.

On macOS or Linux the install script does the same, in plain text you can read first:

url=https://raw.githubusercontent.com/guyshonshon
curl -fsSL $url/vibestrate/main/install.sh | sh

To pin or check a version:

npm view vibestrate versions     # what is published
npm install -g vibestrate@<version>
vibe --version

vibe ui runs from inside a git repository - a run forks a branch. If the folder isn’t a repo yet, git init and one commit is enough.

More > Setup counts Status, Failures, Warnings and Checks run across the top, then walks six numbered steps: a repository, Initialise the project, Connect a model (with a Providers button), Point it at your tests (with Edit config), everything else doctor checks, and Start your first run, which unlocks once the project is initialised and nothing is failing.

Fix what’s safe appears when something can be repaired without a decision from you: missing directories, a missing skills README, an absent built-in role file. It fills in a provider or validation commands only where that part of the config is empty, never over what you wrote, and lists what it declined under Skipped.

vibe init            # scaffold .vibestrate/ (--git-init to create the repo too)
vibe setup           # the wizard, as questions in the terminal
vibe doctor          # the read-only report the Setup page renders
vibe doctor --fix    # the same repair pass as Fix what's safe
vibe doctor --json   # machine-readable, for CI

vibe setup is the closest thing to the Setup page without a browser: it asks rather than reports. It offers whichever of Claude Code, Codex or Ollama it finds as the project default, offers the validation commands it detected, and can take a custom provider’s command and args. It needs a git repository, and answers nothing on your behalf.

vibe on its own opens the interactive shell, whose Doctor page has r to re-run the checks and f to apply the safe fixes.

Alongside the four entries above, rules/ takes extra instruction files composed onto rules.md, skills/ takes markdown attachments that add domain context, flows/ holds this project’s Flows, and runs/ holds run state, artifacts, metrics and events.

policies/ is the one to watch: a rule file that fails to parse, or two claiming the same id, stops run creation outright rather than being skipped. vibe policies doctor names the file and the reason.

Add runs/ to your .gitignore yourself; nothing here touches that file:

.vibestrate/runs/

Connect a model → - Vibestrate spawns the coding CLIs you already have, so point it at one before you run anything.