CodeSentry 🛡️

AI-Powered Pattern-Aware Code Analysis & Developer Education Engine

CodeSentry doesn't just flag issues—it teaches you why they matter and how to fix them.

Quick Start

# Install
pip install -e .

# Scan a file
codesentry scan myfile.py

# Learn while you scan
codesentry scan myfile.py --teach

# Quick lint-style output
codesentry scan myfile.py --quick

# JSON output for CI/CD
codesentry scan myfile.py --format json

What It Detects

CodeSentry focuses on patterns that matter, especially those commonly generated by AI coding assistants:

ID	Pattern	Severity	Description
CS001	generic-exception-swallow	⚠️ warning	Catching broad exceptions and silently ignoring them
CS002	placeholder-code-in-production	❌ error	TODO/FIXME comments with unimplemented stubs
CS003	blocking-call-in-async	❌ error	Using time.sleep() or requests in async functions
CS004	hardcoded-secret	🚨 critical	API keys, passwords, tokens in source code
CS005	mutable-default-argument	⚠️ warning	Using [], {}, or set() as default arguments

Output Modes

Default Mode

Balanced output with issue description and fix suggestion:

╭─ ⚠️  mutable-default-argument (CS005)
│  app.py:42:15
│
│  Parameter 'items' has a mutable default value.
│
│  💡 Change to 'items=None' and add 'if items is None: items = []' inside the function.
╰──────────────────────────────────────────────────

Teach Mode (--teach)

Full educational output with examples and "spot it yourself" tips.

Quick Mode (--quick)

Minimal lint-style output for CI/CD:

app.py:42:15: W CS005 mutable-default-argument
app.py:87:5: E CS002 placeholder-code-in-production

Exit Codes

Code	Meaning
0	No issues found
1	Warnings found
2	Errors found
3	Critical issues found

Commands

# Scan a file
codesentry scan <file.py> [options]

# List all patterns
codesentry patterns

# Show version
codesentry version

Philosophy

Traditional linters tell you what's wrong. CodeSentry teaches you why it matters.

Built in response to Anthropic's research showing AI-assisted developers score 17% lower on code comprehension, with debugging skills showing the steepest decline (Shen & Tamkin, 2026). CodeSentry bridges that knowledge gap—catching what AI generates, teaching what developers forgot.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy codesentry

# Linting
ruff check codesentry

License

MIT

---

Phase 0 - Validation Prototype