CodeDetective

Overview

CodeDetective is an advanced tool that helps developers understand and resume work on codebases by analyzing file patterns, timestamps, and relationships. It leverages OpenAI's powerful Responses API with GPT-4.1 to generate intelligent, contextual reports about your development timeline.

Whether you're returning to a project after weeks away, inheriting someone else's code, or simply trying to regain context, CodeDetective tells you exactly where to pick up.

Installation

# Install globally
npm install -g codedetective

# Or run directly with npx
npx codedetective analyze ./my-project

Key Features

• 💡 Development Timeline Reconstruction - Creates a precise timeline of coding activity based on file modification timestamps
• 📝 Actionable "RESUME HERE" Guidance - Provides specific, concrete next steps to resume work effectively
• 📊 Comprehensive File Analysis - Analyzes repository structure, file relationships and dependencies
• 📁 Intelligent File Categorization - Groups files by category (code, figures, data tables) for focused analysis
• 📋 Multiple Export Formats - Exports detailed reports in DOCX (default), Markdown, or JSON formats
• 🚀 Powerful Filtering Options - Filter by file patterns, categories, or file types
• 🔍 Smart .gitignore Integration - Respects your repository's ignore rules

Usage

# Basic usage - analyze current directory
codedetective analyze

# Analyze a specific directory
codedetective analyze /path/to/your/repo

# Specify output file
codedetective analyze -o my-report.docx

# Change output format (default is docx)
codedetective analyze -f markdown
codedetective analyze -f json

# Set analysis depth (default is 3)
codedetective analyze -d 4

# Include/exclude specific file patterns
codedetective analyze --include "**/*.js" --exclude "tests/**"

# Filter by file category
codedetective analyze --category code     # Only include code files
codedetective analyze --category figure   # Only include figures (png, jpg, svg, etc.)
codedetective analyze --category data_table  # Only include data tables (csv, xlsx, parquet, etc.)

# Shorthand category filters
codedetective analyze --code-only
codedetective analyze --figure-only
codedetective analyze --data-only

# Override the OpenAI model
codedetective analyze -m gpt-4-turbo

# Skip respecting .gitignore rules
codedetective analyze --skip-gitignore

API Usage

CodeDetective can also be used programmatically in your Node.js applications:

import { analyzeRepository, generateReport } from 'codedetective';

async function analyzeMyRepo() {
  // Analyze the repository
  const repoData = await analyzeRepository({
    directory: '/path/to/repository',
    maxDepth: 3,
    category: 'code' // optional category filter
  });
  
  // Generate the report
  const report = await generateReport({
    repoData,
    apiKey: process.env.OPENAI_API_KEY,
    format: 'docx', // or 'markdown' or 'json'
    outputPath: 'report.docx'
  });
  
  console.log('Report generated:', report);
}

Requirements

• Node.js 18 or higher
• OpenAI API key with access to the Responses API

Environment Variables

You can set your OpenAI API key using environment variables:

# Set in your shell or .env file
export OPENAI_API_KEY=your_openai_api_key

Or pass it directly with the --token option:

codedetective analyze --token your_openai_api_key

Report Content

The generated reports include:

• Chronological Timeline - Sequential view of your coding activity
• Last Work Session Analysis - Identification of your most recent code changes
• "RESUME HERE" Section - Specific files to open first and what they're used for
• Related Files - Additional context files you might need to reference
• Next Task Recommendations - Specific, actionable next steps based on analysis
• Unfinished Work - Identification of abandoned or incomplete code threads

Use Cases

• Returning After Time Away - Quickly regain context on where you left off
• Onboarding New Developers - Help new team members understand the codebase
• Project Handoffs - Smoothly transition projects between developers
• Code Archaeology - Understand the history and structure of legacy codebases
• Context Switching - Reduce overhead when switching between multiple projects

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT