Open source · for vibe coders · Next.js

Your agent says it built it. This proves it.

Your AI agent keeps a tiny YAML map of the app it's building — pages, APIs, tasks, env, systems. vibehud renders that map as a live panel and validates it against your real routes, so the map can't silently lie.

How it works ↓

› one file your agent keeps honest — renderedvalidatedpingedrememberedshipped

no install · just paste
Paste this to your agent cursor · claude code · lovable · bolt · replit 
Set up vibehud in this project, then keep it updated.

1. npm install vibehud
2. Add transpilePackages: ['vibehud'] to next.config.
3. Create app/vibehud/page.tsx:
     import { VibehudPage } from 'vibehud/next'
     export const dynamic = 'force-dynamic'
     export default function Page() { return <VibehudPage /> }
4. Create agent-map.md at the repo root describing THIS
   app — yaml block with pages, apis, systems, env NAMES
   (never values), tasks.
   Spec: node_modules/vibehud/spec/FORMAT.md
5. Copy node_modules/vibehud/templates/AGENTS.md into my
   agent instructions (AGENTS.md / CLAUDE.md / .cursor/rules)
   so every future session updates the map in the same turn
   as any change.

Then tell me to open /vibehud.
your agent does the rest · panel is dev-only
What it is · declared, then verified

A render layer for agent state — with a lie detector.

Not a code visualizer. Not a diagram generator. Your agent declares what it's building in one markdown file; vibehud draws it and checks the declarations against the filesystem. Three parts:

01 The file

One agent-map.md at your repo root. Prose for humans, a YAML block for machines. The agent updates it in the same turn as every change.


      

      

        
02 The panel

        
A drop-in React page at /vibehud, dev-only. Page map, API lane, systems,
           env chips, kanban — auto-refreshing every 2 seconds while the agent works.

        

          live · auto-refresh
          

            Shoplyagent-map.mdupdated 2s ago
          

          

            ⚠ map drift1 missing · pinged live
            ✓ map verified8 pages · 8 on disk
          

          
Pages

          

            
Home/

            
Wishlist/wishlist · missing

          

          
API routes

          

            
GET/api/products

          

          

            
TO DO
Build wishlist page

            
DOING
Build wishlist page

            
DONE
Build wishlist page

          

          

        

      

      

        
03 The validator

        
Declared pages vs. real routes. Declared APIs vs. real handlers — pinged live.
           Declared env names vs. .env.example and what's actually set. Drift is one glance.

        

          
⚠ MAP DRIFT — declares 6 · 7 on disk

          
missing: /wishlist · undeclared: /account, /orders

        

      

    

  






  

    How to use it · one prompt or four steps
    
You don't install it. Your agent does.

    
The prompt at the top does all of this for you —
      your agent wires everything up. Doing it by hand is four steps:


    

      

        01
        

          
Install the package

          

            
npm install vibehud

            
          

          
One dependency (yaml). Ships as source; React 18+.

        

      

      

        02
        

          
Let Next transpile it

          
// next.config.mjs
export default {
  transpilePackages: ['vibehud'],
}

          
Next.js app directory is the one supported framework at launch.

        

      

      

        03
        

          
Mount the panel

          
// app/vibehud/page.tsx
import { VibehudPage } from 'vibehud/next'

export const dynamic = 'force-dynamic'
export default function Page() {
  return <VibehudPage />
}

          
Renders nothing in production unless you explicitly enable it.

        

      

      

        04
        

          
Teach your agent

          
# AGENTS.md (shipped template)
Update agent-map.md in the same turn as:
- new/renamed/deleted routes → pages
- new API handlers → apis + methods
- new env NAMES (never values) → env
- work started/finished → tasks

          
Copy the shipped AGENTS.md into your repo. That's the persistence trick —
             every future session re-reads it and keeps the map fresh.

        

      

    


    

      Why the file matters: the map lives in git, next to your code. Every commit that touches
      it becomes a history entry in the panel — and when it drifts, one click copies a fix-prompt
      you paste straight back to your agent.
    

  






  

    Features · one yaml block drives it all
    
Everything the panel watches for you.

    
All of it dev-only by default, all of it driven by one YAML block.

    

      
Drift badge
Declared vs. real — pages and APIs. Missing and undeclared routes, named.

      
API lane + methods
route.ts handlers scanned, GET/POST/… extracted from exports.

      
Health pings
Each declared API is pinged live. Responding, 5xx, 404, unreachable.

      
Env check
Names vs. .env.example vs. what's actually set. Values never leave the server.

      
History strip
Git-powered recap: pages added, tasks done, drift introduced or fixed.

      
Detail drawer
Click any node: what it's made of, its connections, its tasks, its notes.

      
Focus + filter
Type to filter; select to dim everything but a node and its neighbors.

      
Copy fix prompt
Drift found → one click copies the exact instruction to hand your agent.