# VibeFrame

[![CI](https://github.com/jubayertalha/vibeframe/actions/workflows/ci.yml/badge.svg)](https://github.com/jubayertalha/vibeframe/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/vibe-frame-cli.svg?label=npm%20vibe-frame-cli)](https://www.npmjs.com/package/vibe-frame-cli)
[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](LICENSE)

**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

```bash
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](https://github.com/jubayertalha/vibeframe/releases)
if you prefer registry-free installs.)

## Quickstart

```bash
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](docs/getting-started.md).

## Documentation

| | |
| --- | --- |
| [Getting started](docs/getting-started.md) | install → first feature → the safety net |
| [Architecture](docs/architecture.md) | the daemon, ground-truth asymmetry, package boundaries |
| [The `.vibeframe/` format](docs/format/model.md) | capabilities, workflows, components, constraints, decisions |
| [Schema versioning](docs/format/schema-versioning.md) | the three version domains and the migration contract |
| [Validation & drift](docs/validation.md) | every check, its gradations, and its documented false negatives |
| [MCP interface](docs/mcp.md) | the seven `vibe_*` tools, resources, prompts |
| [Claude Code integration](docs/claude-code.md) | plugin, hooks, AGENTS.md digest |
| [CLI](docs/cli.md) · [Browser UI](docs/ui.md) | command and lens reference |
| [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) | 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

```bash
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](docs/contributing/development.md) and
[CLAUDE.md](CLAUDE.md).

## License

[MIT](LICENSE)