OS Pilot helps developers understand laptop slowdowns, identify performance pressure, and safely recover wasted storage from rebuildable project artifacts.
flowchart TD
A["Select Scan Target"] --> B["Desktop Scan UI"]
B --> C["FastAPI Scan Session"]
C --> D["Multi-Agent Planner"]
D --> E{"Human Approval"}
E -->|Approved| F["Restricted Tools"]
E -->|Skipped| G["Dry-Run Report"]
F --> H["Quarantine + Audit"]
H --> I["Recovery Output"]
classDef user fill:#0f172a,stroke:#06b6d4,color:#ffffff;
classDef app fill:#ecfeff,stroke:#0891b2,color:#0f172a;
classDef agent fill:#f0fdf4,stroke:#22c55e,color:#0f172a;
classDef safety fill:#fffbeb,stroke:#f59e0b,color:#0f172a;
classDef output fill:#f5f3ff,stroke:#8b5cf6,color:#0f172a;
class A user;
class B,C app;
class D agent;
class E,F,G safety;
class H,I output;
| Stage | What Happens |
|---|---|
| Select Scan Target | Choose a specific folder with the native Mac picker or run a whole-PC user-space scan |
| Desktop Scan UI | Set file-size threshold and start the scan from the React + Tauri interface |
| FastAPI Scan Session | Walk files, detect project evidence, score rebuildability, and profile workspace pressure |
| Multi-Agent Planner | Monitor, Diagnosis, Maintenance Planner, Risk & Safety, and Report agents build the cleanup plan |
| Human Approval | Compare Conservative, Balanced, and Deep Review scenarios before anything moves |
| Restricted Tools | Validate action ids, recheck safety, block risky paths, and quarantine only approved items |
| Recovery Output | Show reclaimed space, recovery recipes, restore history, and audit evidence |
Developer laptops quietly fill up with old node_modules, virtual environments, build artifacts, Python caches, notebook checkpoints, and large forgotten files. Heavy background apps can also create RAM pressure.
Generic cleaner apps can find large folders, but they usually do not understand whether a development artifact is safely rebuildable from package-lock.json, requirements.txt, pyproject.toml, notebooks, or other project evidence.
OS Pilot observes local system metrics, scans a user-selected folder or user-owned home scope, detects project type, scores artifact rebuildability, creates recovery recipes, validates safety with hard-coded rules, waits for human approval, and moves approved cleanup items to quarantine instead of deleting them.
The workflow is a four-part loop: profile the workspace, rank safe reclaim opportunities, compare Conservative / Balanced / Deep Review cleanup scenarios, then execute only approved items through quarantine with full restore history. Each scan stores a compact local snapshot so the agent can explain workspace growth or shrinkage over time.
|
|
|
|
| Concept | Where It Is Demonstrated |
|---|---|
| Agent / Multi-Agent System | agents/orchestrator_agent.py coordinates Monitor, Diagnosis, Maintenance Planner, Risk & Safety, and Report agents |
| MCP Server / Restricted Tools | mcp_server/server.py exposes a narrow allowlist of local tools instead of arbitrary shell access |
| Antigravity | Backend and frontend can be launched from Antigravity's terminal during the demo workflow |
| Security Features | Server-side scan sessions, protected-path blocking, symlink blocking, identity revalidation, active-process blocks, quarantine, restore, and audit logs |
| Deployability | Local web run commands plus the Tauri desktop shell documented in docs/desktop_app.md and docs/deployability.md |
| Agent Skills | agents/skills.py defines the observation, diagnosis, planning, safety, and reporting skills used by the pipeline |
See Course Concepts for the judge-facing mapping.
| Technology | Purpose |
|---|---|
| React + Vite + Tailwind | Frontend UI |
| Tauri | Desktop app shell |
| FastAPI | Backend API and scan sessions |
| Groq AI | Structured diagnosis with deterministic fallback |
| Restricted MCP-style tools | Safe local scanning, validation, quarantine, restore, and reporting actions |
| SQLite | Audit, quarantine, feedback, and scan snapshot storage |
| Python 3 | Core backend, agent, scanner, and safety logic |
ospilot-agent/
├── agents/ # AI agents for monitoring, diagnosis, planning, and safety
├── api/ # FastAPI backend endpoints and session management
├── core/ # Core logic for workspace profiling, scanning, and metrics
├── docs/ # Architecture, safety model, deployability, and writeup docs
├── frontend/ # React + Vite + Tailwind UI and Tauri desktop shell
├── mcp_server/ # Restricted MCP-style Python tools
├── scripts/ # Utility scripts such as weekly_scan.py
├── tests/ # Backend, agent, scanner, and safety tests
├── config.py # Application configuration
├── README.md # Project overview
└── requirements.txt # Python dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .envOptional Groq setup in .env:
GROQ_API_KEY=your_key_here
GROQ_MODEL=gpt-oss-20b
If no Groq key is configured, or if the model call fails, OS Pilot runs in deterministic fallback mode. Safety validation never depends on Groq.
cd frontend
npm installStart the backend and frontend in two separate terminals. The same commands work in a standard shell or in Antigravity's terminal.
# Terminal 1 - Backend
source .venv/bin/activate
uvicorn api.main:app --reload --port 8000
# Terminal 2 - Frontend
cd frontend
npm run devOpen http://localhost:5173.
cd frontend
npm run desktop:devSee Desktop App for the Tauri build path.
- Open http://localhost:5173, or use the desktop shell.
- Use the large file threshold slider from 30 MB to 5 GB. The default is 30 MB.
- Click Scan a Specific Folder to open the native Mac folder picker and scan the selected path.
- Click Scan Whole PC to scan your user-owned computer space while OS protected folders remain blocked.
The scan uses a single-pass optimized walker that prunes junk directories such as node_modules, .venv, __pycache__, and build outputs before recursing into them, making it practical on large developer workspaces.
python demo/create_demo_workspace.pyThe script creates safe fake Node, Python, notebook, cache, build, and large-file artifacts under demo/demo_workspace/.
After a scan, the Plan & Approval tab shows:
- Workspace profile with detected project types, manifest markers, artifact counts, candidate space, and linked live process signals
- Structured agent diagnosis with summary, top risks, urgency, recommended scenario, confidence, and previous-scan delta
- Cleanup scenarios for Conservative, Balanced, and Deep Review estimates
- Search and filtering for large result sets by folder, reason, or risk
- Cleanup action table with path, size, risk, confidence, reason, status, and approval checkboxes
- Rebuildability-aware planning with project type, manifest evidence, rebuildability, and recovery recipe
- Safe Autopilot for backend-approved stale rebuildable artifacts only
- Manual Review separation for advisory, blocked, protected, or risky items
- Before/after reporting with scenario estimates, quarantine counts, recovery recipes, and audit summary
OS Pilot is on-demand by default. Users can optionally enable a weekly read-only scan from the UI.
- macOS: installs a
launchduser agent at~/Library/LaunchAgents/com.ospilot.weekly-scan.plist - Linux: installs a user
crontabentry - Reports: writes Markdown and HTML reports to
.ospilot_data/reports/ - Safety: weekly scans never quarantine or delete files automatically
Manual run:
source .venv/bin/activate
python scripts/weekly_scan.py- No arbitrary shell access
- No automatic permanent delete
- No automatic process killing
- No registry edits or OS repair
- No unsafe raw full-disk scan
- Protected system paths are blocked
- Folder selection is user-driven through the app
- Running project-linked processes block quarantine for matching paths
- Approved cleanup actions are rechecked immediately before quarantine
- Symlink paths and changed filesystem identities are blocked at execution time
- Cleanup approvals use server-side scan sessions, not browser-submitted cleanup plans
- Scenario loading only selects backend-issued action ids
- Safe Autopilot is server-governed and cannot be pointed at arbitrary files by the UI
- Quarantined items can be restored
- Permanent removal is available only after quarantine
- Every important action is logged
- External LLM prompts use redacted, aggregated scan summaries
| Role | GitHub |
|---|---|
| Team Lead | @omerfarooq223 |
| Project Partner | @Sobanshahid10 |
| Project Partner | @haseebarif11 |
| Project Partner | @mabdullahab614-alt |
This project is licensed under the MIT License.
Star this repo if OS Pilot helped you recover a cleaner developer workspace.