🫀 Pulse (pulse-agent)

AI-powered Code Review & DevOps from your terminal — Security, Performance, and Quality agents on every PR.

Pulse brings autonomous multi-agent code reviews directly to your terminal and development workflow. Powered by LangGraph, Pulse coordinates specialized AI agents that review pull requests or local git diffs in parallel, test fixes inside an isolated Docker sandbox, and stream real-time findings to an interactive web dashboard.

✨ Features

• 🔍 Parallel Multi-Agent Reviews — Specialized Security, Performance, and Code Quality agents analyze your diffs concurrently.
• ⚡ Zero-Configuration Setup — Runs pulse start in any repository. Automatically creates and caches a Python 3.11+ virtual environment (.pulse/.venv/) with zero manual virtualenv management.
• 🔧 Automated Docker Repair — Generates and verifies patch fixes inside an isolated Docker container before suggesting them.
• 🌐 Real-Time Interactive Dashboard — Live Next.js UI (http://localhost:3000) showing agent stream thinking, severity filtering, and one-click patch application.

🚀 Quickstart

1. Install Globally

npm install -g pulse-agent

Prerequisites: Requires Node.js 18+ and Python 3.11+ installed on your machine.

2. Initialize in Any Project

Navigate to any Git repository on your computer and run:

cd /path/to/your-repo
pulse init

The setup wizard will:

• Ask for your LLM provider (Anthropic, OpenAI, or Groq) and securely store your API key
• Optionally configure your GitHub token for remote PR reviews
• Create a .pulse/config.json file in your project root
• Automatically add .pulse/ to your .gitignore

3. Start Pulse

pulse start

This launches both the Python Orchestrator API (http://localhost:8000) and the Interactive Web Dashboard (http://localhost:3000) in the background.

🛠️ CLI Reference (pulse)

| Command | Description | |---|---| | pulse init | Interactive setup wizard to configure API keys for the current project | | pulse start | Boot the Pulse orchestrator (:8000) and dashboard (:3000) | | pulse review | Trigger a review on your local staged/unstaged git diff | | pulse review --pr owner/repo#123 | Review a remote GitHub Pull Request | | pulse status | Display a health check table of all Pulse components | | pulse stop | Gracefully shut down running Pulse background processes |

🌐 Interactive Dashboard

When Pulse is running (pulse start), open your browser to http://localhost:3000:

• Live Agent Pipeline: Watch Security, Performance, and Quality agents stream findings via Socket.io.
• Severity & File Filtering: Filter reviews by Critical, Warning, and Info, or inspect exact file/line recommendations.
• Interactive Patch Review: Inspect diffs generated by the Docker Repair sandbox and apply them to your working tree.

🏗️ Under the Hood

Your Project Repo/
  ├── .pulse/
  │     ├── config.json       # API keys & preferences
  │     ├── .venv/            # Auto-managed Python environment
  │     └── .pid.json         # Background process tracking
  └── ...your codebase

1. Self-Contained Packaging: The CLI package bundles the Python backend and Next.js frontend directly inside the npm package.
2. Hash-Cached Venv: When pulse start runs, it detects Python 3.11+, configures a virtual environment inside .pulse/, and installs requirements using hash-based caching to skip redundant installs.
3. LangGraph Orchestration: Reviews are routed through specialized LangGraph nodes for concurrent security, performance, and code quality evaluation.

📦 Publishing to npm

To publish or update this package on npm:

cd packages/cli
npm publish

The prepublishOnly script automatically runs npm run prepare-bundle to bundle the latest orchestrator and pre-built dashboard into the package before uploading.