deadpush 0.2.3

Guardrails for the vibe coding era — real-time AI agent guardian with MCP write interception, git hooks, and quarantine

deadpush

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.

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

# 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):

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

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

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

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 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:

./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.