zendev-sentinel 0.1.1

Self-healing multi-agent code quality pipeline

SENTINEL

Self-healing AI code review pipeline

19 agents. 5 swarms. Runs on every PR. Free.

---

sentinel scan --path ./my-project --all

┌────────────────────────────────── Summary ──────────────────────────────────┐
│  Risk level        LOW  (0.25)                                              │
│  Files reviewed    2                                                        │
│  Findings          7                                                        │
│  Bugs found        3                                                        │
│  Auto-fixes        2    ← applied automatically                             │
│  Pending fixes     1    ← needs human review                                │
└─────────────────────────────────────────────────────────────────────────────┘

---

Quick start

pip install zendev-sentinel
sentinel init          # saves API keys to ~/.sentinel/.env
sentinel github-setup  # wires up your GitHub webhook
sentinel serve         # start listening for PRs

Two free API keys required — takes ~2 minutes, no credit card:

• Groq → console.groq.com
• HuggingFace → huggingface.co/settings/tokens

---

What it does

🔍 Review swarm — 5 agents fire in parallel on every PR

Agent	Checks
Security	Injection, auth flaws, weak crypto, SSRF, XSS, eval(), hardcoded secrets
Performance	N+1 queries, unbounded queries, blocking async, O(n²), missing memoization
Style	Naming, bare excepts, mutable defaults, magic numbers, function length
Architecture	Layering violations, circular deps, god classes, tight coupling
Lead reviewer	De-duplicates and re-prioritises all findings by severity

🧪 Test swarm — writes and runs tests against your changes

• Generates unit tests per changed file (happy path + edge cases)
• Runs them in an isolated Docker sandbox — network_mode=none, non-root, memory-capped
• Parses coverage output and surfaces gaps below 80%
• Writes integration tests when multiple modules interact (medium/high risk only)

Supports Python (pytest) and TypeScript / JavaScript (jest + ts-jest).

🐛 Bug squad — reproduces, traces, and fixes failures automatically

Failing test
    │
    ▼
Reproduce  →  strip to minimal repro script
    │
    ▼
Root cause  →  identify source file + line, form hypothesis
    │
    ▼
Fix proposer  →  draft 1–3 candidate patches (unified diff)
    │
    ▼
Verifier  →  apply each patch in sandbox, pick the first green one
    │
    ▼
AUTO_MERGE or HUMAN_REQUIRED

🧠 Self-healing knowledge base — gets smarter with every review

ChromaDB + SBERT power a local vector store. Every finding and fix is stored and recalled on future PRs — so agents learn your codebase's patterns over time.

Four maintenance agents run on a schedule:

Agent	Schedule	What it does
Curator	Nightly 02:00 UTC	Removes stale, reverted, and repeatedly-rejected entries
Drift-checker	Nightly 02:15 UTC	Archives entries whose code has since changed
Consistency	Weekly Sunday 03:00 UTC	Resolves contradictions between KB entries
Consolidation	Weekly Sunday 03:30 UTC	Merges near-duplicate entries into patterns

No cloud. No data leaves your machine.

🔐 Trust layer — every fix is explained and gated

• Explainability agent — attaches a plain-English rationale to every finding and fix
• Approval gate — classifies patches as AUTO_MERGE or HUMAN_REQUIRED

Files matching auth, payment, billing, secret, credential, password, token, admin, or migrations always route to HUMAN_REQUIRED — never auto-patched.

---

Pipeline

PR opened / pushed
        │
        ▼
   Risk scorer  ──→  score 0.0–1.0
        │
    ┌───┴───────────────────────────────────────┐
    │ low risk          │ medium / high risk     │
    │ lightweight pass  │ full swarm             │
    └───────────────────┴───────────────────────┘
        │
        ▼
  ┌─────────────────────────────────────────────┐
  │  PARALLEL                                   │
  │  Review swarm      Test swarm               │
  │  ├── Security      ├── Module tests         │
  │  ├── Performance   ├── Coverage analysis    │
  │  ├── Style         └── Integration tests    │
  │  ├── Architecture                           │
  │  └── Lead reviewer                          │
  └─────────────────────────────────────────────┘
        │
        ▼  (on test failures)
  Bug squad  →  Reproduce → Root cause → Fix → Verify
        │
        ▼
  Trust layer  →  Explain → Gate → Post PR comment

---

Commands

Command	What it does
sentinel init	First-time setup wizard — saves keys to ~/.sentinel/.env
sentinel github-setup	Generates webhook secret, walks through GitHub App creation
sentinel scan --path . --all	Scan a local directory (no PR needed)
sentinel run --repo owner/repo --pr 42	Run against a specific GitHub PR
sentinel serve	Start webhook server on port 8000
sentinel maintain	Run KB maintenance agents manually

More scan options

sentinel scan --path . --staged      # staged git changes only
sentinel scan --path . --branch main # diff vs a branch
sentinel scan --path . --all --output report.md  # save to file

---

LLM providers

Set LLM_PROVIDER in ~/.sentinel/.env:

Provider	Cost	Notes
cascade	Free	Groq → HuggingFace fallback. Recommended.
groq	Free	Groq only
huggingface	Free	HuggingFace only
ollama	Free	Local GPU, no API key, no quota
anthropic	Paid	Highest quality

---

Supported languages

Language	Review	Sandbox	Auto-fix
Python	✓	✓ pytest	✓
TypeScript / JavaScript	✓	✓ jest + ts-jest	✓
JSX / TSX	✓	✓ jest + ts-jest	✓

---

Security

• Sandbox: network_mode=none, non-root uid 1000, memory + CPU hard limits
• Webhooks: HMAC-SHA256 verified before any payload is parsed
• Sensitive paths: auth / payment / migrations always require human approval
• Secrets: stored in ~/.sentinel/.env — never committed to version control
• Pre-scan: regex secret detection on every diff before any LLM call

---

Self-hosted (team use)

Run on a shared server with Ollama — no API keys, no quota:

ollama pull qwen2.5-coder:7b
LLM_PROVIDER=ollama sentinel serve

Or with Docker Compose:

docker compose -f docker/docker-compose.yml up -d

---

License

AGPL-3.0 — free to use and self-host. If you offer SENTINEL as a hosted service, your full stack must be open-sourced under the same license.