CodeGuardian is an Engineering Intelligence Control Plane that understands and manages the continuous evolution of software across repositories, branches, commits, PRs, CI failures, releases, regressions, and autonomous Guardian agents.
CodeGuardian maintains a persistent model of repositories, branches, pull requests, tests, incidents and prior repairs. It detects change collisions, traces defects through engineering history, compares symptom patches against root-cause repairs, and compiles only the code evidence required for reasoning.
Coding assistants are optimized primarily around generating and reviewing code within a task. CodeGuardian focuses on the engineering system surrounding those tasks: persistent change history, branch interactions, causal repair depth, proactive risk detection, and context-efficient reasoning across long-lived repositories.
Continuous Engineering Events (Pushes, Commits, PRs, CI Runs)
↓
Codebase Pulse Temporal Topology
↓
Local Deterministic Change & AST Indexing
↓
Context Compiler (AST Neighborhood + Token Budget)
↓
Causal Repair Engine (Band-Aid vs Root-Cause Depth)
↓
Persistent Guardian Network (Observe / Prepare)
↓
Constrained Process Sandbox Verification (Zero Docker)
↓
Git Action Center (Never Auto-Merges)
A Git-aware temporal topology visualization rendered in interactive SVG. Branches are horizontal tracks, branch creation forms forks, merges converge, and small semantic markers highlight commits, pull requests, CI passes/failures, Guardian investigations, regressions, and release milestones.
Clicking any event (such as PR #184) opens the contextual Event Inspector slide-over detailing affected architecture symbols (TokenValidator, SessionManager), changed files, risk scores, and Guardian assessments without requiring terminal Git commands.
For every defect or regression, CodeGuardian evaluates four conceptual repair levels instead of blindly offering the smallest diff:
- Band-Aid: Symptom suppression (e.g. catch exception in controller; low change risk, but underlying race condition remains).
- Local Fix: Input validation before method invocation (local scope protection).
- Root Cause (Recommended): Correct originating defect in state transitions; removes defect across all downstream paths without scope bloat.
- Architectural: Broad subsystem refactoring (strongest long-term architecture, but excessive scope for current incident).
CodeGuardian computes a deterministic Causal Repair Score before LLM invocation:
CodeGuardian recommends the smallest repair that eliminates the actual root cause, not merely the smallest diff.
The LLM never searches the repository from scratch. CodeGuardian uses incremental SHA-256 file hashing to reparse only changed files, compute affected AST neighborhoods, extract test coverage, and assemble a compact Context Packet:
Measured across 5 realistic architectural queries targeting CodeGuardian itself (benchmarks/context_efficiency_large.py):
| Metric | Baseline Naive Retrieval | CodeGuardian Context Compiler | Impact |
|---|---|---|---|
| Files Inspected (Mean) | 8.0 files | 2.8 files | 65.0% reduction |
| Input Tokens (Mean) | 6,008 tokens | 754.6 tokens | 87.44% context reduction |
| Tool Calls (Mean) | 16 calls | 1 compilation pass | 93.8% reduction |
| Relevant-File Recall | 100% | 100% | Complete architectural recall |
| Compilation Latency (Mean) | — | 437.9 ms | Sub-second AST resolution |
Summary: Median Context Reduction 87.52%, Min 82.7%, Max 90.8%, Relevant-File Recall 100.0%.
Measured against localized repository fixtures (benchmarks/context_efficiency.py):
| Metric | Baseline Search Retrieval | CodeGuardian Context Compiler | Impact |
|---|---|---|---|
| Files Read | 7 files | 1 file | 85.7% reduction |
| Input Tokens | 1,241 tokens | 312 tokens | 74.9% context reduction |
| Tool Calls | 14 calls | 1 call | 92.9% reduction |
| Relevant Recall | 100% | 100% | Lossless precision |
| Compilation Latency | — | 0.88 ms | Real-time local execution |
Measured values from local AST parsing and token estimation. No fabricated savings.
Users can assign long-lived autonomous Guardian agents to specific repositories, branches, components, or workflows:
- Autonomy Levels:
OBSERVE: Read/analyze only.RECOMMEND: Proactively produces findings, root-cause hypotheses, repair strategies, and test plans.PREPARE: Additionally creates isolated repair workspaces, generates patches, runs tests in the sandbox, and prepares draft PRs.
- Guardrails: Guardians never auto-merge, never force-push, and require human confirmation for external GitHub operations.
- Event-Driven: Subprocess Git hooks trigger deterministic AST impact filters first; LLMs are only invoked when risk thresholds are exceeded.
The Engineering Inbox aggregates high-signal engineering intelligence requiring attention—regressions, CI failures with prepared repairs, and cross-branch divergence:
CodeGuardian's Change Collision Detector inspects active branches and identifies shared architectural dependencies (e.g. feature/auth-v2 and payments both diverging on SessionManager) before Git merge conflicts occur.
Perform common Git operations visually without terminal commands. When a patch is verified in the sandbox, users can trigger:
- Create Branch: Isolates fix into branch based on main.
- Commit: Structured commit messages with file diff summaries.
- Push: Strictly blocks direct pushes to protected default branches; refuses
--force. - Open Pull Request: Automatically drafts PR with Root Cause, Verification Evidence, and Risk Assessment. Never auto-merges.
A single conversational interface that automatically delegates to relevant Guardians:
- Screenshot Intake
[📎]: Extracts visible clues (UI text, routes, stack traces, HTTP codes) and maps them deterministically to components (CheckoutButton.tsx86%), hooks (useCheckout.ts91%), and endpoints (POST /api/checkout94%). - Central Delegation: Subtly indicates "Consulting Auth Guardian & Payment Guardian — 2 Guardians analyzed 3 branches and 2 open PRs".
CodeGuardian executes repository commands using strictly isolated temporary workspaces and constrained subprocesses:
Original Repository (Untouched)
↓
Create isolated temporary working copy (.codeguardian/runs/<task_id>/repo)
↓
Validate workspace path (Canonical resolve & traversal prevention)
↓
Sanitize environment variables (Strip API keys, tokens, and DB credentials)
↓
Run approved command as subprocess (shell=False, argument array)
↓
Enforce timeout + resource limits (Process group session via os.setsid)
↓
Capture stdout/stderr/exit code & redact sensitive secrets
↓
Kill process group if timeout occurs (SIGTERM → SIGKILL)
↓
Collect test/build results & generate Git diff
↓
Delete temporary workspace when finished
Benchmark Evaluation — Deterministic Sandbox & Hidden Verification
CodeGuardian includes a controlled benchmark suite of 10 diverse software engineering defect tasks evaluated against independent hidden verification suites:
Note
Evaluation Methodology: This benchmark measures the fidelity of CodeGuardian's Constrained Local Process Sandbox and verification harness. For each task, the harness populates an isolated temporary repository workspace, reproduces the failure via subprocess execution (pytest), applies the patch candidate within the sandbox, runs targeted tests, and verifies correctness against an independent hidden verification test that validates boundary edge cases without training data leakage.
This is a deterministic sandbox isolation and verification suite; open-ended LLM code synthesis can be evaluated on live models when external API credentials are provided.
| Task ID | Defect Category | Name | Initial Failure | Targeted Test | Hidden Test | Result |
|---|---|---|---|---|---|---|
task-01 |
API Robustness | Missing Exception Handling (500 → 404) | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-02 |
Boundary Defects | Off-by-One Pagination | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-03 |
Input Validation | Email Validation Regex | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-04 |
Data Filtering | Incorrect Active Record Filtering | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-05 |
Type & Null Safety | Null String Sanitization | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-06 |
Data Transformation | Cents to Dollars Conversion | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-07 |
API Contracts | API Envelope Structure | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-08 |
Arithmetic & Logic | Discount Calculation | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-09 |
Edge Cases | Empty List Median Edge Case | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
task-10 |
Regression Defects | Cache Key Type Differentiation | ✓ Repro | ✓ Passed | ✓ Passed | RESOLVED |
- Tasks Attempted: 10
- Tasks Resolved: 10 / 10 (100.0%)
- Targeted Test Success: 10 / 10 (100.0%)
- Patch Application Rate: 10 / 10 (100.0%)
- Hidden Verification Rate: 10 / 10 (100.0%)
- Average Repair Attempts: 1.0
- Total Measured Runtime: 10.45s
- Execution Cost: $0.00 (Local constrained subprocess execution)
CodeGuardian is built with a clear privacy boundary:
- Local Analysis: Repository indexing, AST dependency graph construction, Git history processing, repair execution in the constrained sandbox, and context compilation run 100% locally on your machine.
- Model Modes:
- Local Mode (Default): When using local models (e.g., via Ollama), zero source code leaves this machine.
- Remote Provider Mode: When configured with OpenAI, Anthropic, or Groq API keys, only the compiled, minimal evidence packets (typically ≤ 4k–8k tokens) are dispatched for reasoning.
- Python: 3.11 or higher
- Node.js: 18 or higher
- pnpm: 9 or higher
- Git: Installed and available in PATH
git clone https://github.com/PRAFULREDDYM/CodeGuardian.git
cd CodeGuardian./scripts/dev.shThis starts:
- FastAPI Backend: http://127.0.0.1:8000
- Next.js Web UI: http://localhost:3000
# Backend pytest suite (26 tests)
PYTHONPATH=apps/api pytest apps/api/tests/ -v
# Frontend Vitest suite (10 tests)
cd apps/web && pnpm test -- --runpython3.11 benchmarks/context_efficiency.pyCodeGuardian/
├── apps/
│ ├── api/ # FastAPI Backend & Engineering Intelligence Core
│ │ ├── app/
│ │ │ ├── agent/ # 12-stage LangGraph autonomous workflow
│ │ │ ├── causal_repair/ # 4-tier defect depth analysis & causal scoring
│ │ │ ├── context_compiler/# AST change indexing & token budgeting
│ │ │ ├── git/ # Safe subprocess git log, diff, branch, commit, push
│ │ │ ├── github/ # GitHub REST client & PR draft generator
│ │ │ ├── guardians/ # Guardian network manager, collision & pre-merge analysis
│ │ │ ├── screenshots/ # Visual clue extraction & symbol mapper
│ │ │ ├── repo_intelligence/ # Python AST & Tree-sitter parser, NetworkX graph
│ │ │ ├── routes/ # Repositories, Pulse, Inbox, Guardians, Context, Repair, Git
│ │ │ └── sandbox/ # Constrained Process Sandbox (Zero Docker)
│ │ ├── tests/ # Backend test suite (workflow, control plane, sandbox security)
│ │ └── requirements.txt
│ │
│ └── web/ # Next.js Web Application
│ ├── src/
│ │ ├── app/ # App router (/, /pulse, /inbox, /repositories, /guardians, /settings)
│ │ ├── components/ # UI components:
│ │ │ ├── pulse/ # CodebasePulse, PulseBranch, PulseEvent, EventInspector, PulseLegend
│ │ │ ├── repair/ # CausalRepairPanel
│ │ │ ├── git/ # GitActionCenter
│ │ │ └── AppHeader, Sidebar, TaskComposer, ConversationView, ContextSlideOver, ContextualDrawer
│ │ └── __tests__/ # Frontend test suite
│ └── package.json
│
├── benchmarks/ # Benchmark evaluation suite
│ ├── context_efficiency.py # Real repository context compilation benchmark
│ ├── context_efficiency_results.json # Verified context reduction telemetry (74.9%)
│ ├── suite.py # 10 defect definitions with hidden tests
│ └── evaluate.py # Benchmark execution runner
│
├── docs/
│ ├── security.md # Threat model & sandbox security breakdown
│ └── screenshots/ # Interface screenshots (01–14)
│
├── scripts/
│ ├── dev.sh # One-command development runner
│ ├── test.sh # One-command test suite runner
│ └── benchmark.sh # Benchmark suite executor
│
├── .github/workflows/ci.yml # GitHub Actions CI workflow
├── LICENSE # Apache 2.0
└── README.md
Distributed under the Apache 2.0 License. See LICENSE for more information.