Automatically scans and documents your project structure.

Features

• 📁 Project Structure Scanning: Auto-generates complete directory tree
• 📦 package.json Extraction: Project name, version, scripts, and dependencies
• 🔗 Clickable Links: Direct navigation to each file
• ⚡ Smart Scanning: Full scan on first run, tracks only changed files afterward
• 🚫 Auto-Exclusion: Excludes node_modules, .git, dist, and other unnecessary directories
• 📝 Single Document: Consolidates all information in .project-structure.md

How it Works

This plugin uses a three-stage tracking approach:

Stage 0: Configuration Initialization (SessionStart Hook)

• Runs at session start
• Reads plugin version from plugin.json
• Checks if configuration file exists at .plugin-config/hook-auto-docs.json
• Performs automatic migration if versions differ
• Creates configuration with default settings if doesn't exist

Stage 1: Real-time File Change Tracking (PostToolUse Hook)

• Runs after every Write operation
• Records changed file paths to .structure-changes.json
• Silent execution (no user interruption)

Stage 2: Structure Documentation Generation (Stop Hook)

• Runs when Claude Code session ends
• When there are changes or it's the first run:
  1. Scans entire project directory
  2. Extracts information from package.json
  3. Generates directory tree (with clickable file links)
  4. Saves to .project-structure.md
  5. Stores current file list in .structure-state.json

Installation

/plugin install hook-auto-docs@dev-gom-plugins

Usage

Once installed, works automatically. When your session ends:

📚 Auto-Docs: Generated project structure documentation (245 files)

Or:

📚 Auto-Docs: Updated project structure (5 file(s) changed)

Generated Files

.project-structure.md

Document containing entire project structure:

# Project Structure

**Generated**: 2025-10-15 14:30:00

## Project Information

- **Name**: claude-code-marketplace
- **Version**: 1.0.0
- **Description**: Claude Code plugin marketplace

## Available Scripts

- `npm run dev`: Start development server
- `npm run build`: Build for production
- `npm test`: Run tests

## Dependencies

### Production (5)

- express: `^4.18.0`
- dotenv: `^16.0.0`

### Development (3)

- eslint: `^8.0.0`
- prettier: `^2.8.0`

## Directory Structure

claude-code-marketplace/
├── [.gitignore](.gitignore)
├── [package.json](package.json)
├── [README.md](README.md)
├── plugins/
│   ├── hook-auto-docs/
│   │   ├── [scripts/track-structure-changes.js](plugins/hook-auto-docs/scripts/track-structure-changes.js)
│   │   ├── [scripts/update-structure-docs.js](plugins/hook-auto-docs/scripts/update-structure-docs.js)
│   │   └── [hooks/hooks.json](plugins/hook-auto-docs/hooks/hooks.json)
│   └── hook-complexity-monitor/
│       └── ...

Configuration

The plugin automatically creates a configuration file at .plugin-config/hook-auto-docs.json on first run.

Automatic Configuration Migration

When you update the plugin, your settings are automatically migrated:

• ✅ Preserves your custom settings
• ✅ Adds new configuration fields with default values
• ✅ Version tracked via _pluginVersion field
• ✅ Zero manual intervention required

Available Configuration Options

showLogs

• Description: Show documentation generation messages in console
• Default: false
• Example: true (show file tracking confirmations)

outputDirectory

• Description: Directory path to save generated documentation
• Default: "" (project root)
• Example: "docs", ".claude-output"

outputFile

• Description: Output filename for project structure documentation
• Default: "" (uses .{project-name}-project-structure.md)
• Example: "project-structure.md", "structure.md"

includeDirs

• Description: List of specific directories to scan (if empty, scans entire project)
• Default: [] (empty - scans all directories except excluded ones)
• Example: ["src", "lib"] - only scans src and lib folders
• Use Case: Useful for large projects where you only want to document specific parts

excludeDirs

• Description: List of directories to exclude from project structure scan (ignored if includeDirs is set)
• Default: ["node_modules", ".git", "dist", "build", "coverage", ".next", "out", ".nuxt", "vendor", ".vscode", ".idea"]
• Example: Add/remove directories from the array

includeExtensions

• Description: List of file extensions to include (if empty, all files are included unless excluded)
• Default: [] (empty - includes all file extensions except excluded ones)
• Example: [".js", ".ts", ".jsx", ".tsx"] - only includes JavaScript/TypeScript files
• Note: Can be specified with or without dot (.meta or meta)
• Use Case: Focus documentation on specific file types (e.g., only source code, only configs)

excludeExtensions

