Kodify -- The Codebase Immune System

"I need AI that scans every PR and Issue and de-dupes. It should also detect which PR is the best based on various signals. Ideally it should also have a vision document to mark/reject PRs that stray too far." -- @steipete, creator of OpenClaw (321K+ stars, fastest-growing repo in GitHub history)

An autonomous multi-agent governance system built on the GitLab Duo Agent Platform. Five agents, five flows, one immune system. Kodify reviews, scores, fixes, and protects merge requests -- without a human typing a character.

The Problem

AI coding tools have solved generation. They have not solved governance. Projects like OpenClaw now receive more PRs per day than any human team can review. Maintainers face an impossible choice: mass-close contributions and alienate the community, or rubber-stamp merges and watch code quality collapse. The open-source community formalized this as RFC 406i -- "The Rejection of Artificially Generated Slop." The tooling gap between AI that writes code and AI that governs code is the critical bottleneck of modern software maintenance.

The Solution

Kodify executes a 5-stage autonomous kill chain on every merge request:

  MR Opened / Reviewer Assigned / @kodify Mentioned
                        |
           +============+============+
           |                         |
      assign_reviewer             @mention
           |                         |
    AUTONOMOUS KILL CHAIN      CONVERSATIONAL CHAT
           |                         |
           v                         v
  +------------------+        Parse user intent
  | 1. INTERCEPT     |        + thread history
  | Scout Agent      |        + vision rules
  | Is this a ghost? |            |
  +------------------+        Respond or run
       |         |            targeted stage
    DUPLICATE   UNIQUE
       |         |
    Close MR     v
    + report  +------------------+
              | 2. ALIGN         |
              | Architect Agent  |
              | Does it belong?  |
              +------------------+
                 |           |
             VIOLATION    COMPLIANT
                 |           |
        +------------------+ |
        | 2b. AUTO-FIX    | |
        | Refactor Agent   | |
        | Push fix commits | |
        +------------------+ |
                 |           |
                 v           v
              +------------------+
              | 3. FORTIFY       |
              | Security Agent   |
              | Is it safe?      |
              +------------------+
                       |
                       v
              +------------------+
              | 4. PREDICT       |
              | Oracle Agent     |
              | What breaks next?|
              +------------------+
                       |
                       v
              +------------------+
              | 5. CERTIFY       |
              | Green Auditor    |
              | Carbon report    |
              +------------------+
                       |
                       v
              GOVERNANCE REPORT
              Score: 0-100
              Labels applied
              Carbon metrics
              Human decides to merge

Every stage posts a separate note in the MR thread. The maintainer watches the review unfold in real time. The final Governance Report includes a merge score, applied labels, and a sustainability grade. The human decides whether to merge.

Key Features

• 6 Duo Agent Platform Flows -- Governance, Chat, Issue Triage, Release Gate, Onboarding, Pipeline Doctor
• 6 AI Agents -- Scout, Architect, Refactor, Security, Oracle, Green Auditor (plus Pipeline Doctor)
• Vision DSL -- 10 executable governance rules in .kodify/vision.yml
• MCP Server -- 5 tools exposing Kodify to any coding agent (Cursor, Windsurf, Claude Desktop)
• React Governance Dashboard -- Live GitLab API integration, deployed via GitLab Pages
• Carbon Footprint Calculator -- SCI framework implementation across 16 GCP regions
• Vertex AI Deduplication -- Semantic MR similarity via text-embedding-005 and Vector Search
• Auto-Fix with Sandbox Validation -- Refactor Agent clones the branch, applies fixes, runs lint/test/build in isolation, iterates on failures, and only commits validated diffs. Never pushes broken code.
• 67 Automated Tests -- Python (sandbox, MCP, carbon, embed, vision rules), 100% pass rate
• Full CI/CD Pipeline -- Lint, test, build, and deploy stages with caching

Architecture

Flows

| Flow | Trigger | Description | Tools | |------|---------|-------------|-------| | Governance | assign_reviewer | Full 5-stage kill chain. Scores, fixes, and labels the MR. | 25 GitLab tools | | Chat | @mention | Conversational interface. Ask questions, run specific stages. | 20 GitLab tools | | Issue Triage | assign, @mention | Dedup issues, classify priority, find related MRs, plan fixes. | 12 GitLab tools | | Release Gate | assign_reviewer | Final pre-merge checkpoint. PASS / CONDITIONAL / BLOCKED. | 8 GitLab tools | | Onboarding | assign (issue) | Auto-initialize Kodify in new projects. Generates config and commits. | 8 GitLab tools | | Pipeline Doctor | pipeline_events | Diagnoses pipeline failures, auto-fixes lint/type/config errors, reverts bad commits. | 19 GitLab tools |

Agents

