Stop analyzing code manually. Ask code-surgeon to understand your codebase, review changes for safety, find performance issues, or plan implementations—all with surgical precision.
code-surgeon is a multi-mode AI advisor that transforms how you work with code. Ask it to understand a system, validate a change before building it, optimize for performance and security, or create step-by-step implementation plans.
It reads your codebase, understands your architecture and patterns, then gives you specific, actionable guidance—not generic advice. No upload, no API keys, everything stays on your machine.
4 powerful modes. One command. Complete confidence.
Pick ONE based on what you need right now:
"I'm new here. What should I know?"
/code-surgeon --mode=discoveryYou get:
- System architecture: How components fit together
- Tech stack and versions: What you're building with
- Design patterns: How code is organized
- Known risks: Security and technical issues to watch
- Learning path: Where to start reading
Perfect for: Onboarding, code reviews, pre-refactor analysis, security audits
"Is this refactor safe? What could break?"
/code-surgeon "Rename auth module to auth-service" --mode=reviewYou get:
- Impact analysis: Exactly which files are affected
- Breaking changes: What will break and how to fix it
- Safety verdict: Go/no-go with explicit conditions
- Pre-flight checklist: Everything to validate before merging
- Migration guide: Step-by-step instructions for dependent code
Perfect for: Large refactors, dependency upgrades, architectural changes, pre-merge validation
"Where are our bottlenecks? What's vulnerable?"
/code-surgeon --mode=optimizationYou get:
- Performance bottlenecks: Slow queries, render issues, inefficient code (ranked by impact)
- Security vulnerabilities: SQL injection, XSS, auth gaps, CVE dependencies
- Code quality improvements: Complexity, duplication, dead code
- Prioritized roadmap: What to fix first, effort vs impact
Perfect for: Performance tuning, security hardening, technical debt cleanup
"I know what I want. How do I build it?"
/code-surgeon "Add JWT token refresh to authentication"You get:
- Architecture approach: How this fits into your system
- File-by-file changes: Exact locations and modifications
- Step-by-step tasks: Each one testable, each one committable
- Code examples: Copy-paste starting points
- Breaking change analysis: What might break and how to handle it
- Testing checklist: What to verify before shipping
Perfect for: Feature implementation, bug fixes, refactoring with confidence
Each mode runs independently. Use whichever matches your current need. No setup, no config, just results.
You just joined a React + Express team. Day one:
$ /code-surgeon --mode=discoveryYou immediately know:
- Frontend: React 18 with custom hooks pattern for state
- Backend: Express with layered architecture (routes → services → database)
- Database: PostgreSQL with Sequelize ORM
- Main risk: N+1 query problem in user fetching, outdated dependency (lodash 4.17.19 with known CVE)
- Where to start: Auth module is the beating heart — 12 other files depend on it
Result: Instead of asking 50 questions, you understand the system in 5 minutes.
Your team wants to refactor the authentication module. Before merging:
$ /code-surgeon "Refactor auth module" --mode=review --depth=DEEPYou get:
- 15 files will be affected
- 3 critical breaking changes (function signatures, return types, error handling)
- 12 tests will need updates
- External dependency:
@company/auth-utilspackage depends on this — users need migration guide - Go/no-go verdict: SAFE TO MERGE IF checklist completed
Result: You catch issues BEFORE code review, not during merge hell.
Users complain the user listing endpoint is slow:
$ /code-surgeon --mode=optimizationYou discover:
- Critical (fix now): N+1 query fetching posts per user (200 queries instead of 1 join)
- High (fix this sprint): Response is 2MB uncompressed, could be 400KB with gzip
- Medium (schedule later): React component re-renders on every list update
- ROI: Fix the N+1 query → 10x faster (1000ms → 100ms), 30 minutes effort
Result: You know exactly what to optimize and why. No guessing.
Build two-factor authentication:
$ /code-surgeon "Add SMS two-factor authentication"You get:
- System overview: Where 2FA fits in your auth flow
- Step-by-step tasks (each one is 2-5 minutes of work):
- Task 1: Write test for SMS code generation
- Task 2: Implement code generation logic
- Task 3: Add SMS provider integration
- Task 4: Update auth flow with verification step
- Task 5: Add UI for code entry
- ...and so on
- Code examples: Starting point for each task
- Testing checklist: What to verify before shipping
- What might break: Legacy clients without 2FA support
Result: You build with a clear plan. No surprises. Easy commits.
Choose one:
Via skills.sh (easiest):
npx skills add baagad-ai/code-surgeonOr clone directly:
git clone https://github.com/baagad-ai/code-surgeon.git ~/.claude/skills/code-surgeonDone. You're ready.
Pick ONE based on what you need:
# 1. Understand a codebase you just joined
/code-surgeon --mode=discovery
# 2. Check if a change is safe before building it
/code-surgeon "Update React from v17 to v18" --mode=review
# 3. Find performance and security issues
/code-surgeon --mode=optimization
# 4. Plan a feature step-by-step (default mode, just describe what you want)
/code-surgeon "Add email notifications on signup"That's it. Run whichever matches your current problem.
All modes support three speeds — pick based on urgency:
# QUICK (5 min, good enough for small changes)
/code-surgeon "Fix bug in login" --depth=QUICK
# STANDARD (15 min, recommended for normal work) ← DEFAULT
/code-surgeon "Add payment processing"
# DEEP (30 min, for risky or complex changes)
/code-surgeon "Refactor authentication system" --depth=DEEP| Situation | Mode | Command | Time |
|---|---|---|---|
| New to a codebase — You need to understand the system | Discovery | /code-surgeon --mode=discovery |
15 min |
| Planning a change — You want to know what breaks | Review | /code-surgeon "describe change" --mode=review |
15 min |
| Code is slow/risky — You need to find issues and prioritize fixes | Optimization | /code-surgeon --mode=optimization |
15 min |
| Ready to build — You know what you want, need step-by-step guidance | Implementation | /code-surgeon "describe task" |
15 min |
Unsure? Ask yourself: What problem am I trying to solve right now?
- "I don't understand this codebase" → Discovery
- "I'm worried this change will break things" → Review
- "This system needs to be faster/safer" → Optimization
- "I know what to build, need a plan" → Implementation
Monday: New feature request arrives
↓
/code-surgeon "Add two-factor auth" --mode=review
(Is this safe? How much work? What breaks?)
↓
/code-surgeon "Add two-factor auth" --mode=optimization
(Are there security issues we should fix first?)
↓
/code-surgeon "Add two-factor auth"
(Get step-by-step implementation plan)
↓
Build with confidence using the plan
Don't use for: Fixing a typo, removing one console.log, changing a variable name Why: Overkill. Just edit it directly. Exception: If the change touches 5+ files or you're unsure about impact → use Review mode
Don't use for: "Add a button to the UI", "Increase timeout from 5s to 10s" Why: Doesn't need deep analysis. Trust your knowledge. Exception: If you're in an unfamiliar codebase or want to validate the change won't break things → use Review mode
Don't use: If your code has hardcoded API keys, passwords, or credentials
Why: code-surgeon will block analysis to protect your secrets. Sanitize first, then retry.
How: Remove API keys, replace with REDACTED or environment variables, then analyze
Don't: Copy-paste code examples without understanding them Don't: Skip testing the recommendations Don't: Ignore the "might break" warnings Do: Review the suggestions, adapt to your situation, test thoroughly
Don't: Expect code-surgeon to write perfect, production-ready code What it does: Provides guidance and starting points What you do: Implement thoughtfully, test thoroughly, review carefully
- You're about to make a change and want to validate it first
- You're onboarding to a new codebase and need understanding fast
- Your system is slow/vulnerable and you need to find and prioritize issues
- You're building a feature and want a detailed step-by-step plan
- You need to explain a change's impact to your team
- QUICK mode: 5 minutes (good enough for small changes)
- STANDARD mode: 15 minutes (recommended, most common)
- DEEP mode: 30 minutes (for risky or complex changes)
Pick based on urgency, not complexity.
Yes. code-surgeon supports:
Frontend: React, Vue, Angular, Next.js, Svelte, Remix Backend: Express, Django, FastAPI, Rails, Spring Boot, Go, Rust Databases: PostgreSQL, MySQL, MongoDB, Firebase Languages: TypeScript, JavaScript, Python, Go, Rust, Java, C#, and 20+ others
If your stack isn't listed, code-surgeon still works — it may just have less framework-specific guidance.
No. Everything runs locally on your machine. Your code never leaves your computer. No API keys, no accounts, no data collection.
Sessions auto-save. If code-surgeon is interrupted, you can resume:
/code-surgeon-resume <session-id>Pick up exactly where you left off.
Yes. The plan/analysis is a guide, not law. Edit as needed for your situation. code-surgeon provides direction; you apply judgment.
Generation stops. Sanitize API keys and passwords, then retry. This protects you.
Yes. code-surgeon detects Lerna, Turborepo, Yarn workspaces automatically. Analyzes across all packages.
- Explicit reasoning: Every recommendation explains the "why"
- Breaking change warnings: Tells you what could fail
- Edge cases documented: Known limitations are called out
- You decide: code-surgeon advises; you approve and implement
- Review before using: Always review suggestions against your knowledge
When you run a command, code-surgeon follows a standardized process:
┌─ Your Question ─┐
│ "Add JWT │
│ refresh" │
└────────┬────────┘
│
↓
┌──────────────────────────────┐
│ Phase 1: Framework Detection │ (2 min)
│ Detects: Tech stack, versions│
└──────────┬───────────────────┘
│
↓
┌──────────────────────────────┐
│ Phase 2: Context Research │ (5 min)
│ Analyzes: Files, dependencies│
└──────────┬───────────────────┘
│
↓
┌──────────────────────────────┐
│ Phase 3: Deep Analysis │ (3 min)
│ Mode-specific deep dive │
│ - Discovery: Maps architecture
│ - Review: Analyzes impact
│ - Optimization: Finds issues
│ - Implementation: Plans tasks
└──────────┬───────────────────┘
│
↓
┌──────────────────────────────┐
│ Phase 4-6: Synthesis & Output│ (5 min)
│ Generates: Guidance, code, │
│ step-by-step tasks │
└──────────┬───────────────────┘
│
↓
┌─── Your Result ──┐
│ Detailed analysis,│
│ code examples, │
│ action plan │
└──────────────────┘
Smart file selection: code-surgeon doesn't read your entire codebase (slow, wasteful). It intelligently selects the most relevant files based on your question.
Pattern recognition: Learns your architecture, conventions, and team patterns. Gives guidance that fits your system, not generic advice.
Breaking change detection: Automatically identifies what might break when you make changes, then provides migration paths.
No hallucination: Uses strict contracts with each analysis step to prevent made-up answers. If uncertain, says so.
Local only: Everything happens on your machine. No uploads, no API dependency, no privacy concerns.
Traditional code analysis tools either:
- Are too generic ("use a linter")
- Require setup and configuration
- Depend on external APIs
- Don't understand your specific architecture
code-surgeon is different:
- Understands YOUR system — analyzes your actual code
- Zero setup — run one command, get insights
- Completely local — secure and private
- Actionable guidance — specific to your codebase, not generic advice
- Local Only — Everything runs on your machine
- No Upload — Your code never leaves your computer
- No Account — No sign-up, no API keys needed
- Open Source — See exactly what it does
- USAGE.md — When to use each mode and how
- EXAMPLES.md — Real-world usage examples
- FAQ.md — Common questions answered
- INSTALLATION.md — Setup and troubleshooting
- SKILL.md — Complete technical reference (for developers)
Pick your first use case:
# New to a codebase?
/code-surgeon --mode=discovery
# Planning a big change?
/code-surgeon "Your change description" --mode=review
# Code needs optimization?
/code-surgeon --mode=optimization
# Ready to build?
/code-surgeon "Your feature description"No installation needed. It's already here. Just run a command.
Found a bug? Have an idea? Open an issue on GitHub.
| Traditional | code-surgeon |
|---|---|
| Generic advice | Specific to YOUR codebase |
| Manual analysis | Automated, instant |
| External dependencies | Local, no setup |
| One-size-fits-all | Adapts to your patterns |
| Slow and tedious | 5-30 minutes, any complexity |
Stop analyzing code manually. Stop wondering if changes are safe. Stop guessing where bottlenecks are. Stop staring at implementation plans.
Ask code-surgeon. Get surgical precision. Ship with confidence.
Made with ❤️ for developers who want to move faster