VibeFlow User Guide

VibeFlow is a local-first CLI (vf) that opens a web UI and orchestrates Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, and Antigravity CLI (agy) through shared context, Anthropic-style skills, hooks, and verification. It never lets an engine work blindly: it scans your repo, resolves the skills a task needs on demand, plans non-overlapping work units, dispatches them in parallel, and refuses to “complete” anything without recorded evidence.

This guide is verifiable end to end — every section ends with a command whose output you can check.

1. Install

npx @magicpro97/vibeflow            # run without installing
npm install -g @magicpro97/vibeflow # or install globally, then use `vf`

Requirements: Node ≥ 18 and git. Engines (Claude Code / Codex / Copilot CLI / OpenCode / Antigravity agy) are optional — VibeFlow detects what you have and degrades gracefully. Context7 discovery needs no extra install (it rides the built-in fetch); an optional CONTEXT7_API_KEY raises the rate limit.

Verify:

vf doctor            # presence/auth check
vf doctor --probe    # also run a live "reply READY" round-trip per engine
vf doctor --refresh  # discard the probe-result cache and re-probe immediately

You should see ✓/• marks for node, git, bun, claude, codex, copilot, agy, docker, plus an “Engine readiness” block. With --probe each engine is launched once with a trivial prompt and must reply READY — proving auth and a working CLI end to end.

2. Mental model

intake + scan  →  resolve skill NEEDS  →  plan work units  →  dispatch (parallel)
                                                                   ↓
                       goal-eval  ←  verify gates  ←  reviewer  ←  evidence

Orchestrator — the main agent. Plans, splits, judges. Never writes code itself.
Work unit — a scoped slice of the task (.vibeflow/workunits/<name>/) with its own gates, evidence, and resource counters. Scopes must not overlap so units run in parallel.
Skill — an Anthropic skill-creator folder (SKILL.md + optional scripts/, references/). VibeFlow discovers, validates, and matches skills; the engine runs them. Nothing is pre-installed — skills are acquired on demand and start unverified.
Confidence gate — any decision below 1.0 triggers bounded investigation/debate; no merge or close on a guess.

3. The web UI (recommended)

vf            # or: vf ui

Opens http://127.0.0.1:<port> (loopback only). The dashboard has:

New workflow — repository path (with Detect), goal, engines, doc/task sources, file types, sample attachments, and the Definition of Done. Click Generate workflow.
Resource meter — units done, tokens, estimated cost, elapsed time (live via SSE).
Triage banner — any blocked unit is surfaced at the top, before everything else.
Dispatch — pick an engine, Write dispatch prompt, or Orchestrate (dry) to plan + dispatch work units (browser orchestration is always dry — it never shells out).
Work units — a board you can add/edit/delete; each card shows status, the build/lint/test/review gate strip, confidence, resources, and recorded evidence.
Skills — locally discovered skills and the demand-driven NEEDS (satisfied vs. must acquire).
Discovery — Context7 docs/skill lookup. The network is only touched after you tick approve network.

Security: the server binds to 127.0.0.1, every write carries a per-process CSRF token, the Host/Origin must be loopback, uploads are sanitized and size-capped, and the page ships no third-party JavaScript under a strict CSP.

Typed evidence

Each work unit’s recorded evidence is classified and rendered by type:

File (path or path:line) — shown as a 📄 click-to-open link. Clicking fetches the file through a token-guarded, loopback-only route that is sandboxed to the repo root: .. traversal, absolute paths, ~, and symlinks escaping the repo are all rejected, files over 256 KB and binaries are refused, and the content is always returned as JSON and rendered as inert text (never executed).
Command ($ …, vf …, bun …, npm …, git …) — shown with a $ badge.
Test (12 pass, 3 fail, acceptance tails) — shown with a ✓/✗ badge.
Text — anything else falls back to plain monospace.

Status timeline

Each unit records an append-only transition ledger at ~/.vibeflow/markers/<unit>.timeline.jsonl — one JSONL line per status change, derived from vf’s own marker updates (status, timestamp, confidence, evidence count). Expand a work unit’s row and the ledger is surfaced beneath its evidence as an ordered list — a status dot, the status, and a relative timestamp (2m ago), oldest first. The read route is token-guarded and loopback-only, and the unit name is sanitized (no /, \, .., or NUL); a fresh unit with no transitions yet simply shows nothing.

