This page walks the product in the order you actually meet it — connect, scan, review, plan, build, explore — and for each step shows the mechanism (what triggers what) and the dashboard sections it lives on.
Two entry points drive everything. A GitHub webhook fires on pull request activity and queues review runs, and MCP calls from your own coding agent start plan reviews and feature runs. Both land findings in one place, and those findings are what move the Architecture Integrity Index on the Overview section.
Nothing below requires you to run VibeCop by hand after the first connection. Scans, reviews, and graph work are triggered by events, schedules, or your agent — the dashboard is where you read the result, approve a Feature Factory task graph when you are the one driving the run, and merge the pull requests VibeCop will never merge for you.
You authorize VibeCop against GitHub and pick a repository. That single authorization produces three separate things: a codebase record scoped to your organization and project, a webhook registered on the repository so future pull requests review themselves, and a quick scan that runs immediately with no model calls in it at all.
The quick scan walks the repository tree over GitHub's API and builds the file inventory everything else indexes against. It is deliberately cheap and deliberately shallow — it exists so the app has something true about your repository before any analysis is paid for. Webhook registration is treated as non-fatal: if GitHub refuses the hook, the connection still succeeds and you can scan on demand.
A repository can be actively connected in one project at a time. Trying to connect one that another project already owns is refused with the owning project named, rather than silently duplicated. Issue trackers are optional and can be connected later.
A scan runs over the whole repository tarball, not a diff, and splits into two lanes that never mix. The hygiene lane is deterministic and cheap: dependency CVEs queried live, secret detection, static analysis patterns, and infrastructure-as-code checks. The architectural lane runs the detector agents, which combine the code graph, embeddings, and model calls.
The first scan is also where the Stack Profile is produced — the detected languages, frameworks, and package manager that calibrate every detector from then on. A detector that does not know what kind of codebase it is reading cannot tell a convention from a deviation, which is why this comes before the architectural pass rather than after it.
Only the architectural lane can move your score. Each finding it produces carries an axis and a severity; findings are bucketed into the four axes and each axis is reduced from its 25 points by the severity weight of everything sitting in it. The Architecture Integrity Index is the sum of those four axis tiles, which is why the headline number and the tiles can never disagree.
Opening or updating a pull request fires the webhook VibeCop registered at connect time. The receiver verifies the request signature before trusting anything in it, then enqueues a review run. A background worker claims queued runs one at a time, executes the harness — the static layers plus the detector agents — and hands the result to a judge pass that synthesizes a narrative and a recommended action over the raw findings.
The run detail on the PRs section shows the findings, the judge's narrative, and the diff that produced them. When a run turns up critical findings, VibeCop also opens a rollup issue on the repository so the result reaches people who never open VibeCop. Runs that stall are reaped rather than left hanging, and each repository is capped at a bounded number of webhook-triggered runs per day so an unattended loop cannot run away.
One deliberate omission is worth knowing about. On a webhook-triggered run, VibeCop compares the head against the base and, if the diff touches no dependency manifest or lockfile, skips the dependency-CVE detector entirely rather than re-querying an unchanged dependency tree. The gate fails open: if the diff cannot be resolved, or the run was started any other way, the detector runs.
Every finding carries a severity from P1 to P4 and is either architectural — in which case it names one of the four axes — or hygiene. Severity is the only thing that determines how much a finding costs its axis. Resolving or dismissing it drops the finding out of the live axis tiles on Overview, which is where the points come back; the score written on the scan that found it is a historical record and stays as it was. You can act on one finding or on a batch, and you can either resolve it (fixed) or dismiss it with a reason (accepted) — a distinction that matters on the first scan of an older repository, where a whole class of finding is often a deliberate trade-off rather than a defect.
A background worker also writes a fix prompt for each finding — ready to paste into whichever coding agent you already use. Prompts are deduplicated by fingerprint, so a finding that recurs across runs reuses the prompt already generated for it rather than paying to write it again. The copy button never waits on that worker: until the generated prompt lands, it falls back to a deterministic one built from the finding itself.
VibeCop runs a Model Context Protocol server, so any MCP-capable agent — Claude Code, Cursor, Codex — can submit its implementation plan for review during planning. You mint a token in Settings, add the server to the agent's config, and the agent calls the check tool with its plan. The review is grounded in your project's real context: the Stack Profile, your architecture decision records, and your module layout.
Skills select how hard the review looks, and the agent names one on every call — there is no implicit default. The broadest, full-review, runs all twelve plan-check dimensions — reuse, architecture decisions, stack profile fit, impact, breaking changes, schema, simplicity, dependencies, security, utility inventory, layer map, and known-finding baseline. The narrower skills answer one of those questions for a cheaper mid-task check. Checks run in parallel, each with its own timeout under a shared budget, so a slow check degrades to a skip rather than stalling the review.
Every review returns a verdict — pass, warn, fail, or inconclusive — alongside its findings, recommendations, and an explicit coverage fraction of how many dimensions actually produced a result. Inconclusive is a real outcome, not an error: when too little of the plan resolved against your indexed code, VibeCop says so instead of scoring on thin evidence. Reviews are persisted, so the Plan Reviews section holds the history, and resubmitting an identical plan within a day returns the review already computed for it.
A feature run starts from your agent over MCP — there is no create button on the dashboard. You give it a title and a task list, where each task declares the files it expects to touch. VibeCop derives the dependency edges between those tasks from real evidence: overlapping footprints and import edges in the code graph. Tasks that are genuinely disjoint run in parallel, anything ambiguous is serialized rather than guessed, and a cyclic graph is rejected before anything is written.
The graph then stops at G1. It is a review checkpoint on the task graph — its jobs, footprints, and dependencies — and until it is approved, no node is dispatched. Approve it on the dashboard, or let the agent driving the run approve it over MCP when it holds authority over that run: G1 asks for a reviewer, not for a person in particular. Approving marks the root nodes ready and mirrors the run to GitHub as one tracking issue per node.
The builder is your own agent. VibeCop does not ship a hosted worker that writes code. The one adapter that works today is claim-based: an agent on your machine claims a ready node, receives a working branch and a time-boxed lease, builds it, and opens one pull request. Claims are leases and not locks, so an agent that goes quiet returns its node to the ready pool instead of stalling the run, and a sweep reclaims expired ones.
A node's pull request is reviewed like any other — the same detectors that guard your hand-written code guard the agent-written code. Node pull requests are exempt from the per-repository daily run cap, but not from the rest of the gate: a repository with auto-review switched off, an organization with no GitHub integration, or one with no spend headroom left gets no run. Then a human merges it. That merge is G2 — the one step in the whole product VibeCop has no API for — and it is the only thing that can mark a node done: node state is driven by GitHub webhook facts, never by an agent reporting its own success. A completed node unlocks its dependents, and when nothing is left the run settles.
Runs and nodes each end for a stated reason rather than just stopping. A run settles done only when every node merged — reason completed. Every other ending is cancelled, and the reason says which one: all_prs_closed when every node reached a terminal state but not all of them merged (the last open pull request closed unmerged, or a blocked cascade), operator_cancelled when you hit the kill switch, and ttl_swept when the run went quiet past its lifetime. A node that ends blocked names why — its pull request closed unmerged, or something upstream of it blocked first. Cancelling sweeps every non-completed node; work already merged stands.
There are two extractors writing two stores, and the difference matters when you are looking at a screen and wondering how fresh it is. Every scan runs an extractor over the source in-app and writes symbol nodes and typed edges — imports between files, and calls, extends, implements, instantiates, and references between symbols. That store is what the layers and modules views draw, and what the Health view summarizes as coupling, cycles, and architectural hubs — the files everything depends on, or that depend on everything.
The full-graph drill-in is a separate lane. A second extractor, in the Partikle substrate, downloads the repository at a resolved commit, extracts the whole graph, and stores a snapshot keyed to that commit; the canvas then reads an assembled snapshot rather than the scan-time store. It runs on demand from Load full graph, and is also kicked automatically the first time a codebase is scanned, or when a manual or scheduled scan lands on a commit the snapshot does not cover.
Both extractors tag every edge with how confidently it was resolved, and both drop an edge whose symbol name matches more than one candidate rather than silently attributing it to one of them, so a finding never rests on an invented relationship. A third lens, the topology view, sits alongside them: built by its own detector agent, it shows deployable units, databases, and external services rather than symbols.
The graph is not only a picture. Six of the nine architectural detectors read it as evidence, and it is what grounds Feature Factory dependency edges in step 6.
The Ask bar is present across the authenticated app. A question fans out concurrently to seven retrieval sources — your project hierarchy, workspace aggregates, recent scans, your knowledge base, extracted facts, conversation memory, and the code graph — each under its own timeout, all beneath one shared budget. Because they run concurrently the wall clock is the slowest source, not their sum. Whatever returns is assembled in a fixed order into a single context block that the model treats as ground truth.
One property is worth stating plainly, because it is the difference between a useful answer and a confident wrong one: the aggregates source is the only one carrying exact counts, and it renders under a header that says so and states whether those totals are scoped to one project or to the whole organization. Every other section is a capped sample, and the assistant is instructed to treat it as one — never to count the entries in a sample and report the result as a total. Sources degrade independently — an empty source and a failed source are recorded differently, so a quiet answer has a diagnosable cause.
Put the eight steps together and the shape is simple: two entry points in, three surfaces out. The GitHub webhook carries pull request activity — opens, syncs, and the merges that drive Feature Factory node states. MCP carries everything your coding agent initiates: plan checks and feature runs. A quieter third input, schedules and manual triggers, keeps scans and graph extraction current between events.
What comes out lands in three places. Findings and the Architecture Integrity Index on Overview, the structural views on Graph and Health, and the two agent-facing histories on Plan Reviews and Features. The Tasks section is the activity feed underneath all of it — what ran, when, and against which project.