Metadata-Version: 2.5
Name: safaai
Version: 0.1.13
Summary: TUI-first developer workstation optimizer
Requires-Python: >=3.13
Requires-Dist: aiofiles>=24.0.0
Requires-Dist: art>=6.5
Requires-Dist: asciimatics>=1.15.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: orjson>=3.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sqlalchemy>=2.0.51
Requires-Dist: textual>=1.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: watchdog>=6.0.0
Description-Content-Type: text/markdown

# 🧹 safaai — TUI-first Developer Workstation Optimizer

```
     _______.     ___       _______    ___           ___       __
    /       |    /   \     |   ____|  /   \         /   \     |  |
   |   (----`   /  ^  \    |  |__    /  ^  \       /  ^  \    |  |
    \   \      /  /_\  \   |   __|  /  /_\  \     /  /_\  \   |  |
.----)   |    /  _____  \  |  |    /  _____  \   /  _____  \  |  |
|_______/    /__/     \__\ |__|   /__/     \__\ /__/     \__\ |__|

```

**Understand your workstation. Never blindly delete. Optimize like a developer.**

---

## 💡 The Motivation: AI Era vs. Developer Disk Space

We live in the golden age of AI, local LLMs, and agentic coding workflows. But with great developer power comes great disk-space responsibility.

Every single week, your workstation accumulates:

- **Gigabytes of Xcode DerivedData** and archived artifacts.
- **Monstrosity-level `node_modules`** directories hidden in old forgotten directories.
- **Orphaned Docker volumes** and dangling images.
- **Caching artifacts** from package managers like Homebrew.
- **Massive model weights** and vector DB test logs.
- **Virtual machine junk** — VirtualBox, UTM, Parallels & VMware bundles, caches, and logs.

Sometimes, your machine starts chugging, and you just need an **instant performance boost** (freeing inactive RAM, purging caches, killing rogue memory-hogging consumer apps) without launching a heavy, closed-source consumer GUI app.

While there are plenty of disk cleaning utilities for Windows, developers on macOS and Linux are often left to guess which `rm -rf` command will break their local databases or compilation systems.

**safaai** is built for devs: terminal-first, completely open-source, interactive, and transparent.

> [!IMPORTANT]
> **safaai's Golden Rule:** Never delete automatically. Explain everything. Every cleanup is previewable. Every action can be dry-run.

---

## 🛠️ Commands Reference

Press `/` inside the application to open the command palette and run slash commands:

| Command           | Action               | Risk Level                 | What it does                                                                                                                            |
| :---------------- | :------------------- | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`/clean`**      | Scan & Clean         | **Safe (Review required)** | Streams live disk scans across node, docker, brew, xcode, and **virtual machine junk** (VirtualBox/UTM/Parallels/VMware). Reclaims space interactively with individual/parallel selectors. |

> [!NOTE]
> **Platform availability:** The virtual machine junk scanner currently targets **macOS only** (VirtualBox VMs, UTM, Parallels, VMware Fusion, and XNU temp disk images). **Windows and Linux** hypervisor detection is on the pipeline — coming in a future release. VM *bundles* are flagged **CAUTION** (never auto-selected); caches/logs are **SAFE** (pre-selected).
| **`/doctor`**     | Compute Health Score | **None**                   | Audits your workstation and returns a developer health score from `0` to `100` based on bloated caches, memory leaks, and boot speed.   |
| **`/optimize`**   | RAM & Process Boost  | **Medium**                 | Instantly purges system memory pages and terminates heavy background third-party applications to recover active RAM.                    |
| **`/logs`**       | Browse Logs          | **None**                   | Full searchable audit log of every operation, file path, and byte reclaimed during safaai runs.                                         |
| **`/ignorelist`** | Manage Exclusions    | **None**                   | Configure directory exclusions so safaai never scans or touches sensitive paths.                                                        |
| **`/sysinfo`**    | System Dashboard     | **None**                   | Visual real-time CPU, RAM, disk read/write, and network bandwidth meters.                                                               |
| **`/update`**     | In-App Self Update   | **None**                   | Automatically fetches latest release assets, checks versions, and atomically replaces the binary executable.                            |
| **`/help`**       | Command Assistant    | **None**                   | Displays quick command hints and keyboard binds.                                                                                        |
| **`/quit`**       | Exit safaai          | **None**                   | Terminate all active scanners safely and exit the TUI.                                                                                  |

---

## ⌨️ TUI Keyboard Shortcuts & Emoji Reference

To make **safaai** fully keyboard-accessible, every clickable action has an associated keyboard shortcut labeled directly in the button or row.

### 🧹 Cleanup Preview (`/clean`)
*   **`[c]` — Clean (`🧹 Clean [c]`)**: Run the cleanup execution on all checked items.
*   **`[s]` — Safe Only (`🟢 Safe [s]`)**: Select only low-risk items (e.g. system cache, temp folders) for deletion.
*   **`[a]` — Toggle All (`⚡ All [a]`)**: Cycle selection states between *safe-only*, *select all*, and *deselect all*.
*   **`[Esc]` — Cancel (`✕ Cancel [Esc]`)**: Exit the cleanup preview and return to the main dashboard.

### 📋 Checklist Row Actions
Use the **Up/Down Arrow keys** to navigate and move focus between the list items. Once a row is highlighted (focused with a green left-border indicator), use these shortcut keys:
*   **`[Space]` / `[Enter]`**: Toggle the checked state of the highlighted item.
*   **`[o]` — Open Directory (`👁️ [o]`)**: Open the target item's folder in Finder (macOS), xdg-open (Linux), or Explorer (Windows) to review its content manually.
*   **`[i]` — Ignore Item (`🙈 [i]`)**: Add the target item to your exclusion list, ignoring it in all future scans.

### 📊 Log Viewer (`/logs`)
*   **`[r]` — Refresh (`🔄 Refresh [r]`)**: Reload and refresh the audit logs database.
*   **`[c]` — Clear (`🗑 Clear [c]`)**: Permanently truncate the SQLite audit log database.
*   **`[d]` — Export (`📥 Export [d]`)**: Export and download all audit logs to a CSV file.
*   **`[Esc]` — Done (`✓ Done [Esc]`)**: Dismiss the log browser.
*   **`[Home]` / `[End]`**: Jump directly to the first/last page of logs.
*   **`[PageUp]` / `[PageDown]`**: Scroll up/down the datatable page.

### 🔑 Authentication Modal
*   **`[Enter]` — Authenticate (`🔑 Authenticate [Enter]`)**: Submit the entered sudo password.
*   **`[Esc]` — Cancel (`✕ Cancel [Esc]`)**: Reject authentication and cancel the operation.

### ⚙️ Self Update Modal (`/update`)
*   **`[u]` — Update Now (`⚙️ Update Now [u]`)**: Confirm and apply the in-app version update.
*   **`[Esc]` — Cancel (`✕ Cancel [Esc]`)**: Dismiss the updater.

---

## 💻 OS Support Matrix

| OS          | Status                      | Notes                                                                                                                                     |
| :---------- | :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| **macOS**   | **Fully Supported** (11.0+) | Optimized for Apple Silicon (`arm64`) and Intel (`x86_64`). Includes Apple-specific scanners (Xcode, LaunchAgents, system memory purges). |
| **Linux**   | **Fully Supported**         | Runs natively in standard TTY terminals. Bypasses macOS-specific routines automatically.                                                  |
| **Windows** | **Coming Soon 🛠️**          | Native command shell adapters and Windows registry/temp cleanup scanners are currently under development.                                 |

---

## 🚀 Installation & Launch

Run it instantly using `uv` (recommended):

```bash
# Force install the latest version, bypassing local cache
uv tool install --force --no-cache safaai
safaai
```

Or run it on-demand without permanent installation:

```bash
uvx --no-cache safaai
```

Or install via `pipx` / `pip`:

```bash
pipx install --force safaai
safaai
```

> [!TIP]
> **Bypassing Cached Versions**: `uv` has aggressive local metadata caching. To guarantee that you fetch and run the absolute latest release of `safaai`, always include the `--no-cache` flag when installing, upgrading, or running on-demand.

_For macOS standalone binary downloads or custom Homebrew formula taps, check the [Releases](https://github.com/manugopinath-dev/safai/releases) page._

_Made with ♥ by [Manu Gopinath](https://manugopinath.in)_
