mod-bot

mod-bot

An adaptive code moderation MCP server that learns your style.

Install • What it does • Tools • Adaptive output • How it works • Contributing

---

Why mod-bot?

Most AI coding tools treat every developer the same. A junior writing their first API gets the same terse response as a staff engineer. Mod-bot fixes that.

It's a Model Context Protocol server for Claude Code that acts as your personal senior tech lead — one who knows your codebase, remembers your preferences, and adjusts their communication style to match your experience level.

Install

claude mcp add --scope user mod-bot -- npx -y mod-bot@latest

That's it. Restart Claude Code and you're ready to go.

What it does

Adapts to you. Tell mod-bot your experience level and it adjusts everything — a junior gets step-by-step walkthroughs with explanations, a senior gets terse one-liners. Working in a language you're learning? It automatically provides more detail.

Learns your patterns. Use early returns consistently? Prefer functional style? Skip reviews on small changes? Mod-bot notices and adapts. After enough sessions, it suggests workflow adjustments based on what it's learned.

Knows your project. On first run, mod-bot scans your codebase — languages, frameworks, test setup, CI/CD, project maturity. It keeps a living knowledge graph that updates as your project evolves.

Manages context. It tracks your current branch, task, decisions, and open questions across sessions. Pick up exactly where you left off.

Respects your tokens. Unlike tools that eagerly spawn agent swarms, mod-bot estimates cost first and asks before spending. Default budget is conservative.

Quick Start

1. Initialize in your project

> init_setup --name "Alex" --experienceLevel senior

Mod-bot scans your project and creates a .mod-bot/ config directory with your preferences.

2. Get suggestions

> mod_suggest --task "Add rate limiting to the API"

3. Review before committing

> mod_review --changes "$(git diff --staged)"

4. Teach it your preferences

> learn_pattern --id "early-returns" --type code_style --description "Always use early returns over nested if/else"

Tools

Init

Tool	What it does
init_setup	Scan project, set your preferences, get tailored recommendations
init_reconfig	Update preferences without re-scanning
init_migrate	Migrate config when mod-bot updates

Moderation

Tool	What it does
mod_suggest	Suggest an approach for a task, adapted to your level
mod_review	Review staged changes — catches issues calibrated to your skill
mod_plan	Create an implementation plan with appropriate detail
mod_checkpoint	Snapshot progress, decisions made, and open questions
mod_retro	Quick retrospective after completing a task

Context

Tool	What it does
ctx_status	Current state: branch, task, health metrics, recent commits
ctx_refresh	Force a full codebase re-scan
ctx_focus	Set a focus area (e.g., "auth module") for prioritized context
ctx_history	Session history and decision log

Learning

Tool	What it does
learn_pattern	Teach a coding pattern or preference
learn_show	See everything mod-bot has learned about you
learn_reset	Remove specific patterns or reset all
learn_suggest-workflow	Get workflow adjustment suggestions based on your habits