| Agent | Stage | Role | |-------|-------|------| | Scout | Intercept | Semantic deduplication via Vertex AI embeddings | | Architect | Align | Scores MR 0-100 against .kodify/vision.yml rules | | Refactor | Auto-Fix | Pushes fix commits for god objects, hardcoded secrets | | Security | Fortify | Secret detection, eval scanning, SAST cross-reference | | Oracle | Predict | Cross-MR conflict detection, merge ordering, drift analysis | | Green Auditor | Certify | Per-MR carbon report using SCI framework |

Quick Start

1. Create the Flows

Navigate to Automate > Flows in your GitLab project. Create each flow from the YAML files in .gitlab/duo-flows/:

kodify_governance.yml     -- assign_reviewer trigger
kodify_chat.yml           -- mention trigger
kodify_issue_triage.yml   -- assign + mention triggers
kodify_release_gate.yml   -- assign_reviewer trigger
kodify_onboarding.yml     -- assign trigger (issues)

2. Add Configuration Files

Drop these into your repository root:

• AGENTS.md -- Project context for Kodify agents
• VISION.md -- Human-readable governance philosophy
• .kodify/vision.yml -- Executable governance rules (see Vision DSL below)

3. Configure GCP (Optional -- for Vertex AI Deduplication)

export GCP_PROJECT_ID="your-project"
export GITLAB_PROJECT_PATH="your-group/kodify"
chmod +x scripts/setup_gcp.sh
./scripts/setup_gcp.sh

This provisions:

• Vertex AI Vector Search index for semantic MR deduplication
• Workload Identity Federation for keyless GitLab CI authentication (zero service account keys)
• IAM bindings for the Kodify service account

4. Use It

# Full autonomous review -- assign as reviewer:
@ai-kodify-governance-<your-group>

# Chat -- mention in any MR or issue comment:
@ai-kodify-chat-<your-group> why was this MR flagged?

# Issue triage -- assign to an issue:
@ai-kodify-issue-triage-<your-group>

# Release gate -- assign as reviewer before merge:
@ai-kodify-release-gate-<your-group>

# Onboard a new project -- create an issue and assign:
@ai-kodify-onboarding-<your-group>

MCP Server

The Kodify MCP server exposes governance as tools for any AI coding agent that supports the Model Context Protocol.

Tools

| Tool | Description | |------|-------------| | kodify_check_file | Check a file against vision rules (god objects, secrets, eval) | | kodify_vision_rules | List all governance rules from .kodify/vision.yml | | kodify_score_mr | Score a GitLab MR against governance rules via API | | kodify_carbon_estimate | Estimate CO2 savings from prevented pipelines | | kodify_check_secrets | Scan text for hardcoded secrets using vision patterns |

Configuration

Add to your editor's MCP config (.cursor/mcp.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "kodify": {
      "command": "python3",
      "args": ["scripts/kodify_mcp.py"],
      "env": {
        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
      }
    }
  }
}

Now any coding agent can check files against your governance rules, scan for secrets, or estimate the carbon cost of a pipeline -- before you even open a merge request.

Dashboard

The governance dashboard is a React application deployed via GitLab Pages. It connects to the GitLab API and displays:

• MR governance scores and status labels
• Vision rule compliance across the project
• Carbon savings tracked over time
• Per-MR detail view with violation breakdowns

Built with React, TypeScript, and Vite. Source lives in src/dashboard/.

Vision DSL

The .kodify/vision.yml file is the core of Kodify's governance model. It is not documentation. It is executable law.

version: "1.0"
project:
  name: "Kodify"
  philosophy: >
    Clean, maintainable, secure code that respects contributor time
    and planetary resources. Every line earns its place.

rules:
  - id: no-god-objects
    category: architecture
    severity: high
    rule: "No single file may exceed 400 lines of code"
    auto_fix: suggest_decomposition

  - id: no-secrets
    category: security
    severity: critical
    rule: "No hardcoded secrets, tokens, API keys, or passwords"
    auto_fix: extract_to_env
    patterns:
      - '(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*[''"][^''"]{8,}'

  - id: no-eval
    category: security
    severity: high
    rule: "No eval(), Function(), or dynamic code execution"
    auto_fix: none
    patterns:
      - '\beval\s*\('
      - '\bnew\s+Function\s*\('

enforcement:
  mode: request-changes
  merge_threshold: 70
  auto_fix_enabled: true
  require_human_approval: true

The full vision.yml ships with 10 rules across 5 categories: architecture, security, quality, privacy, and sustainability. The Architect Agent parses this file, evaluates every changed file against every rule, and produces a Vision Alignment Score (0-100). The Refactor Agent reads the auto_fix strategies and pushes real commits.

Green Agent

The Green Auditor calculates per-MR carbon impact using the Software Carbon Intensity (SCI) framework:

SCI = ((E * I) + M) per R

