Suyash Kumar

Posted on Dec 5

🧟‍♂️⚡ Time Machine Codex: I Built a Time Machine for Code Quality (And It's Haunted)

#kiro #kiroween #codeanalysis #ai

The Problem Every Developer Faces

You're staring at a 500-line function. Your code review says "complexity: 47" but you have no idea what that means. Your teammate asks "how did this file get so bad?" and you shrug because... you don't know. There's no history. No timeline. No way to see when good code turned into a monster.

What if you could travel back in time and watch your code quality evolve? What if you could see the exact commit where everything went wrong?

That's what I built. But here's the twist: I wrapped it in a Frankenstein horror theme and gave it superpowers no other code analysis tool has.

Meet Time Machine Codex: The world's first code quality time machine. ⚡🧟‍♂️

⚡ What Makes This Different

Every code analysis tool tells you "your code is bad." Cool. Thanks.

Time Machine Codex tells you:

How your code quality evolved across 10+ commits
Which commit introduced the biggest regression
When your code was at its best (and worst)
Whether you're improving or declining as a developer
Exactly what to fix, with AI-powered refactoring suggestions

And it does this for JavaScript, TypeScript, AND Python.

Oh, and it's wrapped in a mad scientist's laboratory with lightning bolts, Frankenstein's monster, and live electrical wires. Because why not? 🧟‍♂️

🎯 The Killer Feature: Time Machine Analysis

Caption: Watch your code quality evolve across Git history

This is the feature that makes Time Machine Codex unique. No other tool does this.

You give it:

A GitHub repository URL
A file path (like src/array.js)
Number of commits to analyze (up to 20)

It returns:

Quality score for each commit (0-100)
Trend analysis (improving/declining/stable)
Biggest improvement and regression
Commit messages and dates
Visual timeline

Real example:

// Analyzing lodash's array.js over 10 commits
{
  "overall_trend": "improving",
  "best_commit": {
    "sha": "a1b2c3d",
    "score": 87,
    "message": "Refactor: Extract validation logic"
  },
  "worst_commit": {
    "sha": "x9y8z7w",
    "score": 43,
    "message": "Add feature X (quick fix)"
  },
  "biggest_improvement": "+31 points in commit e4f5g6h",
  "biggest_regression": "-18 points in commit m7n8o9p"
}

Why this matters:

See when technical debt was introduced
Track your improvement as a developer
Identify which changes hurt code quality
Learn from your best commits
Justify refactoring to your team with data

🧪 The Five Superpowers

1. Multi-Language Support (JS/TS/Python)

Most tools only do JavaScript. Time Machine Codex analyzes:

JavaScript - Full AST analysis with Babel
TypeScript - Type-aware complexity detection
Python - Subprocess-based AST analysis

Auto-detects language from file extension and code patterns.

2. Scientific Metrics That Actually Mean Something

**
**
Caption: Industry-standard metrics with clear explanations

Quality Score (0-100) - Weighted combination of all factors
McCabe Cyclomatic Complexity - Decision points in your code
Toxicity Score - Severity-weighted measure of code smells
Maintainability Index - How hard is this to maintain?
Technical Debt - Estimated time to fix (in hours)

Formula breakdown:

Quality Score = 0.5 × Base + 0.3 × (100 - Toxicity) + 0.2 × (100 - 5×Complexity)
Toxicity = Σ(smell_severity × multiplier) / max_possible × 100
Technical Debt = code_smells × 15 minutes (industry standard)

3. AI-Powered Refactoring Suggestions

Not just "this is bad" - actual suggestions:

// Before (Complexity: 12)
function processUser(user) {
  if (user) {
    if (user.active) {
      if (user.email) {
        if (validateEmail(user.email)) {
          return sendEmail(user.email);
        }
      }
    }
  }
  return false;
}

// After (Complexity: 4)
function processUser(user) {
  if (!user?.active) return false;
  if (!user.email) return false;
  if (!validateEmail(user.email)) return false;
  return sendEmail(user.email);
}

Risk assessment included:

Low risk: Safe to apply immediately
Medium risk: Test thoroughly
High risk: Consider edge cases

4. GitHub Repository Scanner

**
**
Caption: Analyze entire repositories (up to 30 files)

Upload a GitHub URL, get:

Aggregate quality metrics
Worst files ranked by quality
Total technical debt
Language breakdown
Prioritized fix list

5. MCP Integration for Kiro IDE

**
**
Caption: 5 custom MCP tools for seamless Kiro integration

Built 5 MCP tools that Kiro can use directly:

analyze_code - Comprehensive analysis
suggest_refactors - Extract function suggestions
detect_code_smells - Focused issue detection
get_quality_score - Quick health check
analyze_repository_history - Time machine! ⚡

Real workflow:

User: "Analyze this code"
Kiro: *calls analyze_code MCP tool*
Kiro: "Your quality score is 67. Main issues: 
      - Function 'processData' has complexity 14
      - 3 levels of nesting in validation logic
      - 5 magic numbers without explanation"

User: "How do I fix it?"
Kiro: *calls suggest_refactors MCP tool*
Kiro: "I suggest extracting validation into a 
       separate function. Here's the refactored code..."

🧟‍♂️ The Frankenstein Theme

**
**
Caption: Mad scientist laboratory meets code analysis

Why a horror theme? Because refactoring is like reanimating dead code. You're taking something broken and bringing it back to life.

UI Features:

⚡ Live electrical wires that spark and crackle
🧟‍♂️ Frankenstein's monster that reacts to code quality
🔬 Laboratory equipment and surgical tools
💀 Skull garlands and occult symbols
🕷️ Cobweb graphs for complexity visualization
🩸 Blood-ink console for results
👁️ All-seeing eye for repository scanning

**
**
Caption: Live wires react to analysis in real-time

Built with:

React 19 + Vite
Three.js for 3D effects
Custom CSS animations
Tailwind for styling
Creepster & Nosifer fonts

🏗️ How I Built It With Kiro

The Spec-Driven Approach

I didn't just code this. I designed it first using Kiro's spec-driven development.

5 comprehensive specs:

Scientific Metrics - McCabe, toxicity, maintainability formulas
AI Refactoring - Gemini integration and suggestion engine
Multi-Language Support - JS/TS/Python analysis engines
Time Machine - Git history tracking and trend analysis ⚡
GitHub Scanner - Repository-wide analysis

Each spec had:

requirements.md - What it must do (EARS-compliant)
design.md - How it works (architecture, correctness properties)
tasks.md - Step-by-step implementation plan

**
**
Caption: 5 specs, 15 files, complete blueprint

The Development Timeline

Week 1: Scientific Metrics

Implemented McCabe complexity calculator
Built toxicity scoring system
Created maintainability index formula
Added technical debt estimation

Week 2: Multi-Language Support

JavaScript/TypeScript with Babel parser
Python with subprocess AST analysis
Auto-detection logic
Language-specific code smell detection

Week 3: AI Integration

Gemini API integration
Refactoring suggestion engine
Risk assessment logic
Two AI personas (friendly + technical)

Week 4: Time Machine ⚡

GitHub API integration
Commit history fetching
Quality tracking across commits
Trend analysis and regression detection

Week 5: MCP + Polish

Built 5 MCP tools for Kiro
Created Frankenstein UI theme
Added repository scanner
Deployment and testing

🔌 The MCP Magic

**
**
Caption: Simple JSON config connects Kiro to Time Machine Codex

Model Context Protocol lets Kiro talk directly to my analysis engine.

Setup in .kiro/settings/mcp.json:

{
  "mcpServers": {
    "refactor-codex": {
      "command": "python",
      "args": ["-m", "codex_mcp.mcp_server"],
      "cwd": "${workspaceFolder}/codex_mcp",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

What this enables:

Kiro can analyze code without leaving the IDE
No copy-paste to external tools
Full context awareness
Seamless workflow

Real example:

User: "Show me how lodash's array.js evolved"
Kiro: *calls analyze_repository_history*
Kiro: "Over 10 commits, quality improved from 
       62 to 81. Biggest jump was commit a1b2c3d 
       where they extracted validation logic."

📊 The Technical Architecture

**
**
Caption: Full-stack architecture with MCP bridge

┌─────────────────────────────────────────────┐
│  React Frontend (Vite + React 19)          │
│  - Frankenstein UI theme                    │
│  - Three.js animations                      │
│  - Real-time analysis display               │
│  ↓ HTTP/REST                                │
│  Express Backend (Node.js)                  │
│  ├─ JavaScript/TypeScript Analyzer (Babel) │
│  ├─ Python Analyzer (subprocess)            │
│  ├─ GitHub API Integration                  │
│  ├─ Commit History Tracker                  │
│  └─ Gemini AI Integration                   │
│  ↓ stdio                                    │
│  MCP Server (Python)                        │
│  - 5 custom tools                           │
│  - JSON-RPC protocol                        │
│  ↓ MCP Protocol                             │
│  Kiro IDE (AI Agent)                        │
└─────────────────────────────────────────────┘

Key Technologies:

Frontend: React 19, Vite, Three.js, Tailwind
Backend: Express, Node.js, Babel parser
Python: AST module, subprocess communication
AI: Google Gemini 1.5 Flash
MCP: Python MCP SDK, JSON-RPC
Git: GitHub API, commit analysis
Deployment: Vercel (frontend), Railway (backend)

🧪 Code Smell Detection

**
**
Caption: Comprehensive smell detection with remediation

High Severity:

Long functions (>50 lines)
Deep nesting (>4 levels)
High complexity (>10)
Callback hell
Missing error handling

Medium Severity:

Moderate functions (20-50 lines)
Moderate nesting (3-4 levels)
Magic numbers
Long parameter lists

Low Severity:

Console logs
Unused variables
Minor style issues

Each smell includes:

Line numbers
Severity level
Why it matters
How to fix it
Estimated time to fix

📈 Real-World Example

**
**
Caption: Real refactoring impact on quality score

Before refactoring:

// Quality Score: 43
// Complexity: 18
// Toxicity: 67
// Technical Debt: 2.5 hours

function handleUserData(data) {
  if (data) {
    if (data.users) {
      for (let i = 0; i < data.users.length; i++) {
        if (data.users[i].active) {
          if (data.users[i].email) {
            if (validateEmail(data.users[i].email)) {
              if (data.users[i].age > 18) {
                processUser(data.users[i]);
              }
            }
          }
        }
      }
    }
  }
}

**
**

After refactoring:

// Quality Score: 89
// Complexity: 4
// Toxicity: 12
// Technical Debt: 15 minutes

function handleUserData(data) {
  const users = data?.users ?? [];
  const eligibleUsers = users.filter(isEligibleUser);
  eligibleUsers.forEach(processUser);
}

function isEligibleUser(user) {
  return user.active 
    && user.email 
    && validateEmail(user.email) 
    && user.age > 18;
}

Impact:

Quality improved by 46 points
Complexity reduced from 18 to 4
Toxicity dropped by 55 points
Technical debt reduced by 2+ hours
Code is now testable and maintainable

🎯 What I Learned

1. Specs Are Worth Their Weight in Gold

Writing specs first meant:

Clear requirements before coding
No scope creep
Systematic implementation
Living documentation

Time saved: Probably 20+ hours of refactoring and confusion.

2. MCP Changes Everything

Direct tool integration beats copy-paste workflows by miles:

No context loss
Faster iteration
Better UX
Seamless AI assistance

3. Multi-Language Is Hard But Worth It

Supporting Python + JavaScript required:

Different parsers (Babel vs AST)
Language-specific smell detection
Subprocess communication
Error handling for both

But: Opens up way more use cases.

4. Time Machine Is The Differentiator

Every code tool does static analysis. Nobody does historical tracking.

This feature alone makes Time Machine Codex unique.

5. Theme Matters

The Frankenstein theme isn't just decoration - it makes the tool memorable and fun to use.

People remember "the code reanimation tool" way more than "code analysis tool #47."

🚀 Try It Yourself

[📸 IMAGE PLACEHOLDER 14: Call-to-action screenshot]
Caption: Ready to reanimate your code?

Live Demo

🔗 https://codex-refactor-mkjd.vercel.app/

Quick Start

Analyze Code:
- Paste JavaScript, TypeScript, or Python
- Get instant quality score and metrics
- See detailed code smells
Get Refactoring Suggestions:
- Click "Suggest Refactorings"
- Review AI-powered improvements
- See before/after comparisons
Time Machine:
- Enter GitHub repo URL
- Specify file path
- Watch quality evolve across commits ⚡
Scan Repository:
- Analyze up to 30 files
- Get aggregate metrics
- Prioritize worst files

Use With Kiro

Install MCP server:

   cd codex_mcp
   npm install

Configure in .kiro/settings/mcp.json:

   {
     "mcpServers": {
       "refactor-codex": {
         "command": "python",
         "args": ["-m", "codex_mcp.mcp_server"]
       }
     }
   }

Chat with Kiro:

   "Analyze this code"
   "Show me refactoring suggestions"
   "Track quality history for src/main.js"

📊 By The Numbers

Development:

5 comprehensive specs
15 spec files (requirements, design, tasks)
5 weeks of development
100+ commits

Features:

3 languages supported (JS/TS/Python)
5 MCP tools for Kiro
20+ code smell types detected
4 scientific metrics calculated
30 files per repository scan
20 commits max for time machine

Code:

React frontend with 25+ components
Express backend with 8 API endpoints
Python MCP server with 5 tools
3 analysis engines (Babel, AST, Gemini)
Full TypeScript type safety

UI:

30+ custom CSS animations
Three.js 3D effects
10+ themed components
Responsive mobile design
Accessibility compliant

🎃 Built for Kiroween

Refactor Codex embodies everything Kiroween is about:

✅ Haunting Theme - Frankenstein's laboratory aesthetic

✅ Reanimation Metaphor - Bringing dead code back to life

✅ Kiro Integration - Deep MCP integration with 5 tools

✅ Spec-Driven - 5 comprehensive specs, living documentation

✅ Unique Feature - Time machine analysis (nobody else has this)

✅ Production Ready - Deployed, tested, fully functional

Like Dr. Frankenstein, I stitched together multiple technologies (React + Express + Python + Gemini + GitHub + MCP) into one living, breathing system.

And unlike Frankenstein's monster, this one actually helps people. 🧟‍♂️⚡

🔮 What's Next

Planned features:

Support for more languages (Go, Rust, Java)
Team collaboration features
CI/CD integration
VS Code extension
Automated refactoring application
Code quality badges for README
Slack/Discord notifications

The vision: Make code quality tracking as natural as Git commits.

💡 The Bottom Line

I built a code analysis tool that:

Tracks quality across Git history (unique!)
Supports multiple languages (JS/TS/Python)
Provides AI-powered refactoring suggestions
Integrates seamlessly with Kiro via MCP
Looks like a mad scientist's laboratory

This is the future of code quality tools.

Not just "your code is bad" - but "here's how it got bad, here's how to fix it, and here's how to prevent it."

All wrapped in a Frankenstein theme because refactoring is reanimation. ⚡🧟‍♂️

🧟‍♂️ Ready to Reanimate Your Code?

**
**
Caption: The laboratory awaits...

Try Time Machine Codex and watch your code quality come back to life.

Because every developer deserves to see their code's story - not just its current state.

🔗 Live Demo: https://codex-refactor-mkjd.vercel.app/
📱 Source Code: https://github.com/suyashk-afk/codex-refactor/tree/main
🎥 Video Demo: https://youtu.be/FQAmgI-x07s

Have you ever wished you could see how your code quality evolved? What would you use a time machine for? Drop a comment below! 👇

Built with ⚡Kiro by Suyash

DEV Community