{"id":48413814,"url":"https://github.com/noahbclarkson/codebase_viewer","last_synced_at":"2026-04-06T06:35:18.971Z","repository":{"id":289783015,"uuid":"972386614","full_name":"noahbclarkson/codebase_viewer","owner":"noahbclarkson","description":"Scan, explore, and document/export large codebases","archived":false,"fork":false,"pushed_at":"2025-12-20T04:17:05.000Z","size":2473,"stargazers_count":37,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-22T12:45:02.712Z","etag":null,"topics":["egui","gui","llm-tools","rust","rust-lang"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noahbclarkson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-25T02:04:17.000Z","updated_at":"2025-12-20T04:17:09.000Z","dependencies_parsed_at":"2025-07-07T07:19:47.567Z","dependency_job_id":"9ea906c4-a3a2-4cdc-bed7-b24254f68561","html_url":"https://github.com/noahbclarkson/codebase_viewer","commit_stats":null,"previous_names":["noahbclarkson/codebase_viewer"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/noahbclarkson/codebase_viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbclarkson%2Fcodebase_viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbclarkson%2Fcodebase_viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbclarkson%2Fcodebase_viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbclarkson%2Fcodebase_viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noahbclarkson","download_url":"https://codeload.github.com/noahbclarkson/codebase_viewer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbclarkson%2Fcodebase_viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31463015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["egui","gui","llm-tools","rust","rust-lang"],"created_at":"2026-04-06T06:35:15.781Z","updated_at":"2026-04-06T06:35:18.965Z","avatar_url":"https://github.com/noahbclarkson.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codebase Viewer\n\n[![Rust CI](https://github.com/noahbclarkson/codebase_viewer/actions/workflows/ci.yml/badge.svg)](https://github.com/noahbclarkson/codebase_viewer/actions/workflows/ci.yml)\n\nCodebase Viewer is a cross-platform desktop application—written entirely in Rust—that lets you **scan, explore, and document large codebases** with millisecond-level responsiveness.\nThe UI is built with [egui](https://github.com/emilk/egui) via *eframe*, giving you a native-feeling window on Windows, macOS, Linux, and the web (web support experimental).\n\n## ✨ Key Features\n\n| Capability                           | Details                                                                                                                                                                     |\n| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Blazing-fast scans**               | Parallel directory walking powered by the **ignore** crate’s `WalkBuilder`, which respects `.gitignore`, global Git excludes, hidden-file masks, and uses multiple threads. |\n| **Live tree UI**                     | Immediate-mode GUI rendered by egui/eframe; every file appears as soon as it’s discovered, even while the scan is still running. File icons based on type.                  |\n| **Selective exports**                | Keep the *full* directory context but choose exactly which files’ contents go into HTML, Markdown, or plain-text reports—ideal for LLM ingestion or documentation.          |\n| **Syntax-highlighted preview**       | On-the-fly colouring courtesy of **syntect**, using Sublime-Text grammars. Supports common text file types.                                                                 |\n| **Image preview**                    | Preview common image formats (PNG, JPG, GIF, BMP, ICO, TIFF) directly within the app.                                                                                       |\n| **SVG preview**                      | Preview Scalable Vector Graphics (.svg) files using the **resvg** crate.                                                                                                    |\n| **Native dialogs \u0026 theme awareness** | File/dir pickers via **rfd** and automatic light/dark detection via **dark-light**.                                                                                         |\n| **Cross-thread messaging**           | Non-blocking updates sent through **crossbeam-channel** for MPMC performance, keeping the UI responsive during scans and report generation.                                 |\n| **Human-readable sizes**             | Byte counts formatted with **humansize**.                                                                                                                                   |\n| **Config persistence**               | Settings stored in the OS-native config directory obtained with **dirs-next**.                                                                                              |\n| **Selection persistence**            | Save and load the checked state of files/directories to a JSON file.                                                                                                        |\n\n## 🚀 Quick Start\n\n```bash\n# 1. Clone and build in release mode\ngit clone https://github.com/noahbclarkson/codebase_viewer.git\ncd codebase_viewer\ncargo run --release\n\n# 2. Open a project\nFile ▸ Open Directory …   # or use the recent-projects list\n\n# 3. Explore \u0026 select\n– Navigate the tree using mouse or keyboard\n– Use the search bar (Ctrl+F) to filter\n– Tick files/dirs you want included in reports/exports\n\n# 4. Generate documentation\nFile ▸ Generate Report …\nChoose Markdown / HTML / Text, select options, and hit **Generate**\n```\n\n\u003e **System requirements**: Any modern OS with Rust 1.77+ installed. The app utilizes multiple threads for scanning via **Rayon** and **ignore**.\n\n## 🔧 Configuration\n\nA JSON config (`config.json`) is auto-saved to the standard user configuration directory:\n\n* **Linux:** `$HOME/.config/codebase_viewer/`\n* **Windows:** `%APPDATA%\\codebase_viewer\\`\n* **macOS:** `~/Library/Application Support/codebase_viewer/`\n\nKey fields:\n\n| Key                       | Purpose                                                             | Default          |\n| ------------------------- | ------------------------------------------------------------------- | ---------------- |\n| `theme`                   | UI theme: `\"light\"`, `\"dark\"`, or `\"system\"`                        | `\"system\"`       |\n| `show_hidden_files`       | Whether the scanner should include hidden files/directories         | `false`          |\n| `auto_expand_limit`       | Auto-expand dirs whose total file count ≤ this value after scan     | `100`            |\n| `max_file_size_preview`   | Size threshold (bytes) before preview/export refuses to read a file | `1048576` (1MiB) |\n| `export_format`           | Default format for reports: `\"markdown\"`, `\"html\"`, `\"text\"`        | `\"markdown\"`     |\n| `export_include_stats`    | Default setting for including stats in reports                      | `true`           |\n| `export_include_contents` | Default setting for including file contents in reports              | `true`           |\n| `recent_projects`         | List of recently opened directory paths (up to 10)                  | `[]`             |\n\n## 🏗️ Architecture Overview\n\n```text\nsrc/\n├── app.rs        # Top-level eframe::App state and logic orchestrator\n├── config.rs     # Handles loading/saving AppConfig (serde + dirs-next)\n├── external.rs   # Utility for opening paths in external apps (open crate)\n├── fs/           # File system operations\n│   ├── file_info.rs # Metadata struct for files/dirs\n│   ├── scanner.rs   # Background directory scanner (ignore crate)\n│   └── stats.rs     # Statistics collection during scan (ScanStats)\n├── model.rs      # Core data structures (FileNode, FileId, Check state)\n├── preview.rs    # Content preview generation (syntect, image crate)\n├── report/       # Report generation logic\n│   ├── generator.rs # Core report data collection and dispatch\n│   ├── html.rs      # HTML report formatter\n│   ├── markdown.rs  # Markdown report formatter\n│   └── text.rs      # Plain text report formatter\n├── selection.rs  # Saving/loading tree selection state to JSON\n├── task.rs       # Enums for background task messages (ScanMessage, TaskMessage)\n└── ui/           # egui UI modules\n    ├── dialogs.rs     # Preferences, Report Options, About, Shortcuts windows\n    ├── menu_bar.rs    # Top menu bar drawing logic\n    ├── preview_panel.rs # Right panel for file content preview\n    ├── status_bar.rs  # Bottom status bar drawing logic\n    └── tree_panel.rs  # Left panel with file tree view and search\n```\n\n* Long-running tasks (directory scanning, report generation) happen in background threads (`std::thread`, `rayon`).\n* UI updates are driven by messages received via `crossbeam-channel`, ensuring the GUI remains responsive (target 60 fps).\n* Directory scanning respects `.gitignore` and other standard ignore files via the `ignore` crate.\n* Reports include the full directory structure for context, followed by the selected subtree and optionally file contents.\n\n## 🖼️ Screenshots\n\n![Main Window](screenshots/main_window.png)\n\n---\n\n![Preferences Dialog](screenshots/preferences_dialog.png)\n\n---\n\n![Report Options Dialog](screenshots/report_options_dialog.png)\n\n## 🛠️ Development\n\n```bash\n# Format code\ncargo fmt --all\n\n# Lint code (strict)\ncargo clippy --all-targets --all-features -- -D warnings\n\n# Run tests\ncargo test --all-features\n\n# Run in debug mode (with hot-reload where applicable)\ncargo run\n\n# Run optimized release build\ncargo run --release\n```\n\n### Performance tips\n\n* Always build with `--release` for optimal performance, especially for the scanner.\n* On very large repositories, uncheck \"Include file contents\" in the report dialog if you only need the structure and stats.\n* The `max_file_size_preview` setting in Preferences can prevent attempts to load huge files into the preview panel.\n\n## Limitations / Known Issues\n\n* Previewing PDF files is not currently supported.\n* Web assembly (`wasm`) builds may work but are not actively tested or supported for v0.1.0.\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature/my-new-feature` or `bugfix/issue-number`).\n3. Make your changes. Ensure code is formatted (`cargo fmt`) and passes lints (`cargo clippy -- -D warnings`).\n4. Add tests for new functionality if applicable.\n5. Commit your changes with descriptive messages.\n6. Push to your branch (`git push origin feature/my-new-feature`).\n7. Open a Pull Request against the `main` branch of the original repository. Explain the purpose and scope of your changes.\n\nPlease also refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more detailed guidelines.\n\n## 📜 License\n\nThis project is dual-licensed under either the MIT License or the Apache License, Version 2.0, at your option. See the [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) files for details.\n\n---\n\n*This project demonstrates building a responsive, native-feeling desktop application using the Rust GUI ecosystem, primarily egui/eframe.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoahbclarkson%2Fcodebase_viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoahbclarkson%2Fcodebase_viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoahbclarkson%2Fcodebase_viewer/lists"}