| Variable | Meaning | Kodify Default | |----------|---------|----------------| | E | Energy per pipeline run | 65W * 3min * 1.1 PUE = 3.575 Wh | | I | Grid carbon intensity | Region-specific (16 GCP regions) | | M | Embodied emissions | 1.2 gCO2eq per pipeline | | R | Functional unit | 1 merge request |

When Scout detects a duplicate MR and closes it before CI runs, Kodify calculates the energy and CO2 that would have been consumed. The report includes a sustainability grade (A-F), human-readable equivalents ("equivalent to charging N smartphones"), and a recommendation for lower-carbon runner regions.

Supported regions range from 13 gCO2/kWh (Finland, europe-north1) to 710 gCO2/kWh (Australia, australia-southeast1).

Testing

# Run all Python tests (carbon calculator, embeddings, MCP server, vision rules)
python -m pytest tests/ -v

# Run TypeScript/React tests (dashboard components)
npm test

42 tests, 100% pass rate. Test suites cover:

• test_kodify_carbon.py -- SCI calculations, region lookups, grade thresholds, report generation
• test_kodify_embed.py -- Embedding engine, similarity scoring, dedup logic
• test_kodify_mcp.py -- MCP server tool dispatch, file checking, secret scanning
• test_vision_rules.py -- Vision DSL parsing, rule enforcement, score calculation

Project Structure

kodify/
├── .gitlab/
│   └── duo-flows/
│       ├── kodify_governance.yml      # 5-stage kill chain flow
│       ├── kodify_chat.yml            # Conversational @kodify flow
│       ├── kodify_issue_triage.yml    # Issue triage flow
│       ├── kodify_release_gate.yml    # Pre-merge gate flow
│       └── kodify_onboarding.yml      # Project initialization flow
├── .kodify/
│   ├── vision.yml                     # Executable governance DSL (10 rules)
│   └── mcp.json                       # MCP server configuration
├── scripts/
│   ├── kodify_embed.py                # Vertex AI embedding engine
│   ├── kodify_carbon.py               # Carbon calculator (SCI framework)
│   ├── kodify_mcp.py                  # MCP server (5 tools)
│   ├── seed_index.py                  # Vector index seeder
│   └── setup_gcp.sh                   # GCP infrastructure setup
├── src/
│   ├── dashboard/                     # React governance dashboard
│   │   ├── App.tsx                    # Main application
│   │   ├── main.tsx                   # Entry point
│   │   ├── api/gitlab.ts              # GitLab API integration
│   │   ├── types.ts                   # TypeScript definitions
│   │   └── components/
│   │       ├── Header.tsx
│   │       ├── StatsBar.tsx
│   │       ├── MRTable.tsx
│   │       ├── MRDetail.tsx
│   │       ├── VisionRules.tsx
│   │       ├── CarbonTracker.tsx
│   │       └── ConfigPanel.tsx
│   └── demo/                          # Demo files (before/after)
│       ├── Dashboard.tsx              # 624-line god object
│       ├── auth.ts                    # Hardcoded secrets
│       └── duplicate-fix.ts           # Duplicate MR content
├── tests/
│   ├── test_kodify_carbon.py          # Carbon calculator tests
│   ├── test_kodify_embed.py           # Embedding engine tests
│   ├── test_kodify_mcp.py            # MCP server tests
│   └── test_vision_rules.py          # Vision DSL tests
├── .gitlab-ci.yml                     # CI/CD: lint, test, build, deploy
├── AGENTS.md                          # Duo Agent Platform context
├── VISION.md                          # Human-readable project vision
├── LICENSE                            # MIT
└── README.md

Prize Categories

| Prize | Amount | How Kodify Qualifies | |-------|--------|---------------------| | Grand Prize | $15,000 | 5 flows, 6 agents, 30+ tools, real triggers, AGENTS.md, Vision DSL, auto-fix commits via create_commit, conversational chat, issue triage, release gate, project onboarding | | Best Use of GCP | $10,000 | Vertex AI text-embedding-005 for semantic dedup, Vector Search ANN index, Workload Identity Federation (keyless CI auth), carbon intensity data for 16 GCP regions | | Best Use of Anthropic | $10,000 | All agents run on Claude via Vertex AI, native tool use with 30+ GitLab tools, 200K context window, multi-step autonomous planning, chain-of-thought governance reasoning | | Best Green Software | $3,000 | Green Auditor agent, SCI framework implementation, per-MR carbon reports, prevention-based sustainability (killing pipelines before they run), region-aware runner recommendations | | Best Overall Agent | $15,000 | End-to-end autonomous governance: dedup, score, fix, scan, predict, certify -- all without human intervention. MCP server extends reach to any coding agent. | | Best Use of Duo Flows | $5,000 | 5 production-ready flows with distinct triggers, toolsets, and responsibilities. Flows compose into a complete governance lifecycle from onboarding through release. |

License

MIT

Five agents. Five flows. One immune system. The human decides whether to merge -- Kodify decides everything else.