If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/zendesk/maxwell shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 12 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live zendesk/maxwell repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/zendesk/maxwell.

What it runs against: a local clone of zendesk/maxwell — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in zendesk/maxwell | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 111 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of zendesk/maxwell. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/zendesk/maxwell.git
#   cd maxwell
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of zendesk/maxwell and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "zendesk/maxwell(\\.git)?\\b" \\
  && ok "origin remote is zendesk/maxwell" \\
  || miss "origin remote is not zendesk/maxwell (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main/java/com/zendesk/maxwell/Maxwell.java" \\
  && ok "src/main/java/com/zendesk/maxwell/Maxwell.java" \\
  || miss "missing critical file: src/main/java/com/zendesk/maxwell/Maxwell.java"
test -f "src/main/java/com/zendesk/maxwell/MaxwellContext.java" \\
  && ok "src/main/java/com/zendesk/maxwell/MaxwellContext.java" \\
  || miss "missing critical file: src/main/java/com/zendesk/maxwell/MaxwellContext.java"
test -f "src/main/java/com/zendesk/maxwell/MaxwellConfig.java" \\
  && ok "src/main/java/com/zendesk/maxwell/MaxwellConfig.java" \\
  || miss "missing critical file: src/main/java/com/zendesk/maxwell/MaxwellConfig.java"
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4" \\
  && ok "src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4" \\
  || miss "missing critical file: src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 111 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~81d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/zendesk/maxwell"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Maxwell's daemon is a MySQL-to-Kafka change data capture (CDC) application that reads MySQL binary logs and produces JSON-formatted events to Kafka, Kinesis, and other streaming platforms. It captures INSERT, UPDATE, DELETE operations with full row data and historical before-state, enabling real-time downstream systems to stay synchronized with MySQL source-of-truth databases. Monolithic Maven project with Java (914KB) as primary language, ANTLR grammars (28KB) for SQL parsing, shell scripts (9.7KB) in bin/ for CLI tooling (maxwell, maxwell-benchmark, maxwell-bootstrap, maxwell-docker), and Ruby build tooling (7.3KB) in build/. Core engine logic resides in src/main/java, with docs built via MkDocs (docs/mkdocs.yml), Dockerfile for containerization, and config.properties.example as the canonical configuration template.

Data engineers and DevOps teams building event-driven architectures who need to stream MySQL changes into Kafka for ETL pipelines, cache invalidation, audit logging, search indexing (Elasticsearch), and inter-service event propagation without writing custom binlog parsing code.

Actively maintained production system at v1.44.0 with comprehensive CI/CD via GitHub Actions (ci.yaml, test.yaml), documented deployment patterns in docs/docs/deployment.md and docs/docs/high_availability.md, and a substantial Java codebase (915KB). The project is stable and widely used at Zendesk, with clear versioning and release artifacts, but shows lower activity velocity suggesting it is in steady-state maintenance rather than rapid feature development.

Standard open source risks apply.

Unable to determine from provided file listing—no git commit history, GitHub issues, or PR data visible. Check .github/workflows/ci.yaml and .github/workflows/test.yaml to infer CI triggers; review CHANGELOG.md for recent version notes (v1.44.0 is current). Recommend checking GitHub 'Issues' and 'Pull Requests' tabs and recent commits to understand active work.

git clone git@github.com:zendesk/maxwell.git
cd maxwell
make

The Makefile wraps Maven (standard Java build). For Docker: docker build -f Dockerfile -t maxwell:latest . then configure via config.properties.example and run bin/maxwell --config=config.properties.

Daily commands:

make
cp config.properties.example config.properties
# Edit config.properties with mysql_host, mysql_user, mysql_password, kafka brokers
bin/maxwell --config=config.properties

For bootstrapping existing data: bin/maxwell-bootstrap --config=config.properties. For benchmarking throughput: bin/maxwell-benchmark.

