codedetective/README.md

AI-powered tool to analyze codebases, reconstruct development timelines, and suggest where to resume work

# CodeDetective

<p align="center">
  <img src="https://via.placeholder.com/200x200?text=CodeDetective" alt="CodeDetective Logo" width="200" height="200">
</p>

<p align="center">
  <strong>Your AI-powered development assistant for resuming work on any codebase</strong>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#key-features">Key Features</a> •
  <a href="#usage">Usage</a> •
  <a href="#api-usage">API Usage</a> •
  <a href="#use-cases">Use Cases</a> •
  <a href="#license">License</a>
</p>

---

## 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

```bash
# 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

```bash
# 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:

```javascript
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:

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

Or pass it directly with the `--token` option:

```bash
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](CONTRIBUTING.md) for guidelines.

## License

MIT

---

<p align="center">
  Made with ❤️ by the CodeDetective Team
</p>