safaai

TUI-first developer workstation optimizer.

Understands your machine instead of blindly cleaning it.

Never delete automatically. Explain everything. Every cleanup is previewable. Every action can be dry-run.

Quick start

uv run safaai

Opens the TUI dashboard. Press / for slash commands.

Requirements

• macOS (Apple Silicon, v0.1 targets macOS)
• Python 3.13+ (managed via uv)
• Textual terminal UI framework

Installation

git clone <repo> safaai
cd safaai
uv sync

Development

uv run safaai         # Run the TUI
uv run pytest        # Run all tests
uv run python -c …   # Quick check

Project structure

safaai/
├── safaai/               # Python package
│   ├── __init__.py
│   ├── __main__.py      # Entry: `uv run safaai`
│   ├── app.py           # SafaaiApp(App) + screen routing
│   ├── config.py        # Pydantic settings schema
│   ├── css/             # Per-screen CSS modules
│   │   ├── dashboard.py
│   │   └── screens.py
│   ├── screens/         # Textual Screen subclasses
│   │   └── dashboard.py
│   ├── scanners/        # Plugin scanners (added per task)
│   ├── commands/        # Slash command providers
│   ├── workflows/       # LangGraph pipeline engine
│   ├── widgets/         # Custom Textual widgets
│   ├── actions/         # Executor, trash, kill
│   └── core/            # HealthScore, journal
├── tests/               # Per-task test files
├── AGENTS.md            # Coding agent guide
├── graphify-out/        # Code knowledge graph (auto)
└── .hermes/plans/       # Implementation plans

Manual testing

After any change:

# 1. Run unit tests
uv run pytest -v

# 2. Run the TUI app (type q to quit)
uv run safaai

# 3. Import smoke test
uv run python -c "from safaai.app import SafaaiApp; print('import OK')"

# 4. Headless widget test
uv run python -c "
import asyncio
from safaai.app import SafaaiApp
app = SafaaiApp()
async def t():
    async with app.run_test() as p:
        await p.pause()
        print('dashboard:', app.screen.__class__.__name__)
asyncio.run(t())
"

Philosophy

1. Never delete automatically — every action is preview + confirm.
2. Explain everything — show what will happen and why.
3. Previewable — see what would be cleaned before committing.
4. Dry-run by default — destructive commands default to dry-run.