• src/main/java/com/zendesk/maxwell/Maxwell.java — Main entry point and daemon orchestration; every contributor must understand the startup and shutdown flow.
• src/main/java/com/zendesk/maxwell/MaxwellContext.java — Central dependency injection and configuration container; holds references to all major subsystems.
• src/main/java/com/zendesk/maxwell/MaxwellConfig.java — Configuration parsing and validation; defines all runtime options and defaults.
• pom.xml — Maven build configuration with all critical dependencies (MySQL driver, Kafka, Kinesis, ANTLR).
• src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4 — ANTLR grammar for MySQL DDL parsing; core to schema evolution tracking.
• src/main/java/com/zendesk/maxwell/bootstrap/BootstrapController.java — Handles table snapshots and initial data capture; critical for full table synchronization.
• src/main/java/com/zendesk/maxwell/MaxwellHA.java — High availability coordination and failover logic; essential for production deployments.

Add a Custom Producer for a New Streaming Platform

1. Create a new class implementing the producer interface in src/main/java/com/zendesk/maxwell/producer/ (reference src/example/com/zendesk/maxwell/example/producerfactory/CustomProducer.java) (src/example/com/zendesk/maxwell/example/producerfactory/CustomProducer.java)
2. Create a ProducerFactory class that instantiates your producer, following the pattern in CustomProducerFactory.java (src/example/com/zendesk/maxwell/example/producerfactory/CustomProducerFactory.java)
3. Register your factory in MaxwellConfig.java's producer instantiation logic (look for existing producer name-to-factory mappings) (src/main/java/com/zendesk/maxwell/MaxwellConfig.java)
4. Add configuration documentation and example to docs/docs/producers.md and config.properties.example (config.properties.example)
5. Update CHANGELOG.md with your new producer support (CHANGELOG.md)

Add Support for a New MySQL DDL Statement Type

1. Extend the ANTLR grammar file src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4 or create a new modular grammar in src/main/antlr4/imports/ (src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4)
2. Run ANTLR code generation (typically via Maven: mvn antlr4:antlr4) to regenerate parser classes (pom.xml)
3. Create a new DDL handler class in src/main/java/com/zendesk/maxwell/schema/ddl/ to process the AST and update schema state (src/main/java/com/zendesk/maxwell/MaxwellContext.java)
4. Register the handler in the DDL processing chain (typically in schema mutation logic) (src/main/antlr4/com/zendesk/maxwell/schema/ddl/mysql.g4)

Implement a Custom Health Check Plugin

1. Create a new class implementing MaxwellHealthCheck interface in src/main/java/com/zendesk/maxwell/health/ (reference src/example/com/zendesk/maxwell/example/maxwellhealthcheckfactory/CustomMaxwellHealthCheck.java) (src/example/com/zendesk/maxwell/example/maxwellhealthcheckfactory/CustomMaxwellHealthCheck.java)
2. Create a MaxwellHealthCheckFactory to instantiate your health check (reference CustomMaxwellHealthCheckFactory.java) (src/example/com/zendesk/maxwell/example/maxwellhealthcheckfactory/CustomMaxwellHealthCheckFactory.java)
3. Register your factory in MaxwellContext.java's health check initialization logic (src/main/java/com/zendesk/maxwell/MaxwellContext.java)
4. Document your health check in docs/docs/monitoring.md and provide example configuration in config.properties.example (config.properties.example)

Add a New Configuration Option

1. Add the property name constant and getter method to MaxwellConfig.java (src/main/java/com/zendesk/maxwell/MaxwellConfig.java)
2. Add parsing logic in MaxwellConfig constructor to read from properties, environment variables, or CLI args (src/main/java/com/zendesk/maxwell/MaxwellConfig.java)
3. Document the new option in config.properties.example with description and default value (config.properties.example)
4. Update docs/docs/config.md with detailed documentation of the new option, its purpose, and examples (docs/docs/config.md)

MySQL binlog position tracking: Maxwell stores position in a maxwell.positions table in MySQL—if this table is dropped or corrupted, daemon loses sync and may replay events. Schema change handling: ALTER TABLE events must be propagated to consumers correctly; DDL parsing via ANTLR can fail on non-standard SQL dialects (Percona extensions, MariaDB specifics). Kafka producer buffering: Misconfigured buffer.memory or batch.size can cause silent data loss; test failover explicitly. Position gaps on crash: If Maxwell crashes between committing a Kafka offset and writing the binlog position, duplicate events or skipped events can occur—idempotency must be enforced downstream. MySQL user permissions: Requires REPLICATION SLAVE privilege; missing this is a silent failure until startup. Config file encoding: Properties file must be UTF-8; non-ASCII characters in passwords may cause silent parsing failures.

