Intelligenter Dokumentations-Assistent, der kontinuierlich deinen Code überwacht und Claude automatisch auffordert, fehlende Kommentare zu schreiben. Generiert technische Erklärungen für Entwickler UND einfache Erklärungen für Laien.

Features

🔍 Intelligente Lücken-Erkennung - Unterscheidet technische vs. einfache Kommentare
🤖 Automatische Claude-Prompts - Generiert perfekt formatierte Aufträge für Claude
👁️ Watch-Mode - Kontinuierliche Überwachung alle X Minuten
🔄 Daemon-Mode - Läuft persistent im Hintergrund
📊 Multi-File Analyse - Comprehensive Prompts für ganze Projekte
🛡️ Enterprise Security - Path validation, input sanitization, atomic operations
🔒 Production-Ready - Race-condition-free, memory-leak-proof, ReDoS-protected
⚛️ Multi-Language Support (JS, TS, Python, Java, C++, C#, PHP, Ruby, Go)
📖 Dual-Level Explanations (technisch + einfach)
📚 README Generation - Automatische Projekt-Dokumentation

Installation

# Global installation (recommended)
npm install -g neandoc

# Or use directly with npx (no installation needed)
npx neandoc@latest ./src

Usage

Einmalige Analyse:

# Analysiere Code und generiere Claude-Prompt
neandoc ./src

# Mit README-Generierung  
neandoc ./src --readme

# Preview-Modus (keine Änderungen)
neandoc ./src --dry-run

Watch-Mode (Game-Changer!):

# Überwachung alle 5 Minuten
neandoc ./src --watch --interval 5

# Daemon-Mode (Hintergrund)
neandoc ./src --daemon --interval 10

# Mit README-Updates
neandoc ./src --watch --readme

Apply-Mode:

# Claude-Response anwenden (Coming Soon)
neandoc ./src --apply claude-response.md

How it works

Architecture

Neandoc is built with enterprise-grade security and performance optimizations:

Project Structure

bin/     # Executable scripts (CLI entry point)
config/  # Configuration files (prompts, settings)
lib/     # Core library modules
  ├── parser.js      # Multi-language code parsing
  ├── commentor.js   # Safe comment generation & insertion
  ├── mcp-client.js  # AI integration & watch mode
  └── readme.js      # Documentation generation

Security Features ✅

Path Traversal Protection - Validates all file paths to prevent directory escaping
Input Sanitization - Validates function names, imports, and all user inputs
Atomic File Operations - Race-condition-free file locking and backup system
Memory Leak Prevention - Proper cleanup in watch mode and daemon processes
ReDoS Protection - Safe regex patterns to prevent regex denial-of-service attacks

Neuer intelligenter Workflow:

1. Automatische Analyse:

Code-Scanning - Findet Funktionen, Klassen, Variablen
Gap-Detection - Erkennt fehlende technische + einfache Kommentare
Prompt-Generation - Erstellt perfekt formatierte Claude-Aufträge
Direct-Output - Du kopierst Prompt → Claude macht den Rest

2. Watch-Mode (Kontinuierlich):

Background-Monitoring - Überwacht Code-Changes alle X Minuten
Gap-Tracking - Findet neue undokumentierte Funktionen
Auto-Prompting - Schickt Claude automatisch neue Aufträge
Persistent-Reminders - Nervt bis alles dokumentiert ist 😄

3. Claude Integration:

Neandoc → "Hey Claude, hier fehlen 3 Kommentare..."
Claude → Schreibt perfekte Dual-Level Dokumentation
User → Kopiert Kommentare in Code
Neandoc → "Danke! Überwache weiter..."

API Reference

CLI Commands

neandoc [directory] [options]

Options:

--watch - Watch mode - kontinuierliche Überwachung
--daemon - Daemon mode - läuft im Hintergrund
--interval <minutes> - Check-Intervall in Minuten (default: 5)
--apply <file> - Claude-Response aus Datei anwenden
--readme - README.md erstellen/aktualisieren
--dry-run - Preview ohne Änderungen
--only-functions - Nur Funktionen kommentieren
--no-readme - Keine README-Generierung

Core Classes

Parser - Multi-language code analysis (10+ languages)
NeandocAssistant - Intelligente Gap-Detection & Claude-Prompting
Commentor - File-safe comment insertion with backup
ReadmeGenerator - Intelligent README creation

Examples

Typischer Workflow:

# 1. Erste Analyse
neandoc ./src

# Output:
❌ Found 8 documentation gaps across 3 files!

🤖 NEANDOC → CLAUDE
==================================================
🦣 NEANDOC COMPREHENSIVE DOCUMENTATION REQUEST

Diese Funktionen brauchen Kommentare:

### validateInput (function) - Line 42
```javascript
function validateInput(data) {
  return data.length > 0 && data.match(/^[a-zA-Z]+$/);
}

AUFGABE: Erstelle technische + einfache Erklärungen...

📋 Copy the prompt above and send it to Claude! 💡 Then run: neandoc --apply


### **Watch-Mode in Action:**

```bash
# 2. Kontinuierliche Überwachung starten
neandoc ./src --watch --interval 3

# Output:
🦣 Neandoc watching ./src for documentation gaps...
📅 Checking every 3 minutes

[14:32:15] 🔍 Checking documentation...
✅ All code properly documented!

[14:35:15] 🔍 Checking documentation...
❌ Found 2 documentation gaps!
🤖 Sending new prompt to Claude...

# → Läuft permanent und nervt Claude bei neuen Lücken! 😄

Configuration

Customize prompts and behavior in config/prompts.json:

{
  "basePrompt": "Du bist Neandoc...",
  "commentStyle": {
    "technical": { "focus": ["Implementation details", "Parameters"] },
    "simple": { "focus": ["Everyday comparisons", "Basic functionality"] }
  }
}

Supported Languages

JavaScript/TypeScript (.js, .jsx, .ts, .tsx)
Python (.py)
Java (.java)
C/C++ (.c, .cpp)
C# (.cs)
PHP (.php)
Ruby (.rb)
Go (.go)

Integration

Claude Code (MCP)

Neandoc detects when running in Claude Code environment and uses MCP for optimal AI integration.

API Integration

Supports direct integration with:

Claude (Anthropic)
OpenAI GPT models
Custom LLM endpoints

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Philosophy

"Make code so clear that even a caveman could understand it."

Neandoc bridges the gap between technical complexity and human understanding. Every function deserves an explanation that both your senior developer and your project manager can understand.

License

MIT

Changelog

v1.1.0 - Security & Performance Update ✅

🔒 Security Improvements:

Fixed path traversal vulnerability (CVE prevention)
Added input sanitization for all user inputs
Implemented file size limits and permission checks

⚡ Performance & Stability:

Fixed race condition in file locking system
Eliminated memory leaks in watch mode
Replaced ReDoS-vulnerable regex with safe parsers
Improved error handling and recovery

🛠️ Code Quality:

Split large functions for better maintainability
Added atomic backup file operations
Enhanced test coverage (25/25 tests passing)
Improved error chaining and debugging

🦣 Built with prehistoric wisdom and modern AI

Keywords

FAQs

What is neandoc?

Is neandoc well maintained?

Package last updated on 27 Jun 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

neandoc

Neandoc