4. The CLI

Generate context

vf init                       # scan repo + generate canonical context for all engines
vf init --engine claude       # only Claude Code files
vf init --interactive         # ask the intake questions in the terminal
vf init --memory              # force the claude-mem install (skip the prompt)
vf init --no-memory           # skip the claude-mem install (skip the prompt)
vf init --dry-run             # show what would be written
# per-role agent files are written alongside the engine files when a per-role
# renderer is available (see src/agents/render.ts); see AGENT_ORCHESTRATION_POLICY.md

On a TTY, vf init asks whether to install claude-mem so engines can recall past specs and decisions (Install claude-mem for spec/plan recall? (Y/n), default yes). On yes it installs claude-mem and appends a usage guide to WORKFLOW_POLICY.md. The answer is saved to settings.memory; toggle it later with vf config memory <mode> (a read-only vf config memory status prints the current state). --memory / --no-memory skip the prompt.

Memory modes (default: false / off):

Mode	What it does
`off` / `false`	No recall — nothing injected into prompts (default)
`builtin`	Zero-config BM25/FTS5 recall from `.vibeflow/knowledge/decisions.md` via `bun:sqlite`; lazy-indexed on mtime; generates `.vibeflow/knowledge/memory.db` (gitignored)
`claude-mem`	Shells `claude-mem search`; requires `claude-mem` installed separately

Enable builtin recall:

vf config memory builtin

Enable claude-mem (external):

vf config memory claude-mem   # requires: npm i -g claude-mem (or vf init --memory)

Disable:

vf config memory off

vf init --ai runs the AI enrichment phase on top of the deterministic context. The chosen engine is the first ready one in priority order (claude > copilot > codex > opencode > antigravity), unless --engine is set.

vf init --ai                                # auto-pick the best engine
vf init --ai --engine copilot              # force a specific engine
vf init --ai --autopilot                   # fall back to next-best if engine fails
vf init --ai --engine copilot --autopilot  # ask for copilot, fall back to claude/codex if it errors

--autopilot retries with the next-best ready engine when the chosen engine is unavailable or returns a permission error. Capped at 3 fallbacks; never retries the same engine twice. Off by default — the single-shot failure mode is preserved unless you opt in. See docs/COVERAGE.md for the full reference.

