@openverb/pulse

AI-friendly project log that automatically updates with builds, tests, and errors.

Features

• 📝 Auto-logging: Wrap any command to automatically log results
• 🚀 Runtime Error Capture: Automatically capture errors from dev servers
• 🧠 Project Brain: Machine-readable openverb-pulse.json for AI tools
• 🔍 Codebase Analysis: Automatically analyzes your project to extract:
  • Real tech stack from package.json
  • Features from route structure
  • Project purpose from main entry point
  • Intent and vision from codebase
• ✅ Task Extraction: High-severity errors automatically become actionable tasks
• 🌐 Browser viewable: HTML files work in editors and browsers
• 🤖 AI-ready: Structured JSON embedded for easy parsing
• 🔗 OpenVerb integration: Optional link to sync with OpenVerb cloud

Installation

npm install -D @openverb/pulse

Quick Start

1. Initialize

npx ov-pulse init --name "My Project"

This creates .ov-pulse.json and .ai/openverb-pulse.html

2. Wrap Commands

# Instead of: npm run build
npx ov-pulse exec -- npm run build

# Instead of: pnpm test
npx ov-pulse exec -- pnpm test

3. Capture Runtime Errors

# Start dev server with error capture
npx ov-pulse dev -- next dev
# or
npx ov-pulse dev -- vite

Automatically captures React errors, route failures, console errors, and more.

4. View Log

# View permanent project brain
npx ov-pulse view

# View current session errors
npx ov-pulse view --session

Opens .ai/openverb-pulse.html in your browser.

Usage

Dev Server Proxy (Runtime Error Capture)

Capture runtime errors from your dev server:

npx ov-pulse dev -- next dev
npx ov-pulse dev -- vite
npx ov-pulse dev -- npm run dev

What gets captured:

• React hydration errors
• Route/page errors
• Console errors and warnings
• Network/API errors
• Compilation errors
• Unhandled exceptions

Errors are automatically recorded to openverb-pulse.json and session errors.

Note: Only actual errors (4xx/5xx status codes) are captured. Successful requests (200) are ignored.

Exec Command

Execute any command and automatically log the result:

ov-pulse exec -- <your-command>

Examples:

ov-pulse exec -- next build
ov-pulse exec -- pnpm test
ov-pulse exec -- vercel --prod

Snapshot Command

Create a snapshot of current project state:

npx ov-pulse snapshot

Captures:

• Git branch and commit
• Project structure (entrypoints, routes)
• Build/runtime status
• Updates openverb-pulse.json

Dev Command

Start dev server with runtime error capture:

npx ov-pulse dev -- <command>

See Dev Server Proxy above for details.

Enrich Command (Coming Soon)

Enrich openverb-pulse.json with AI analysis:

npx ov-pulse enrich

This will use a local LLM to add:

• Diagnosis hypotheses
• Proposed fixes
• Impact severity
• Task grouping

View Command

Open the pulse log in your browser:

ov-pulse view
ov-pulse view --session  # View session errors

Generate Command

Regenerate the HTML and JSON files:

ov-pulse generate

Output Files

openverb-pulse.json

Machine-readable project brain in JSON format:

{
  "schema_version": "1.0.0",
  "project": { ... },
  "snapshot": { ... },
  "events": [ ... ],
  "open_tasks": [ ... ],
  "notes": [ ... ]
}

This file can be consumed by AI tools (ChatGPT, Claude, Cursor, etc.) to understand your project without manual explanation.

Location: .ai/openverb-pulse.json

openverb-pulse.html

Human-readable project brain with visual timeline.

Location: .ai/openverb-pulse.html

session-errors.json & session-errors.html

Ephemeral errors from current development session.

Location: .ai/session-errors.json and .ai/session-errors.html

Integration with package.json

Add scripts to your package.json:

{
  "scripts": {
    "dev": "ov-pulse dev -- next dev",
    "build": "ov-pulse exec -- next build",
    "test": "ov-pulse exec -- pnpm vitest",
    "deploy": "ov-pulse exec -- vercel --prod",
    "pulse:view": "ov-pulse view",
    "pulse:snapshot": "ov-pulse snapshot"
  }
}

Configuration

Edit .ov-pulse.json:

{
  "projectName": "My Project",
  "projectId": "optional-project-id",
  "visualMode": "none",
  "sync": {
    "enabled": false,
    "endpoint": null,
    "apiKeyEnv": null
  },
  "outputFile": ".ai/openverb-pulse.html"
}

How It Works

1. Command Execution: ov-pulse exec runs your command and captures output
2. Runtime Capture: ov-pulse dev proxies your dev server and captures runtime errors
3. Event Logging: Results are saved to .ai/openverb-pulse.json and session errors
4. HTML Generation: .ai/openverb-pulse.html is generated with:
   • Human-readable event list
   • Embedded JSON for AI/tool parsing
   • "Continue in OpenVerb" link

AI Integration

For ChatGPT/Claude (browser)

1. Run ov-pulse view to open the log
2. Copy relevant event snippets or the entire openverb-pulse.json
3. Paste into chat

For Cursor/VS Code AI

The AI can read .ai/openverb-pulse.json or .ai/openverb-pulse.html directly as files in your repo.

For AI with Browsing

Use the "Continue in OpenVerb" link to view logs on the web, then share the URL.

File Structure

.ai/
  ├── openverb-pulse.json     # Machine-readable project brain (unified format)
  ├── openverb-pulse.html     # Browser-viewable log
  ├── session-errors.json     # Ephemeral errors
  └── session-errors.html     # Session errors viewer
.ov-pulse.json                 # Configuration

License

MIT