Contributing
The key difference from your existing CONTRIBUTING.md is this version leads with where to help and gives more context on the codebase for someone who's never seen it.
Why Contribute
mex is early-stage and open source. The core works — drift detection, sync, scaffold population — but there's a lot of surface area to improve. If you use AI coding tools and have opinions about how agents should understand codebases, this is a good place to put those opinions into code.
Where to Start
Good First Contributions
- •New manifest support — the dependency and version checkers currently only read package.json. Adding support for pyproject.toml, go.mod, Cargo.toml, requirements.txt, or Gemfile is a self-contained task with clear test cases.
- •Smarter claim extraction — the markdown parser that extracts path, command, and dependency claims has edge cases. If you run
mex checkon your project and get a false positive, fixing it is a great first PR. - •Scaffold templates — starter scaffolds for specific stacks (Next.js, FastAPI, Rails, etc.) that make setup faster for projects using those stacks.
- •Bug fixes — check the Issues page for anything tagged with bug.
Larger Contributions
- •New drift checkers — if you can think of a way the scaffold can drift from reality that isn't already caught by the 8 existing checkers.
- •Improvements to the sync brief builder — better context for the AI means better fixes.
- •Support for additional AI tools beyond Claude Code, Cursor, Windsurf, and Copilot.
Setup
git clone https://github.com/theDakshJaitly/mex.gitcd mexnpm installnpm run build
Development commands:
| Command | What it does |
|---|---|
| npm run dev | Watch mode — rebuilds on every save |
| npm run test:watch | Runs tests in watch mode |
| npm test | Full test suite (Vitest, 78 tests) |
| npm run typecheck | TypeScript type checking without emitting |
Project Structure
# Source Directorysrc/ cli.ts — CLI entry point (commander) config.ts — project/scaffold root detection types.ts — shared TypeScript types reporter.ts — terminal output formatting markdown.ts — markdown parsing and frontmatter extraction git.ts — git operations (staleness, diffs) watch.ts — post-commit hook management drift/ index.ts — drift check orchestrator claims.ts — extracts path/command/dependency claims from markdown scoring.ts — computes 0-100 drift score frontmatter.ts — reads YAML frontmatter from scaffold files checkers/ — one file per checker, each returns DriftIssue[] scanner/ index.ts — pre-scanner orchestrator manifest.ts — reads package.json / manifest files entry-points.ts — detects main entry files folder-tree.ts — builds directory structure tooling.ts — detects build tools, linters, CI config readme.ts — reads existing README sync/ index.ts — sync loop (check → fix → verify → repeat) brief-builder.ts — builds targeted prompts with file content + context
Adding a New Checker
- Create a new file in
src/drift/checkers/(e.g.,my-checker.ts) - Export a function that takes claims or file paths and returns
DriftIssue[] - Each issue needs:
code(unique string),severity(error/warning/info),file,line(or null),message - Wire it into
src/drift/index.ts - Add tests in
test/
Look at any existing checker for the pattern — they're all self-contained and follow the same shape.
PR Guidelines
- ●One fix or feature per PR — keep changes focused
- ●Add tests for new checkers or bug fixes when possible
- ●Test locally with a real project — run
mex checkagainst an actual codebase, not just unit tests - ●Don't refactor surrounding code unless that's the point of the PR
Before Submitting
CI runs these across Node 18, 20, and 22 on every PR. PRs use a template — please fill in the What, Why, How to Test, and Checklist sections.
Reporting Bugs
Include the output of mex check --json if it's a drift detection issue.
Feature Requests
Describe the problem you're trying to solve, not just the solution you want.
Request Feature →Security
Don't open a public issue for security vulnerabilities. Email us with a description, reproduction steps, and potential impact. You'll get an acknowledgment within 48 hours.
thedakshjaitly@gmail.comLicense
By contributing, your work is licensed under the standard MIT license governing the mex repository.