init scans the repo (README, manifests, lockfiles, CI) and writes .vibeflow/* plus the engine files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md). It runs a live readiness probe first and refuses to create a workflow when no engine is ready — engines that fail the probe are skipped, files are written only for ready ones (--dry-run skips the gate). Verify:

cat .vibeflow/PROJECT_CONTEXT.md     # contains a "## Detected stack" section

Resolve which skills a task needs (demand-driven)

vf skills list           # skills discovered under .vibeflow/.claude/.agents/.github skills dirs
vf skills search xlsx    # rank local skills against a term
vf skills resolve        # derive NEEDS from the scan + intake; show satisfied vs missing
vf skills validate       # validate every canonical skill against the Anthropic standard
vf skills sync           # regenerate engine mirrors from .vibeflow/skills/ (default: pointer)
vf skills verify-sync    # check each mirror has a SKILL.md for every canonical skill

Example vf skills resolve output:

• xlsx-reader  (attachment data.xlsx) — missing — vf discover skills xlsx --yes
• Next.js docs (detected framework Next.js) — missing — vf discover docs Next.js --yes

Discover external docs/skills (approval-gated)

vf discover docs next.js          # prints "approval required"
vf discover docs next.js --yes    # Context7 HTTP lookup; imports are experimental
vf discover skills pdf --yes

Discovery uses the Context7 HTTP API via the built-in fetch (no ctx7 binary), only reaches the network with --yes, and fails gracefully when offline.

vf tools status                  # what's enabled/installed + the priority ladder
vf tools install codegraph --yes # run the install plan (prints it without --yes)
vf tools enable codegraph        # wire it into each engine's MCP config
vf tools disable lsp             # turn off + remove its MCP servers

Two opt-in tools (both off by default) give engines better code navigation: codegraph (a local code-graph MCP server) and lsp (an MCP↔language-server bridge, one server per detected language). Enabling a tool flips it in .vibeflow/SETTINGS.json and wires MCP config per engine — it merges .mcp.json for Claude, writes .codex/config.toml (with disabled_tools gating) for Codex, and prints copilot mcp add commands for you to run. The preference order codegraph > lsp > native is injected into the engine instruction files. Re-run vf init after changing tools to regenerate them.

Dispatch and orchestrate

vf run claude                 # write .vibeflow/dispatch/claude.md (dry)
vf run claude --yes           # launch the Claude Code CLI

vf orchestrate                # plan + dispatch work units (dry: prompts only)
vf orchestrate --engine codex --concurrency 4
vf orchestrate --yes          # real dispatch through the engine CLI

orchestrate dispatches every work unit through a bounded parallel pool, runs an independent reviewer (a unit only passes at confidence 1.0 with evidence), then the orchestrator-only goal-eval prints met | partial | blocked.

Inspect the ledger

vf units status               # board: status, gates, owner, confidence
vf units show <name>          # one unit as JSON
vf units resources            # token / cost / wall-time totals
vf units evidence <name>      # recorded evidence paths

Verify (hard gates)

vf verify

Runs typecheck/lint/test when your package.json declares them, plus the policy gates: confidence < 1 fails, a done unit with no evidence fails, and overlapping work-unit scopes fail.

Hooks (guardrails)

vf hooks status               # show git path + live guardrail status
vf hooks install              # install fail-closed pre-commit + pre-push gates
vf hooks emit                 # write engine configs plus managed git hooks
echo '{"event":"pre-command","command":"rm -rf /"}' | vf hook   # → {"decision":"block",...}

All engine hook configs delegate to one entrypoint — vf hook — which scores risk and returns allow | warn | require_approval | block.

.githooks/pre-push runs current-HEAD verification with local review evidence. It fails closed with repair guidance, but docs-only/no-checklist ranges need no reviewer record. No network or LLM runs inside it. git push --no-verify bypasses local feedback only; remote review-thread-gate remains authoritative. User-owned hooks are preserved.

5. End-to-end walkthrough (verifiable)

mkdir demo && cd demo && git init -q
printf '{"name":"demo","scripts":{"build":"tsc","test":"echo ok"},"dependencies":{"express":"^4"}}' > package.json
printf '# Demo\n\nA tiny service.\n' > README.md

vf init --engine claude          # → PROJECT_CONTEXT.md shows Express + npm + build
vf skills resolve                # → Express docs need (acquire on demand)
vf orchestrate                   # → 1 unit dispatched (dry); goal: partial (confidence 0)
vf units status                  # → the unit with its gate strip
vf verify                        # → fails the confidence gate (no completion on a guess)

Every step prints evidence you can check. The goal only reaches met when each unit is done at confidence 1.0 with recorded evidence — which is exactly the point.

6. Generated files

CLAUDE.md AGENTS.md .github/copilot-instructions.md   # engine instruction files
.vibeflow/PROJECT_CONTEXT.md REQUIREMENTS.md TASK_CONTEXT.md
.vibeflow/WORKFLOW_POLICY.md SKILL_INDEX.md WORKFLOW_STATE.json
.vibeflow/SETTINGS.json                                 # per-repo tool settings
.vibeflow/dispatch/<engine>.md                          # vf run
.vibeflow/workunits/<name>/CONTEXT.md + <engine>.result.json   # vf orchestrate
.vibeflow/attachments/                                  # uploaded sample files

Minimal-footprint principle: VibeFlow generates the fewest files needed, composed from canonical context. Work units and skills appear only when a task actually needs them.

7. Troubleshooting

“No workflow. Run vf init first.” — you ran orchestrate/units before init.
vf discover says approval required — re-run with --yes; network is never silent.
vf discover failed / offline — Context7 runs over HTTP; check connectivity. Set CONTEXT7_API_KEY to raise the rate limit (keyless works but is throttled).
An engine CLI isn’t launched on vf run — install it; vf doctor shows what’s missing.
vf verify fails on confidence — raise the unit to 1.0 with evidence, or keep investigating; this is the anti-hallucination gate working as designed.