VibeFlow

The local-first orchestrator for AI coding agents.
Drive Claude Code, Codex, GitHub Copilot CLI, OpenCode & Antigravity CLI with a confidence gate, source protection, and verified completion.

🌐 Website · 📚 Wiki · 📖 Docs · 📦 npm · 🎬 Demo

Purpose

VibeFlow is a local-first npm CLI tool that opens a visual web UI and helps users run AI-assisted software development workflows using Claude Code, Codex CLI, and GitHub Copilot CLI out-of-the-box.

The tool acts as the main orchestrator. It collects task context, reads project sources, selects skills, generates tool-specific instruction files, dispatches AI coding engines, verifies results, and continuously improves local skills based on lessons learned.

On a fresh clone, arm the guardrail before any human edit:

./scripts/guardrail-on.sh

See issue #162 (orchestrator-first / F1) for the full rationale.

Recommended name and command

Product name: VibeFlow

Recommended npm package and command:

npx @magicpro97/vibeflow

After global install:

npm install -g @magicpro97/vibeflow
vf

vf is the short command for day-to-day use.

Install and use

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

vf                # open the local web UI — intake wizard + live dashboard
vf doctor         # check required and optional tools (--probe for a live engine round-trip)
vf init           # scan repo + generate canonical context + engine files (--engine, --no-ask, --dry-run)
vf run claude     # dispatch one engine: claude | codex | copilot | opencode | antigravity (--yes to launch)
vf ask src/x.ts:10-20 "what does this do?"   # inline code Q&A (--engine, --resume)
vf orchestrate    # plan + dispatch work units in parallel, review, goal-eval (--engine, --yes, --concurrency)
vf units status   # work-unit board: status, gates, owner, confidence
vf skills list    # skills: list | search | resolve | sync | draft | crystallize | curator scan | registry
vf tools status   # optional code-nav tools (status | enable | disable | install <tool>)
vf discover docs <lib> --yes   # Context7 docs/skills lookup (network requires approval)
vf verify         # typecheck / lint / test + confidence / evidence / scope gates
vf hooks emit     # write per-engine hook configs (--yes; `install` wires core.hooksPath)
vf eval           # passive success-rate gate over dogfood telemetry (--min-pass-rate)
vf pr merge-when-green   # poll CI and merge on green (queue + auto-merge)
vf state brief    # durable cross-session coordinator brief

The web UI is where you initialize a workflow: fill in goal, engines, doc/task sources, file types, and expected result, then Generate workflow (writes the canonical context + engine files) and Write dispatch prompt for the chosen engine. Prefer the terminal? Use vf init --interactive for the same questions, or vf init for a non-interactive scaffold.

Using VibeFlow as a skill

vf init seeds a vf skill into your repo and syncs it to Claude Code, Codex, GitHub Copilot, OpenCode, and Antigravity — one cross-engine skill, no per-tool wiring.

npx @magicpro97/vibeflow init   # seed the `vf` skill + sync to every engine
vf skills resolve               # inspect / search / resolve demand-driven skills

Activate it inside any supported CLI tool:

• Type <your task> + vf in a prompt to pull the VibeFlow workflow into the request.
• Type /vf in a CLI tool (Claude Code / Codex / Copilot / OpenCode) to run the skill directly.
• Run /vf with no args and it grills you toward a spec from the chat context.

See the Skills system wiki page for the full reference.

Develop

Built with Bun + TypeScript, one runtime dependency (proper-lockfile for file locking; otherwise Node stdlib only, so the published CLI runs anywhere node does). The web UI applies the taste-skill design read with a small inline motion layer (no third-party CDN script, since the page is same-origin with the write API).

bun install       # install dev tooling and set up git hooks (core.hooksPath)
bun run dev       # run the CLI from source (src/cli.ts)
bun run check     # typecheck + lint + test
bun run build     # bundle to dist/cli.js (Node-compatible, with shebang)

A v* git tag triggers the npm publish workflow (requires the NPM_TOKEN secret).

Core idea

The system should not let an AI coding engine operate blindly. Instead, it should build a structured workflow:

User prompt
  ↓
Main Orchestrator Agent
  ↓
Questionnaire / Context Intake
  ↓
Source + Skill Resolution
  ↓
Repository + Document Analysis
  ↓
Plan / Debate / Task Split
  ↓
Tool-specific adapter generation
  ↓
Claude Code / Codex / Copilot / OpenCode / Antigravity CLI execution
  ↓
Diff / log / test verification
  ↓
Skill evolution proposal

Main goals

• Provide one npm command to start a local web UI.
• Support Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, and Antigravity CLI.
• Generate CLAUDE.md, AGENTS.md, and Copilot instruction files automatically.
• Use Anthropic-style Skills based on SKILL.md.
• Manage a skill registry (git-backed, pinned) plus a curator that turns findings into reviewable proposals.
• Search trusted external skills/docs when local knowledge may be stale.
• Read project documents from sources such as GitHub, Jira, Google Drive, Confluence, Notion, local folders, and others.
• Process files such as Markdown, DOCX, XLSX, PPTX, PDF, OpenAPI, Postman, Mermaid, and Draw.io.
• Use hooks as guardrails across all supported engines.
• Avoid hallucination through evidence, verification, confidence thresholds, and reviewer agents.
• Generate the fewest files possible, all produced by AI from canonical context rather than static templates.
• Continuously improve internal skills from real execution lessons.

Repository layout

This repo is the @magicpro97/vibeflow tool itself. It is kept deliberately minimal — every file earns its place; the rest is generated on demand.

/
  package.json tsconfig.json biome.json   # toolchain config
  src/
    cli.ts core.ts commands.ts           # entry + command router
    commands/                             # one file per `vf` subcommand
    server/  server.ts                    # local web UI + API routes
    skills/                               # registry, resolver, sync, curator, validator
    hooks/                                # runner, risk, adapters, apply-gate
    orchestrator/                         # investigate, plan, run, agent, debate, marker
    plan-review/  eval/  logbus/  memory/ # review, telemetry, durable stream, recall
    dispatch/  preflight/  safety/        # engine dispatch, readiness, checkpoint/quota
    tools/  discovery/  workflow/         # codegraph/lsp, context7, lifecycle/merge
    ui/                                   # Vue web UI (workspace)
  test/       190+ test files
  docs/       *.md (the specification this tool implements)
  landing/    Astro marketing site + wiki (deployed to Firebase)
  .githooks/  pre-commit + pre-push (format-fix → typecheck → lint → test → build)
  .github/    copilot-instructions.md, workflows/{ci,release,deploy-landing,skill-curator}.yml

When run against a target project, vf init generates only what that engine/task needs (maximum surface shown below; the minimal-footprint principle keeps it lean):

CLAUDE.md                              # Claude Code
AGENTS.md                              # Codex + Copilot + OpenCode + Antigravity
.github/copilot-instructions.md        # Copilot
.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 (tools, toolPriority)
.vibeflow/dispatch/<engine>.md          # on `vf run`
.vibeflow/workunits/<name>/             # only when a task is decomposed

Documentation

📚 Full documentation index → — organized by the Diátaxis framework (Tutorials · How-to · Reference · Explanation), also browsable as a searchable wiki.

Quick links:

• User Guide — get started
• Command Reference — every vf command
• Architecture — how it works
• Security Model — guardrails & source protection

Star History

---

_{Powered by VibeFlow · MIT License}