Varedura
joaosnet/Varedura
Limpeza de Docker e monitoramento de rede em TUI/CLI multiplataforma
Ver no GitHubMCP server multiplataforma para limpeza de Docker, monitoramento de rede e gerenciamento de recursos. Oferece interface TUI intuitiva e CLI modular, construído inteiramente com GitHub Copilot CLI. Detecta automaticamente o SO (Windows, Linux, macOS) e gerencia dependências.
Instalação
npx convez-ai joaosnet/Varedura1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Limpeza automatizada de containers e imagens Docker inutilizadas
- Monitoramento de recursos e rede em tempo real via terminal
- Integração com Claude via MCP para automação DevOps
- Compactação de discos virtuais e otimização de WSL no Windows
Veredito

Ferramenta sólida de limpeza Docker com interface TUI bem executada e suporte multiplataforma genuíno. A integração MCP é funcional, mas o projeto ainda está em fase inicial — útil para DevOps que precisam otimizar ambientes Docker locais com assistência de IA.
README
A tradução para o português deste README ainda está na fila.
🧹 Varedura
📦 Quick Install
One-liner (recommended)
Windows (PowerShell):
irm https://raw.githubusercontent.com/joaosnet/Varedura/main/install.ps1 | iex
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/joaosnet/Varedura/main/install.sh | bash
After installing, just type varedura in any terminal to launch.
The installer automatically detects your OS, checks for required tools (
uv,Docker,Git), installs only what's missing, and supports both Portuguese and English. If Varedura is already installed, it offers to reinstall or uninstall.
Other installation methods
uv tool install git+https://github.com/joaosnet/Varedura.git --python ">=3.14"
Then run: varedura
git clone https://github.com/joaosnet/Varedura.git
cd Varedura
uv run main.py # TUI (recommended)
uv run python -m cli.quick_cleanup # Quick Docker prune
uv run python -m cli.main_cleaner # Full cleanup with progress bar
uv run python -m cli.admin_tasks compact_vhdx # Admin-only tasks (Windows)
Via installer:
# Windows
.\install.ps1 -Uninstall
# Linux / macOS
./install.sh --uninstall
Or via uv:
uv tool uninstall varedura
Requirements
| Requirement | Notes |
|---|---|
| Python ≥ 3.14.2 | Managed automatically by uv during install |
| uv | Installed automatically by the installer if missing |
| Docker | Optional — needed for Docker cleanup features |
| Admin / root | Optional — needed for VHDX compaction & WSL config (Windows) |
📌 Current Project Status
Varedura is currently a Textual + Rich terminal app with modular tooling for Docker cleanup, network diagnostics, MCP integration, and session recording.
- Main interface: Textual TUI in
cli/textual_app.pywith Rich renderables - Legacy Rich interface:
varedura --legacy-richorVAREDURA_UI=rich varedura - Docker engine cleanup: sync + async logic in
docker_cleaner/core.py - Network tooling:
monitor/stalker.py,monitor/port_scanner.py,monitor/speed_tester.py - MCP server:
mcp_server/server.py(5 tools exposed to AI agents) - Session recorder: SVG capture + GIF generation in
recorder/ - i18n: bilingual
i18n/en.jsonandi18n/pt.json - Model utilities: LM Arena parser/generator in
lmarena/
✨ Features
🐳 Docker Cleanup
- Full system prune — containers, images, volumes, networks, build cache
- Granular options — pick exactly what to clean via interactive menu
- VHDX compaction — reclaim disk space from WSL2 virtual disks (Windows)
- WSL sparse config — optimize WSL2 memory and disk usage (Windows)
- Temp file cleanup — clear system temp directories
- Real-time streaming — watch every command execute line-by-line
🔍 Network Stalker
- Real-time network monitoring with latency graphs
- Port scanning with process identification
- Internet speed testing (multi-provider: Speedtest.net, Fast.com)
- ANATEL compliance checking (Brazil broadband regulation)
- PDF report export with history charts
- Persistent preferences for export settings
🤖 MCP Server (AI Integration)
- Exposes Varedura tools to GitHub Copilot CLI and other AI agents via Model Context Protocol
- 5 tools available:
docker_status,docker_quick_cleanup,docker_full_cleanup,port_scan,get_logs - Automatic
.vscode/mcp.jsonconfiguration from Settings menu - Works seamlessly with GitHub Copilot CLI agent mode
🎬 Session Recorder
- Automatic GIF recording of terminal sessions
- SVG snapshot capture → animated GIF generation
- Auto-updates
screenshots/demo.giffor README - Toggle on/off from Settings menu
🤖 Animated Mascot
- Pixel-art robot companion with state-based animations
- States: Idle, Working, Success, Error, Scanning, Wave
- Speech bubbles with contextual messages
📊 Logging & Reports
- Daily rotating logs in
logs/YYYY-MM-DD.log - PDF export for network monitoring reports
- CSV export for ping and speed history
- Automatic exception capture (Python, asyncio, threading)
🌍 Internationalization
- Auto-detects your system locale on first run (Portuguese / English)
- Switch anytime from the Settings menu
- 350+ translation keys covering every UI element
- Persists your choice to
~/.varedura_lang.json
🧠 LM Arena Models
- Parses and normalizes model lists for LM Arena workflows
- Generates structured outputs from
lmarena/lmarena_models.txt
🤖 MCP Server & Copilot CLI Integration
Varedura includes a built-in MCP (Model Context Protocol) server that exposes its tools to AI agents like GitHub Copilot CLI.
Setup
From the Varedura menu, go to Settings → MCP Server to auto-configure, or manually add to .vscode/mcp.json:
{
"servers": {
"varedura": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "-m", "mcp_server"]
}
}
}
Available MCP Tools
| Tool | Description |
|---|---|
docker_status | Get Docker disk usage, running containers, image/volume counts |
docker_quick_cleanup | Prune containers, images, volumes, networks, build cache |
docker_full_cleanup | Full cleanup + WSL shutdown + VHDX compaction (Windows) |
port_scan | Scan listening TCP/UDP ports, top processes by connection count |
get_logs | Retrieve recent Varedura log entries (up to 500 lines) |
Usage with Copilot CLI
Once configured, GitHub Copilot CLI can use Varedura tools directly:
> How much Docker disk space am I using? → calls docker_status
> Clean up all unused Docker resources → calls docker_quick_cleanup
> What ports are listening on my system? → calls port_scan
> Show me the last 50 log entries → calls get_logs
🖥️ Cross-Platform
Varedura runs on Windows, Linux, and macOS:
| Feature | Windows | Linux | macOS |
|---|---|---|---|
| Docker prune/cleanup | ✅ | ✅ | ✅ |
| Stop Docker processes | ✅ taskkill | ✅ systemctl/killall | ✅ killall/open |
| VHDX compaction | ✅ Optimize-VHD | ⬜ N/A | ⬜ N/A |
| WSL sparse config | ✅ | ⬜ N/A | ⬜ N/A |
| Temp file cleanup | ✅ %TEMP% | ✅ /tmp | ✅ /tmp |
| Recycle bin cleanup | ✅ PowerShell | ⬜ Skipped | ⬜ Skipped |
| Admin elevation | ✅ UAC | ✅ sudo | ✅ sudo |
| Network Stalker | ✅ | ✅ | ✅ |
| MCP Server | ✅ | ✅ | ✅ |
| One-liner install | ✅ irm | iex | ✅ curl | bash | ✅ curl | bash |
Windows-only features (VHDX, WSL sparse) are gracefully skipped on other platforms with an informational message.
🏗️ Current File Tree (Mar 2026)
Varedura/
├── .github/
├── .vscode/
├── build/
│ └── lib/
│ ├── cli/
│ ├── docker_cleaner/
│ ├── i18n/
│ ├── mascot/
│ ├── mcp_server/
│ ├── monitor/
│ └── recorder/
├── cli/
│ ├── admin_tasks.py
│ ├── main_cleaner.py
│ ├── quick_cleanup.py
│ └── richlog.py
├── docker_cleaner/
│ └── core.py
├── exports/
├── i18n/
│ ├── en.json
│ └── pt.json
├── lmarena/
│ ├── generator.py
│ ├── lmarena_models.txt
│ └── models.py
├── mascot/
│ ├── frames.py
│ ├── generate_sprites.py
│ ├── images/
│ └── renderer.py
├── mcp_server/
│ ├── __main__.py
│ └── server.py
├── monitor/
│ ├── port_scanner.py
│ ├── speed_providers.py
│ ├── speed_tester.py
│ └── stalker.py
├── recorder/
│ ├── gif_generator.py
│ └── session_recorder.py
├── recordings/
├── screenshots/
├── tests/
│ ├── images/
│ ├── static/
│ ├── test_export_pdf.py
│ ├── test_export_prefs.py
│ └── test_export_prompt.py
├── install.ps1
├── install.sh
├── LICENSE
├── main.py
├── POST-SUBMISSION.md
├── pyproject.toml
├── README.md
├── README.pt-BR.md
├── router_template.html
└── uv.lock
⚠️ Safety
Destructive operations always require explicit user confirmation:
| Command | Effect |
|---|---|
docker system prune -af --volumes | Removes ALL unused containers, images, volumes, networks |
taskkill /F / killall | Force-kills Docker processes |
wsl --shutdown | Stops all WSL distributions (Windows) |
Optimize-VHD | Compacts VHDX files (Windows, requires admin) |
Recommendations:
- ✅ Back up important data before running cleanup
- ✅ Review selected options before confirming
- ✅ Run as admin/root for full functionality
- ✅ Monitor real-time logs during execution
🧪 Testing
uv run python -m pytest tests/ -v
All destructive operations are mocked in tests — no Docker commands are actually executed.
🤖 Built with GitHub Copilot CLI
This project was built for the GitHub Copilot CLI Challenge.
Every feature of Varedura was developed using GitHub Copilot CLI as the primary development tool — from architecture decisions to implementation, debugging, and testing.
How Copilot CLI was used throughout the project:
- 🏗️ Architecture — Designed the dual sync/async execution model, MCP server integration, and cross-platform abstraction
- 🐳 Docker Cleaner — Implemented WSLDockerCleaner with streaming output, admin elevation, and VHDX compaction
- 🔍 Network Monitor — Built the stalker, port scanner, speed tester with multi-provider support
- 🤖 MCP Server — Created the Model Context Protocol server exposing all tools to AI agents
- 🎨 TUI & Mascot — Designed the Rich-based menu system and pixel-art animated robot companion
- 🌍 i18n System — Implemented 350+ bilingual translation keys with auto-detection
- 📦 Installer — Created the standalone installer scripts (install.sh + install.ps1) following UV/OpenClaw patterns
- 🎬 Session Recorder — Built the SVG→GIF recording pipeline for automatic demo generation
- 🧪 Testing — Wrote unit tests with proper mocking for all destructive operations
📄 License
MIT — see LICENSE for details.