• MySQL Binary Logging — Maxwell reads MySQL's row-based binary logs (binlog) to capture row changes; understanding binlog position, rotation, and formats (ROW vs STATEMENT vs MIXED) is essential to troubleshoot replication lag and data loss
• Change Data Capture (CDC) — CDC is the architectural pattern Maxwell implements—capturing and propagating database mutations to downstream systems in real-time; critical for understanding when/why to use Maxwell vs. polling
• ANTLR (Another Tool for Language Recognition) — Maxwell uses ANTLR 4 to parse MySQL DDL (CREATE/ALTER TABLE statements) to dynamically track schema changes; understanding grammar files in src/main/antlr4/ is required to extend DDL parsing
• Exactly-Once Semantics (EOS) — Maxwell offers at-least-once delivery by default (may duplicate on crash); achieving exactly-once requires idempotent consumers and careful position management, a key operational consideration
• Row-Based Replication (RBR) — Maxwell requires MySQL binlog_format=ROW to capture individual row changes; other formats (STATEMENT, MIXED) are incompatible and will cause silent errors
• Schema Evolution Tracking — Maxwell dynamically parses DDL to track column additions/removals/renames; old vs. new row data in events may have mismatched schemas—downstream consumers must handle versioning
• Kafka Offset Management — Maxwell must commit Kafka offsets in sync with MySQL binlog positions to guarantee resumption without duplication/loss; understanding consumer group offsets and offset commit strategies is critical for production deployment

• debezium/debezium — Alternative CDC platform (supports MySQL, PostgreSQL, MongoDB, Oracle, SQL Server) with broader database coverage but more complex deployment
• mysql-shell-plugins/general_backend — MySQL-native utilities for replication and migration; sometimes used alongside Maxwell for hybrid MySQL operations
• confluentinc/kafka-connect-jdbc — Kafka Connect JDBC source allowing users to poll MySQL instead of tailing binlogs, complementary approach to Maxwell's streaming model
• airbyte/airbyte — Universal data integration platform supporting MySQL CDC via Debezium; orchestration layer for syncing MySQL to data warehouses (Snowflake, BigQuery) downstream of Maxwell
• linkedin/databus — LinkedIn's original CDC system (predecessor inspiration); Maxwell was built partly as a Kafka-native successor to Databus

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for custom producer implementations

The repo includes example custom producer and health check factories in src/example/ but lacks integration tests verifying they work end-to-end. This would help contributors understand the extension points and catch regressions in the producer factory pattern.

• [ ] Create src/test/java/com/zendesk/maxwell/producer/CustomProducerIntegrationTest.java
• [ ] Add tests that instantiate CustomProducer and CustomProducerFactory from src/example/
• [ ] Verify producer lifecycle (init, push, flush, close) matches Maxwell's expectations
• [ ] Test CustomMaxwellHealthCheck integration from src/example/maxwellhealthcheckfactory/
• [ ] Add documentation link in docs/docs/embedding.md referencing the new test suite

Add GitHub Actions workflow for multi-version Kafka compatibility testing

The pom.xml shows multiple Kafka version profiles (0.8.2.2 mentioned) but .github/workflows/test.yaml likely doesn't test across versions. This prevents detection of breaking changes in Kafka client APIs.

• [ ] Review current .github/workflows/test.yaml to identify existing test strategy
• [ ] Create .github/workflows/kafka-compatibility.yaml that runs matrix builds with kafka-clients versions: 0.8.2.2, 2.x, 3.x
• [ ] Ensure pom.xml profiles are used correctly (e.g., mvn -P kafka-0.8.2.2 clean test)
• [ ] Add build status badge to README.md showing Kafka version coverage

Add comprehensive filter.js test suite and validation documentation

src/example/filter.js exists but there's no evidence of unit tests validating filter syntax or behavior. Filtering is a core feature (docs/docs/filtering.md exists) and incorrect filters could silently drop data.

• [ ] Create src/test/java/com/zendesk/maxwell/filtering/FilterEngineTest.java covering edge cases
• [ ] Test filter.js examples: basic row filtering, column exclusion, database matching
• [ ] Add test for invalid filter syntax error handling and reporting
• [ ] Create docs/docs/filter-examples.md with runnable filter.js examples and expected JSON outputs
• [ ] Link new examples from docs/docs/filtering.md

