Metadata-Version: 2.4
Name: deadpush
Version: 0.2.2
Summary: Guardrails for the vibe coding era — real-time AI agent guardian with MCP write interception, git hooks, and quarantine
Project-URL: Homepage, https://github.com/harris-ahmad/deadpush
Project-URL: Source, https://github.com/harris-ahmad/deadpush
Project-URL: Bug Tracker, https://github.com/harris-ahmad/deadpush/issues
Project-URL: Documentation, https://github.com/harris-ahmad/deadpush#readme
Author-email: Harris Ahmad <harris@deadpush.dev>
License: MIT
License-File: LICENSE
Keywords: ai-coding,git-hook,guardrails,llm,mcp,quarantine,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: pathspec>=0.12.1
Requires-Dist: watchdog>=4.0.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.45.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rich>=13.7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: watchdog>=4.0.0; extra == 'dev'
Provides-Extra: rich
Requires-Dist: rich>=13.7.0; extra == 'rich'
Description-Content-Type: text/markdown

# deadpush

[![GitHub stars](https://img.shields.io/github/stars/harris-ahmad/deadpush?style=social)](https://github.com/harris-ahmad/deadpush)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Your personal AI Agent Guardian.**  
Protects you from the mistakes, secrets, and context pollution that AI coding agents (Claude, Cursor, Windsurf, etc.) inevitably create — even when you're not watching.

Run it once with `deadpush protect --daemon` and it runs in the background forever, monitoring your filesystem in real time.

---

## The Problem (2026 AI Coding Reality)

You tell your agent to "add the new feature" and walk away.

30 minutes later you come back to:
- A `claude.md` or `.cursorrules` file committed to the repo
- Hardcoded API keys in `.env` files the agent "helpfully" created
- 47 new "temporary" scripts and scratchpads
- LLM context files like `CLAUDE.md` or `agents.md` committed to the repo

**deadpush** is the always-on guardian that catches this the moment it happens.

## One Command. Real Protection.

```bash
pip install deadpush
deadpush protect --daemon
```

That's it.

It will:
- Install a smart pre-push git hook
- Merge AI-specific ignore patterns into `.cursorignore`, `.claudeignore`, and `.gitignore`
- Start a persistent background process that watches your entire repo
- Automatically quarantine dangerous files the second they appear
- Track a **Safety Score** that reacts intelligently when multiple agents are going wild

While you're at the gym, in a meeting, or sleeping, deadpush is on duty.

## See It In Action

```bash
# After running protect --daemon, try simulating an agent:
mkdir -p .deadpush-e2e-sandbox
touch .deadpush-e2e-sandbox/claude.md
echo 'OPENAI_API_KEY=sk-...' > .deadpush-e2e-sandbox/.env.bad

deadpush status
deadpush quarantine list
```

You'll see the guardian react, drop the Safety Score, and quarantine the files.

For a full automated demo of guardian features (burst simulation, hooks, MCP):

```bash
python scripts/full_e2e_test.py --simulate-agent --burst
```

## Key Features

- **True background guardian** — Survives terminal close, supports systemd/launchd autostart
- **Smart multi-agent Safety Score** — Penalizes bursts of dangerous activity from parallel agents
- **Automatic quarantine** (never hard-delete) — Easy `deadpush quarantine list` / `restore`
- **Local Control Interface for agents** — Your AI coding agents can query the guardian themselves (`GET /status`, `/quarantine-list`, etc. on localhost)
- **Cross-platform git hooks** — Pre-commit, post-commit, and pre-push guardrails
- **Debris detection** — LLM context files, vibe scratchpads, hardcoded secrets

## Commands You'll Actually Use

```bash
deadpush protect --daemon     # The one command you run per repo
deadpush status               # Is the guardian alive? What's the Safety Score?
deadpush quarantine list      # See what it caught
deadpush doctor               # Health check (hooks, MCP, guardian)
deadpush mcp                  # MCP server for AI agents (guardrailed writes)
```

## Why This Matters in the AI Era

AI agents are incredible productivity multipliers.

They are also incredibly good at creating technical debt, leaking secrets, and polluting your context — especially when you give them long-running tasks and step away.

deadpush is the missing safety net.

## Installation

```bash
pip install deadpush
```

Then run `deadpush protect --daemon` in any repo you care about.

## Windows Users

The pre-push hook ships as a Python script + `.cmd` shim. It works from PowerShell, Command Prompt, and Git Bash. The `deadpush protect` command records the exact Python interpreter so everything works even inside virtualenvs.

## Development

```bash
git clone https://github.com/harris-ahmad/deadpush
cd deadpush
./scripts/dev_install.sh
```

On macOS, use `dev_install.sh` instead of bare `pip install -e .` — see [CONTRIBUTING.md](CONTRIBUTING.md) if imports fail outside the repo.

### Validating hardened mode

Hardened mode's guarantees (privilege separation, an agent-unkillable daemon,
root-immutable `schg` hooks, repo ACLs, real-time quarantine, hook self-heal, and
a clean teardown) require root and a real service manager, so CI can't verify
them. Run the end-to-end QA harness manually on a clean machine or VM:

```bash
./scripts/hardened_qa.sh
```

It provisions a throwaway repo, runs `deadpush protect --hardened`, asserts every
guarantee against live system state, then uninstalls and verifies nothing is left
behind. Run it as your normal user (not root); it escalates with `sudo` only where
needed. It refuses to run if a `_deadpush` account already exists, so it can't
disturb a real hardened install (pass `--allow-existing` to override, `--keep` to
skip teardown for inspection).

## Architecture

deadpush is a closed-loop guardian with four cooperating layers:

### 1. Intercept Layer (`deadpush/intercept.py`)
The real-time guardrail engine. Every file write is checked via `enforce_content()`:
- **Security guardrails**: `eval`, `subprocess`, pickle deserialization, SQL injection patterns
- **Secret detection**: Hardcoded API keys, tokens, passwords (with **path-aware lowering** in test/mock files)
- **Prompt injection**: AI prompt manipulation patterns
- **Destructive change detection**: Near-empty rewrites, >50% line reduction
- **Sensitive config protection**: CI/CD, deployment, Docker files
- **Layer violations**: Architecture import rules
- **Debris detection**: LLM context files, scratchpads, secrets

**Learned false positive suppression**: Adjudicated false positives persist to `.deadpush/learned_patterns.json` and auto-suppress on future checks.

### 2. Guardian Daemon (`deadpush/guard.py`)
Filesystem watcher that quarantines dangerous writes, maintains the Safety Score, and exposes a local control API for agents.

### 3. Git Hooks (`deadpush/hooks.py`)
Pre-commit, post-commit, and pre-push hooks all call the same `enforce_content()` kernel — no bypass between MCP, daemon, and git.

### 4. MCP Server (`deadpush/mcp_server.py`)
Stdio MCP server exposing guardian tools: `write_file`, `check_file`, `verify_write`, quarantine management, feedback loops, and danger-gated config tools.

### Data Flow

```
Agent writes file (MCP write_file or native editor)
       ↓
enforce_content() — same kernel for MCP, hooks, and guardian
       ↓
Approved?  →  Blocked → Quarantine + Feedback + Safety Score drop
  Yes
       ↓
verify_write (optional) → Run tests → Pass? → Write
                                              Fail → Quarantine + Restore from git
       ↓
git commit → pre-commit hook → post-commit hook
git push   → pre-push hook (server-side GitHub Action available)
```

## Philosophy

Set it and forget it.

The best guardian is one you forget exists — until the moment it saves you from your own agent.

---

**Star the repo** if you think every developer running AI coding agents in 2026 should have this running in the background.

For the complete source and architecture, see the implementation notes in the repo.