• Description: List of file extensions to exclude from project structure (works together with includeExtensions)
• Default: [] (empty - no extensions excluded)
• Example: [".meta", ".log", ".tmp"] - excludes Unity meta files, logs, and temp files
• Note: Can be specified with or without dot (.meta or meta)
• Use Case: Hide unnecessary file types from documentation (e.g., Unity .meta files, build artifacts)

How to Change Settings

Edit the .plugin-config/hook-auto-docs.json file:

{
  "showLogs": false,
  "outputDirectory": "docs",
  "outputFile": "project-structure.md",
  "includeDirs": ["src", "lib"],
  "excludeDirs": [
    "node_modules",
    ".git",
    "dist",
    "build",
    "coverage",
    ".next",
    "out",
    ".nuxt",
    "vendor",
    ".vscode",
    ".idea",
    "tmp",
    "cache"
  ],
  "includeExtensions": [],
  "excludeExtensions": [".meta", ".log", ".tmp"],
  "includeEmptyDirs": true
}

Filter Rules:

• If includeDirs is set to a non-empty array, only those directories will be scanned and excludeDirs will be ignored
• If includeExtensions is set, only those extensions are included first, then excludeExtensions is applied to filter them further
• Both extension filters work together (AND condition) for maximum flexibility

Configuration Priority

The outputDirectory is determined in this order:

1. .plugin-config/hook-auto-docs.json's outputDirectory
2. Environment variable AUTO_DOCS_DIR
3. Environment variable CLAUDE_PLUGIN_OUTPUT_DIR
4. Default (project root)

Best Practices

Add to .gitignore

.project-structure.md
.structure-state.json
.structure-changes.json

Regular Reviews

Use the generated project structure documentation to:

• Onboard new team members
• Understand project organization
• Plan refactoring efforts

Output Files

Troubleshooting

Plugin not generating documentation?

1. Check for changes: Plugin only updates when files have changed.

2. First run: Automatically scans entire structure on first run.

3. Check file permissions: Ensure plugin has write permissions to project root.

Some directories missing?

1. Check exclusion list: See if it's in configuration.excludeDirs
2. Hidden directories: Directories starting with . are automatically excluded

Performance

• First scan: < 3 seconds even for 1000+ file projects
• Incremental updates: Only tracks changed files for fast execution
• Memory efficient: Processes files in streaming fashion

Related Plugins

• Session Summary - Summarizes file operations during session
• TODO Collector - Collects TODO comments
• Git Auto-Backup - Auto-commits at session end

Technical Details

Script Locations

• ~/.claude/plugins/marketplaces/dev-gom-plugins/plugins/hook-auto-docs/scripts/init-config.js - Configuration initialization
• ~/.claude/plugins/marketplaces/dev-gom-plugins/plugins/hook-auto-docs/scripts/track-structure-changes.js - File change tracking
• ~/.claude/plugins/marketplaces/dev-gom-plugins/plugins/hook-auto-docs/scripts/update-structure-docs.js - Structure documentation generation

Hook Types

• SessionStart - Initializes configuration on session start
• PostToolUse - Tracks file changes after Write operations
• Stop - Generates structure documentation at session end

Dependencies

• Node.js
• Git (optional - for change detection)

Timeouts

• PostToolUse: 5 seconds
• Stop: 15 seconds

Version

Current Version: 1.4.1

Changelog

v1.4.1 (2025-10-20)

• ✨ Improvement: Unified tree structure when multiple directories are included
• 🐛 Bug Fix: Regenerate documentation when output file is deleted
• 🔄 Auto Migration: Plugin version-based configuration migration
• 📦 Smart Updates: Preserves user settings while adding new fields
• 🎯 SessionStart Hook: Auto-creates configuration file on session start
• ⚡ Performance: SessionStart hook exits immediately if config is up-to-date
• 🌍 Cross-Platform: Enhanced path handling for Windows/macOS/Linux compatibility

v1.4.0 (2025-10-18)

• Added includeEmptyDirs configuration option to control empty directory inclusion
• Fixed extension filter display to show both filters when both are active

v1.3.0 (2025-10-18)

• Added includeExtensions and excludeExtensions configuration options for file extension filtering
• Both filters work together (AND condition) for fine-grained control

v1.2.0 (2025-10-18)

• Added project-scoped file naming using project directory name
• Prevents file collisions across multiple projects

v1.1.0 (2025-10-18)

• Added selective directory scanning with includeDirs configuration option

v1.0.0

• Initial release

License

Apache License 2.0 - See LICENSE for details

Credits

Part of the Claude Code Developer Utilities collection.