dirdocs

dirdocs is a Rust-powered CLI that provides file level documentation by leveraging an LLM.

It walks a directory (respecting .gitignore and extra ignores), hashes files, and for each new or changed file, it queries an LLM using the Awful Jade configuration + prompt templates.

The result is stored in a .dirdocs.nu file at the project root — a Nuon-compatible JSON tree of files, each annotated with descriptions, joy metrics, and personality emojis.

                      .`.
                    .`~.-:
                  .`- . -`
                .`-  . -`
              .`-   . -`
            .`-    . -`
          .`-     . -`
         `-      . -`
       .`-      . -`
      ;-       . -`
     .-      .  -`
    ;.      . -`
   ;.     . -`
   ::._.-`
   (.-`
   .Y(.
  ((()))
  _)==(_
 | .--. |
 | '--' |
 '------' LGB(plus at least two more letters)

🚀 How it works

1. Scan — Uses ignore::WalkBuilder to walk the project, applying .gitignore, global gitignore, excludes, and hidden rules.
2. Cache merge — Loads previous .dirdocs.nu and any subdirectory caches so unchanged files are skipped.
3. Hash — Uses content hashing to detect dirty vs clean files.
4. Template render — Builds a YAML-based LLM prompt from dir_docs.yaml in your awful_jade config directory.
5. LLM call — Uses awful_aj::ask with exponential backoff to request descriptions.
6. Merge + write — Updates .dirdocs.nu in place with new/changed entries, preserving older cached docs.
7. Works extremely well with the Qwen 3 4B model I Finetuned for Systems Programming related queries.

💡 Use with the included dls and dtree binaries or replace Github commit messages with the Chrome Extension.

📦 Installation

cargo install dirdocs

👷🏽‍♀️ Setup (steps will vary according to your operating system)

1. Install conda python version manager.

brew install miniconda

2. Create Python 3.11 virtual environment named aj and activate it.

conda create -n aj python=3.11
conda activate aj

3. Install pytorch 2.4.0

pip install torch==2.4.0

4. Add the following to your shell initialization.

export LIBTORCH_USE_PYTORCH=1
export LIBTORCH='/opt/homebrew/Caskroom/miniconda/base/pkgs/pytorch-2.4.0-py3.11_0/lib/python3.11/site-packages/torch' # Or wherever Conda installed libtorch on your OS
export DYLD_LIBRARY_PATH="$LIBTORCH/lib"

conda activate aj

⚙️ Usage

Initialize the template and configuration

dirdocs init

Generate file level documentation

dirdocs [OPTIONS]

Flags

• -d, --directory <PATH> — Root directory to scan (default .).
• -i, --ignore <NAMES> — Extra directories to ignore (comma-separated or repeatable).
• -f, --force — Force regeneration for all files, even if unchanged.

Examples

# Document the current project
dirdocs

# Document another directory
dirdocs --directory ~/Projects/my-app

# Ignore build artifacts
dirdocs --ignore target,node_modules,dist

# Regenerate everything
dirdocs --force

📄 Output: .dirdocs.nu

Example snippet:

{
  "root": "src",
  "updated_at": "2025-10-01T12:34:56Z",
  "entries": [
    {
      "kind": "file",
      "name": "main.rs",
      "path": "src/main.rs",
      "hash": "f1a23c...",
      "updated_at": "2025-10-01T12:34:56Z",
      "doc": {
        "fileDescription": "Main entrypoint wiring CLI args to internal modules.",
        "joyThisFileBrings": 7,
        "personalityEmoji": "🦀"
      }
    }
  ]
}

• Fully Nuon-compatible (readable in Nushell).
• Is used by dls and dtree to produce colorized tree listings with inline docs.

🔧 Configuration

• Reads Awful Jade config from ~/.config/com.awful-sec.aj/config.yaml.
• Uses a Handlebars template:
  ~/.config/com.awful-sec.aj/templates/dir_docs.yaml
  (You can customize the YAML to change prompt formatting.)

🧩 Included Binaries

• dls — ls-style directory listings with .dirdocs.nu docs attached.
• dtree — tree-style visualization with emoji 🌿 or ASCII connectors.

Together with dirdocs, they form a documentation-aware tree + ls.

🛠 Roadmap

• Implement a Bionic Font algorithm to make walls of text easier to read.
• Richer JSON schema with symbol lists and token counts.
• Integration with rust_ast.nu for Rust-specific symbol trees.

🤝 Contributing

PRs welcome!

• Improve template logic.
• Expand test coverage.

📜 License

This project is licensed under CC0 1.0 Universal (Public Domain Dedication).

You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission.