⚡ etop (Ecosystem Top)

Deterministic macOS Developer Ecosystem & Package Top

etop is a blazing-fast, deterministic CLI and interactive TUI monitor for macOS developers who work with multiple programming languages, package managers, runtimes, build caches, and container layers.

Inspired by classic Unix monitors (htop, btop, ctop), etop audits your entire developer workstation to discover installed software, resolve dependency topologies (unreferenced orphans vs explicit top-level tools), inspect associated filesystem artifacts (configs, data directories, logs, caches, and environment variables), and generate reversible, zero-accident cleanup scripts.

┌─ ⚡ etop | Items: 879 | Orphans: 219 (778 MB) | Marked: 0 | Sort: Disk Size ─────────────────────┐
│ Mark  Source         Name                 Category               Size       Status        Last Used│
│ [✓]   🧹 cache:build UV Python Wheels     Build Artifacts        1.47 GB    Cache         Today    │
│ [✓]   🧹 cache:build Homebrew Bottles     Build Artifacts        1.75 GB    Cache         Today    │
│ [ ]   🍺 brew:formula postgresql@16       Databases & Storage    68.7 MB    Dep (7 refs)  Today    │
│ [ ]   ⚡ mise:runtime ruby@4.0.6          Languages & Runtimes   482.1 MB   Active Runtime 4d ago  │
│ [ ]   🦀 cargo:bin   tokio-console        CLI Developer Tools    18.4 MB    Top-Level     12d ago  │
│ [ ]   🍎 macos:app   Ghostty              GUI Apps & Media       42.1 MB    Top-Level     1d ago   │
└────────────────────────────────────────────────────────────────────────────────────────────────────┘

---

✨ Key Capabilities

• Immediate Screen Painting ($< 1\text{ ms}$ Startup): Renders the complete UI frame instantly without blocking terminal startup, asynchronously streaming live discoveries from background workers with smooth 30 FPS Braille loading animations.
• Polyglot Ecosystem Coverage: Parallel, read-only discovery across 10 toolchains:
  • 🍺 Homebrew Formulae & Casks (brew info --json=v2)
  • ⚡ Mise Runtimes (mise ls --json / active configs)
  • 🦀 Cargo / Rust Binaries (~/.cargo/.crates2.json)
  • 💎 Ruby Gems (audited across all active runtimes)
  • 🌐 NPM / Bun / Yarn Global Packages
  • 🐍 Python / UV / Pip Isolated Tools
  • 🐹 Go Binaries ($GOPATH/bin + go version -m)
  • 🍎 macOS Applications (/Applications + mdls access timestamps)
  • 🧹 Compiler Build Caches (Cargo, Go, UV, Bundler, Homebrew)
  • 🐳 Docker Dangling Images & Container Layers
• Filesystem & Artifact Archaeology: Dynamically locates all associated configuration files, application support state, log files, caches, and active toolchain environment variables for any installed tool.
• Configuration & Environment Preservation Invariant: User configuration files (~/.config/..., .toml, .conf, .plist, .rc) and active environment variables are preserved and never deleted.
• Surgical Residual Log Purging: Cleanup plans specifically isolate and purge .log files, crash dumps, and caches — including logs nested inside config directories (e.g. ~/.config/<name>/*.log or logs/) — without touching configuration state.
• Post-Removal Package Tombstones & Forensic Archive: Complete package snapshots (paths, configs, data, logs, active environment variables, and reinstall commands) are archived to ~/.local/share/etop/tombstones/ and an append-only history.jsonl Write-Ahead Log upon cleanup generation.
• Security, Credentials & Environment Auditor: Audits SSH keys (~/.ssh), GPG signing identities, cloud credentials (~/.aws, ~/.kube, ~/.docker, GCP), package manager tokens (~/.npmrc, ~/.gem/credentials, ~/.cargo/credentials.toml, ~/.netrc), project .env files, and exported shell environment variables. Identifies insecure POSIX file permissions (0644 vs 0600) and masks secrets by default.
• Interactive Security View & Chmod Remediation: Dedicated TUI Tab [2] 🔐 Security & Env and CLI command etop security with safe in-memory unmasking ([r] or --reveal <key>) and deterministic security_fix_*.sh remediation script generation.
• Deterministic User Configuration System (etop.conf): Personalize default sorting, entrypoint mode, UI theme presets, and split percentages via ~/.config/etop/etop.conf (or etop.toml). Prioritized through a deterministic precedence ladder (CLI Flag > ENV > etop.conf > Defaults) with anti-bloat domain partitioning and frame-0 UI state hydration.
• Pre-Flight Workstation Diagnostics (etop doctor): Audits developer toolchains, tombstone storage permissions, custom security policies, and user configuration syntax with actionable health checks.
• Zero-Accident Safety Protocol: Never deletes packages silently. Cleanup operations default to --dry-run and generate human-auditable bash scripts with inverse rollback/reinstall scripts.

---

🚀 Installation

Option 1: Homebrew (Recommended)

brew tap vikks/tap
brew install etop

Option 2: One-Line Universal Installer (Pre-compiled Binary)

curl -fsSL https://raw.githubusercontent.com/vikks/etop/main/install.sh | sh

Option 3: Install via Cargo

cargo install --git https://github.com/vikks/etop.git

Option 4: Build from Source

git clone https://github.com/vikks/etop.git
cd etop
cargo build --release
cargo install --path .

---

🗑️ Uninstallation

Via Homebrew:

brew uninstall etop

Via Script:

curl -fsSL https://raw.githubusercontent.com/vikks/etop/main/uninstall.sh | sh

(To also purge tombstone history data from ~/.local/share/etop/, pass --purge: curl -fsSL .../uninstall.sh | sh -s -- --purge)

---

🎮 Interactive TUI Dashboard

Launch the fullscreen immediate-mode TUI:

etop
# or
etop tui

💻 CLI Subcommand Reference

1. Inspect Package Details & Associated Files (etop info)

Inspect multiple versions, install paths, configurations, data directories, log paths, caches, active environment variables, and reinstall commands:

# Inspect specific package or runtime
etop info postgresql
etop info ruby
etop info ripgrep

# Output structured JSON for automation pipelines
etop info postgresql --json

2. Full Audited Software Inventory Table (etop scan)

# View complete table sorted by disk footprint
etop scan

# View top 15 largest items
etop scan --top 15

# Sort by inactivity (longest unused first)
etop scan --sort inactivity

# Output raw JSON
etop scan --json

3. Filter by Objective Criteria (etop filter)

# Filter by ecosystem / toolchain
etop filter --ecosystem ruby
etop filter --ecosystem rust
etop filter --ecosystem brew

# Show only unreferenced orphan dependencies
etop filter --orphans

# Show only build artifact caches and dangling Docker layers
etop filter --caches

# Filter packages inactive for more than 90 days
etop filter --older-than 90

# Combine multi-criteria filters
etop filter -e python --orphans --older-than 60

4. High-Level Inventory Summary (etop summary & etop categories)

# High-level toolchain, orphan, and cache breakdown
etop summary

# Disk usage grouped by categorized domains
etop categories

5. Historical Tombstone Store (etop history)

# List all past uninstalled packages and preserved configs
etop history

# Inspect full forensic snapshot of an uninstalled package
etop history --inspect postgresql

6. Security, Credentials & Environment Auditor (etop security / etop env)

# Audit all credentials, SSH keys, package manager tokens, and shell ENV
etop security

# Show only items with permission issues or warnings (e.g. non-0600 modes)
etop security --check-perms

# Filter by security domain (ssh, cloud, pkg, env, cert, dotenv)
etop security --domain ssh
etop security --domain cloud
etop security --domain env

# Safely unmask/reveal a specific key in CLI (requires explicit key specification)
etop security --reveal "id_ed25519.pub"

# Generate deterministic chmod permission remediation script (with rollback)
etop security --fix

# Output structured JSON audit report
etop security --json

7. Generate Deterministic Cleanup & Rollback Scripts (etop prune)

# Generate cleanup plan for orphan dependencies
etop prune --orphans

# Generate cleanup plan for build caches
etop prune --caches

# Output scripts to a specific directory
etop prune --orphans --caches --out ./cleanup_plans

8. Workstation Pre-Flight Diagnostics (etop doctor)

Run an instant diagnostic checklist across installed language runtimes, storage permissions, and custom policy configurations:

etop doctor

Example diagnostic output:

  [✓] Pass   1/3 Toolchains & Runtimes (Found: brew, mise, cargo, git, uv, node, docker)
  [✓] Pass   2/3 Storage & Tombstone Permissions (Writable: ~/.local/share/etop)
  [✓] Pass   3/3 Custom Policy Configurations (Audited custom policies in ~/.config/etop)
             • Valid user configuration: etop.conf

9. Custom Configuration System (etop.conf / etop.toml)

etop can be personalized through ~/.config/etop/etop.conf (or ~/.config/etop/etop.toml).

A complete reference template is available in config/etop.conf.example:

[general]
# Default sort order: "size", "name", "last-used", "source", "category"
default_sort = "size"

# Default entrypoint mode: "tui" (default) or "table"
default_mode = "tui"

# Table top items limit (0 for unlimited)
top = 0

[tui]
# Active color theme preset ("catppuccin", "tokyo-night", "flexoki", "monokai", etc.)
theme = "catppuccin"

# Split percentage for the package list table (35 to 80, default 55)
table_width_percentage = 55

# Action subview height in lines (4 to 20, default 8)
action_subview_height = 8

[cleanup]
# Default dry-run mode for cleanup operations
dry_run = true

# Custom directory for run bundles (tombstones, manifests, rollback scripts)
runs_dir = "~/.local/share/etop/runs"

[security]
# Custom security policies directory
policies_dir = "~/.config/etop/policies"

# Whitelisted rules file
ignore_store = "~/.config/etop/policies/ignore.toml"

Deterministic Precedence Ladder

Configuration options resolve in strict, predictable priority order:

1. CLI Flags (-C, --config <PATH>, --sort <CRITERIA>, -n, --top <N>)
2. Environment Variables ($ETOP_CONFIG, $ETOP_SORT)
3. User Configuration File (~/.config/etop/etop.conf or etop.toml)
4. Built-in System Defaults

Anti-Bloat Guardrails

• Domain Partitioning: Settings are partitioned into bounded domains ([general], [tui], [cleanup], [security]). No unorganized flat namespace.
• Ergonomics vs. Transience: Dotfiles store only persistent user ergonomics (default views, theme, layout dimensions). Ephemeral execution flags (--json, --verbose, --force) are strictly CLI flags.
• Dynamic Layout Elasticity: Layout dimensions use Option<u16> to preserve dynamic resizing when omitted.
• Zero-Mutation Invariant: etop treats user configuration as strictly read-only; it will never overwrite or mutate your dotfiles.

---

🛡️ Zero-Accident Safety & Forensic Deletion Protocol

When etop generates a cleanup plan (e.g. cleanup_20260819_160920.sh), it enforces a strict dual-tier safety structure:

1. Phase 1: Native Package Uninstalls: Executes native package manager commands (brew uninstall, cargo uninstall, gem uninstall, etc.).
2. Phase 2: Targeted Log & Cache Purge: Deterministically deletes only .log files, crash dumps, and caches — specifically including logs nested inside config directories (~/.config/<name>/*.log or logs/) — while keeping all .conf, .toml, .plist, and .rc user configuration files completely intact.
3. Forensic Tombstone Archive: A companion manifest (cleanup_manifest_*.json) is saved alongside the scripts, and every removed package's paths, configs, logs, and environment variables are permanently archived to ~/.local/share/etop/tombstones/ and history.jsonl.
4. Reversible Rollback Script: A matching rollback_reinstall_*.sh script is generated with inverse install commands and documentation of all preserved configuration paths and environment settings.

---

🤝 Contributing Guidelines

We welcome contributions from systems programmers, toolsmiths, and developers across all language ecosystems!

Development Workflow

1. Fork & Clone:

   git clone https://github.com/your-username/etop.git
   cd etop
   

2. Make Changes: Implement your collector, TUI feature, or engine enhancement.
3. Verify Zero Warnings & Invariants:

   cargo check
   cargo test
   cargo clippy -- -D warnings
   

4. Submit a Pull Request.

Core Architecture Invariants

• Strict Determinism: Never rely on external network calls or non-deterministic heuristics at runtime. All inspection must come from deterministic CLI tools and filesystem metadata.
• Read-Only Scans: Audits and discovery queries must never mutate the host filesystem.
• Config & Env Preservation: Never write deletion routines that destroy ~/.config files or user environment configurations without explicit, isolated safeguards.

---

📜 License

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)