VibeFrame

A control plane for agentic coding. VibeFrame maintains a living, in-repo model of what your software is supposed to be — business intent, system design, and the code itself — keeps it deterministically synchronized with reality, and shows you where they diverge.

Coding agents write code faster than anyone can read it. What evaporates is the theory: what exists, why it exists, which decisions are load-bearing, and whether the code still matches what was decided. VibeFrame captures that theory at the moment it is cheapest to capture (planning time, through the agent's own MCP protocol), stores it as plain files in your repo, verifies it mechanically forever, and pays the agent back with task-scoped context briefs that beat re-grepping the codebase.

• Three planes, one graph — capabilities & workflows (intent), components & constraints (system), files & symbols (code, 100% derived — never guessed).
• Trust tiers on every fact — A derived / B enriched / C asserted; staleness is visible, never silent.
• Drift detection with evidence — a live reflexion model: divergence, absence, broken bindings, orphans, cycles, locked-decision touches. Zero LLM calls; the framework is deterministic and the coding agent is the intelligence.
• In-repo model — .vibeframe/ YAML/Markdown versioned by git: branch-safe, PR-reviewable, survives any tool. A gitignored SQLite index is derived and rebuildable.
• One daemon per project — Streamable-HTTP MCP endpoint, REST + SSE, and a live browser UI (Map, Focus, Inspector, Activity, Drift inbox, Decisions) in a single process.
• Claude Code first — a plugin bundles the MCP server, deterministic hooks, and skills; the model also serves any agent through an AGENTS.md digest.

Install

npm i -D vibe-frame-cli

Node ≥ 22.12. This installs the vibeframe command and everything it needs. (Careful: the unhyphenated vibeframe on npm is an unrelated project — don't install that. Tarballs are also attached to each GitHub release if you prefer registry-free installs.)

Quickstart

npx vibeframe init                              # scaffold .vibeframe/ — commit it
claude mcp add vibeframe -- npx vibeframe mcp   # or install the Claude Code plugin (below)
npx vibeframe start                             # daemon + browser UI (prints the URL)

For the full Claude Code experience (MCP plus deterministic hooks and the /vibeframe:* commands), install the plugin from this repository inside Claude Code — /plugin marketplace add jubayertalha/vibeframe then /plugin install vibeframe — and skip the claude mcp add line above (the plugin brings the server).

Then ask your agent to plan a feature. It orients with one vibe_context call, declares the workflow before coding, binds implementations after — and everything it forgets, the deterministic layer catches: violations come back as same-turn warnings, unexplained changes queue for reconciliation, and the drift inbox shows exactly where reality left the plan, with file:line evidence. Full walkthrough: docs/getting-started.md.

Documentation

Getting started	install → first feature → the safety net
Architecture	the daemon, ground-truth asymmetry, package boundaries
The .vibeframe/ format	capabilities, workflows, components, constraints, decisions
Schema versioning	the three version domains and the migration contract
Validation & drift	every check, its gradations, and its documented false negatives
MCP interface	the seven vibe_* tools, resources, prompts
Claude Code integration	plugin, hooks, AGENTS.md digest
CLI · Browser UI	command and lens reference
Contributing · Security	working on VibeFrame; the trust model

Status

v0.1.0 — the complete loop on greenfield TypeScript/JavaScript/Python projects: init → declare → index → link → validate → reconcile, with the daemon, MCP tools, hooks, and the six-lens UI. Deferred by design (see the Discovery): other-agent adapters, brownfield adopt-mode, symbol-level call graphs, teams, anything hosted.

Development

npm ci && npm run build && npm run check   # lint + typecheck + unit tests
npm run test:dogfood                       # the full-loop acceptance suite

See docs/contributing/development.md and CLAUDE.md.

License

MIT