PULSE Framework – Controlled AI-Assisted Development

# PULSE Framework – Controlled AI-Assisted Development

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CLI Version](https://img.shields.io/badge/CLI-v0.4.6-blue.svg)](packages/pulse-cli)
[![MCP Version](https://img.shields.io/badge/MCP-v0.5.0-blue.svg)](packages/pulse-mcp)
[![Website](https://img.shields.io/badge/Website-manuel--fuss.de-green)](https://manuel-fuss.de/pulse)

**PULSE** is a complete toolkit for controlled AI-assisted software development: methodology, CLI commands, MCP server for Cursor IDE, automatic safeguards, and loop detection.

```bash
# Quick Start
npm install && npm run build
npm link -w packages/pulse-cli -w packages/pulse-mcp

cd your-project
pulse init --mcp    # Initialize with Cursor integration
```

> **Target Audience:** Senior Developers and Tech Leads who want structured, safe AI-assisted development.

---

## ⚡ Before vs After

<p align="center">
  <img src="assets/diagrams/comparison-before-after.png" width="800" alt="Before vs After PULSE" />
</p>

---

## 🔄 The Workflow

<p align="center">
  <img src="assets/workflow/pulse-workflow-animated.gif" width="800" alt="PULSE Workflow Animation" />
</p>

**Status** → **Run** → **Build** → **Doctor** → **Checkpoint** → *repeat*

---

## 🛡️ The 5 Safeguards

<p align="center">
  <img src="assets/workflow/safeguards-animated.gif" width="650" alt="PULSE Safeguards" />
</p>

---

## 🎬 Extension Features

### ⏱️ Always-On Status Bar Timer

<p align="center">
  <img src="assets/demos/statusbar-timer.gif" width="800" alt="Pulse status bar timer" />
</p>

- **Visual checkpoint reminder** – See exactly how long since your last commit
- **Color-coded warnings** – Green → Yellow → Red as time passes
- **One-click access** – Click to open checkpoint menu instantly

---

### 🚀 One-Click Project Setup

<p align="center">
  <img src="assets/demos/auto-setup-fullstack.gif" width="500" alt="One-click setup" />
</p>

- **Auto-detection** – Pulse recognizes uninitialized projects automatically
- **Fullstack preset** – Sensible defaults for most projects
- **Zero config** – MCP server, Git hooks, and Cursor rules installed in one click

---

### 💾 Smart Checkpoint (AI-Generated Commits)

<p align="center">
  <img src="assets/demos/smart-checkpoint.gif" width="600" alt="Smart checkpoint" />
</p>

- **Context-aware** – The AI generates commit messages from your chat history
- **No copy-paste** – Zero friction between coding and committing
- **Git best practices** – Meaningful, structured commit messages every time

---

### ⏸️ Snooze & Stop Watcher

<p align="center">
  <img src="assets/demos/snooze-stop-watcher.gif" width="600" alt="Snooze and stop watcher" />
</p>

- **Non-intrusive reminders** – Only notifies when you have uncommitted changes
- **Snooze 1 hour** – Take a break without spam
- **Stop Watcher** – Disable completely when you need deep focus

---

**If Pulse helps your workflow, please ⭐ Star the Repository.**

---

## 💻 CLI Commands

### `pulse status` – Check Project State

<p align="center">
  <img src="assets/cli/pulse-status.png" width="650" alt="pulse status" />
</p>

---

### `pulse doctor` – Scan for Red Flags

<p align="center">
  <img src="assets/cli/pulse-doctor.png" width="650" alt="pulse doctor" />
</p>

---

### `pulse doctor` – Warning Example (Secrets + Mass Delete)

<p align="center">
  <img src="assets/cli/pulse-doctor-warning.png" width="650" alt="pulse doctor warning" />
</p>

---

### `pulse run` – Start New Feature

<p align="center">
  <img src="assets/cli/pulse-run.png" width="650" alt="pulse run" />
</p>

---

### `pulse checkpoint` – Save Progress

<p align="center">
  <img src="assets/cli/pulse-checkpoint.png" width="650" alt="pulse checkpoint" />
</p>

---

### `pulse doctor --loop` – Detect Fix-Loops

<p align="center">
  <img src="assets/cli/pulse-loop.png" width="650" alt="pulse loop detection" />
</p>

---

## 🤖 Agent Mode (MCP Tools)

The AI agent automatically calls PULSE tools during your conversation. Here's what it looks like:

### 📊 Status Check (Before Every Response)

<p align="center">
  <img src="assets/mcp/mcp-status-clean.png" width="700" alt="pulse_status clean" />
</p>

- **Automatic** – Agent calls `pulse_status` before every response
- **Checkpoint tracking** – Shows time since last commit
- **Scope awareness** – Tracks files and lines changed

---

### ⚠️ Checkpoint Overdue Warning

<p align="center">
  <img src="assets/mcp/mcp-status-overdue.png" width="700" alt="pulse_status overdue" />
</p>

- **30-minute rule** – Stops the agent when checkpoint is overdue
- **Protects your work** – Forces a save before continuing
- **Clear action** – Agent creates checkpoint automatically

---

### 🔑 Secret Detection

<p align="center">
  <img src="assets/mcp/mcp-doctor-secret.png" width="700" alt="pulse_doctor secret" />
</p>

- **Pre-commit scan** – Catches API keys before they leak
- **Blocks commit** – Won't let you push secr

... (truncated)