• Add integration test for ALTER TABLE RENAME in src/test/java/com/zendesk/maxwell/integration/ to verify DDL parsing via ANTLR correctly tracks schema changes when tables are renamed
• Document the maxwell.positions table schema and recovery procedures in docs/docs/troubleshooting.md (file currently missing) with examples of manual position reset
• Implement metrics endpoint (Prometheus-compatible /metrics) using existing OpenCensus 0.28.3 dependency to expose events_produced, kafka_lag, and binlog_position counters

• High · Outdated Jackson Dependency with Known Vulnerabilities — pom.xml - <jackson.version>2.15.2</jackson.version>. Jackson 2.15.2 has known deserialization vulnerabilities (CVE-2023-46604 and related). This version should be updated to 2.15.4 or later. Jackson is a critical dependency for JSON processing and is frequently targeted in security research. Fix: Upgrade jackson.version to 2.15.4 or latest stable version (2.16.x). Run 'mvn dependency:check' to identify other vulnerable transitive dependencies.
• High · Outdated AWS SDK with Known Vulnerabilities — pom.xml - <aws-java.version>1.12.782</aws-java.version>. AWS Java SDK 1.12.782 is outdated and contains multiple known CVEs. AWS SDK v1 is in maintenance mode. Consider migrating to AWS SDK v2 (aws-sdk-java-v2) or at minimum update to the latest v1 patch version. Fix: Upgrade to AWS SDK Java v2 (com.software.amazon.awssdk) or update aws-java.version to latest available 1.x patch version. Verify compatibility with Maxwell before upgrading.
• High · Outdated OpenCensus Dependency — pom.xml - <opencensus.version>0.28.3</opencensus.version>. OpenCensus 0.28.3 is deprecated and unmaintained. The project has migrated to OpenTelemetry. This dependency may contain unpatched security vulnerabilities. Fix: Migrate from OpenCensus to OpenTelemetry (io.opentelemetry). If upgrading is not immediately possible, audit all usages and consider removing if not actively used.
• Medium · Java 8 Compilation Target — pom.xml - <maven.compiler.source>1.8</maven.compiler.source> and <maven.compiler.target>1.8</maven.compiler.target>. The project targets Java 8 (maven.compiler.source/target = 1.8), which reached end-of-life in December 2030 but has long been unsupported by Oracle. Modern Java versions contain significant security improvements. Fix: Upgrade to Java 11 LTS or Java 17 LTS minimum. The Dockerfile already uses Java 23, creating a version mismatch. Align compilation and runtime targets to Java 17 or later.
• Medium · Docker Base Image Security Mismatch — Dockerfile - FROM maven:3.9.9-eclipse-temurin-23 and FROM openjdk:23-jdk-slim. The builder stage uses maven:3.9.9-eclipse-temurin-23 while the runtime uses openjdk:23-jdk-slim. Java 23 is a non-LTS release with short support windows. This creates maintenance burden and security exposure. Fix: Use Java 17 LTS or 21 LTS instead: 'maven:3.9.9-eclipse-temurin-17' and 'openjdk:17-jdk-slim'. This provides long-term support and stability.
• Medium · Incomplete Dependency Cleanup in Dockerfile — Dockerfile - RUN cd /tmp && mvn dependency:resolve. While the Dockerfile removes /root/.m2/ cache, Maven downloads are cached in the first layer. For a multi-stage build, this is acceptable but could be optimized. No credentials appear to be exposed, but verify no sensitive data in build logs. Fix: Add Maven security flags: '-Ddependency.check.skip=false' and scan with OWASP Dependency-Check plugin in CI/CD pipeline. Consider using .mvn/maven.config for consistent build settings.
• Medium · Missing Security Scanning in CI/CD — .github/workflows/. While GitHub Actions workflows exist (.github/workflows/ci.yaml and test.yaml), there's no evidence of security scanning (SAST, dependency checking, container scanning) in the provided file structure. Fix: Add GitHub Actions for: 1) OWASP Dependency-Check, 2) Container image scanning (Trivy), 3) SAST scanning (Snyk or

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.