OsAgent

A local AI-powered OS assistant for Windows that organizes files, monitors system pressure, suggests cleanup actions, and stays privacy-friendly by running with local tooling such as Ollama.

OsAgent is built for people whose Downloads folder turns into archaeology, whose disk keeps filling up, and whose machine feels slow long before they know why. It combines fast deterministic file handling with local LLM reasoning, safe approval gates, background monitoring, and review-friendly terminal UX.

Table of Contents

• Why People Use It
• Highlights
• Demo
• Architecture
• Comparison
• Installation
• Quick Start
• Core Workflows
• Configuration
• Command Reference
• Output Philosophy
• Safety Model
• Background Notifications
• Troubleshooting
• Contributing
• Roadmap
• Local Development
• Publishing to PyPI

Why People Use It

• Keep Downloads under control without manually sorting hundreds of files
• Detect large, stale, or duplicate files before they become a problem
• Understand system pressure from CPU, memory, disk, and top processes
• Get practical recommendations like what to review, close, archive, or ignore
• Run in the background and surface approval needs with desktop notifications
• Stay local-first: Ollama is optional, and rule-based fallbacks still work

Highlights

• Fast scans with metadata caching and parallel processing
• Safe file organization with approval-aware actions
• Relative folder structure preservation during moves
• Restore reports and undo support for recent move actions
• Process-aware system pressure analysis
• Ollama-powered human recommendations when available
• Background daemon with Windows notifications
• Compact CLI summaries by default, full JSON when you need it

Demo

Terminal

osagent doctor
osagent scan
osagent organize --dry-run
osagent stats
osagent suggest
osagent restore-report

Screenshots / GIFs

Add these once you have media assets:

• docs/demo-scan.png
• docs/demo-stats.png
• docs/demo-suggest.png
• docs/demo-daemon.gif

Recommended production-style layout:

![Scan Summary](docs/demo-scan.png)
![System Health](docs/demo-stats.png)
![Suggestions](docs/demo-suggest.png)

Architecture

OsAgent uses a hybrid local architecture:

                    +----------------------+
                    |       Ollama         |
                    |  Local LLM Reasoning |
                    +----------+-----------+
                               |
                               v
   +------------------+   +----+------------------+   +------------------+
   |  Filesystem      |-->|     Agent Service     |<--| System Monitor   |
   |  Scanner         |   |  planning / safety    |   | CPU/RAM/Disk     |
   +------------------+   +----+------------------+   +------------------+
                               |
                 +-------------+-------------+
                 |                           |
                 v                           v
        +------------------+        +----------------------+
        | SQLite Memory    |        | CLI / Daemon / Toast |
        | history, cache,  |        | summaries, reports,  |
        | feedback, state  |        | notifications        |
        +------------------+        +----------------------+

Key design choices:

• Rules-first for speed and reliability
• LLM second for human reasoning and ambiguous cases
• SQLite for persistence, auditability, and restore support
• Explicit approval gates for risky actions

Comparison

Capability	OsAgent	Manual Cleanup	Generic File Sorter
Organize Downloads	Yes	Slow	Usually yes
Preserve subfolder structure	Yes	Yes	Often no
Duplicate detection	Yes	Manual effort	Sometimes
CPU / memory / disk review	Yes	Manual	Rare
Process-aware suggestions	Yes	Manual	No
Local LLM recommendations	Yes	No	No
Restore / undo support	Yes	Manual	Rare
Background monitoring	Yes	No	Sometimes
Desktop notifications	Yes	No	Rare
Approval-aware actions	Yes	N/A	Rare

Installation

End Users

pip install osagent
osagent init
osagent doctor
osagent organize --dry-run

If you want human-style recommendations for pressure management and ambiguous file classification, install and run Ollama locally.

Ollama Setup

ollama serve
ollama list
osagent config get ollama_model
osagent config get ollama_url

Default expected URL:

http://127.0.0.1:11434/api/generate

If needed:

osagent config set ollama_model "phi3"
osagent config set ollama_url "http://127.0.0.1:11434/api/generate"

Quick Start

1. Initialize

osagent init

This creates your config at:

%USERPROFILE%\.osagent\config.json

2. Run Diagnostics

osagent doctor

doctor checks:

• config file presence
• watched paths
• destination root
• database location
• Ollama reachability and model availability
• desktop notification support
• daemon status

3. Preview Before Changing Anything

osagent scan
osagent organize --dry-run
osagent stats
osagent suggest

4. Apply Safe Actions

osagent organize --apply

5. Run in Background

osagent daemon start
osagent daemon status

When enabled, the daemon can:

• watch configured folders
• generate review suggestions in the background
• send Windows toast notifications
• open a review report when you click the notification

Core Workflows

File Organization

osagent scan
osagent organize --dry-run
osagent organize --apply

OsAgent:

• classifies files using rules first
• falls back to Ollama only when needed
• preserves relative subfolder structure
• writes actions to history for review and restore

System Pressure Review

osagent stats
osagent suggest

This gives you:

• current CPU, memory, and disk pressure
• large and stale file signals
• top memory-heavy processes
• actionable suggestions
• human-readable Ollama advice when available

Process Pressure and Closing Apps

osagent stats
osagent suggest
osagent close 12345 --dry-run
osagent close 12345

Use close carefully. OsAgent can recommend process review actions, but destructive or system-impactful actions should always be checked before execution.

Review, Approve, Reject, Ignore

osagent approve <action-id>
osagent reject <action-id>
osagent ignore "C:\Users\rocki\Downloads\some-folder"

These feedback loops help OsAgent become more useful over time.

Restore and Undo

osagent restore-report
osagent restore --last 5 --dry-run
osagent restore --action-id <action-id>

You can review recent move history and restore files back to their original locations.

Configuration

Use the CLI instead of manually editing JSON whenever possible:

osagent config show
osagent config get watched_paths
osagent config set watched_paths "[\"D:/Downloads\", \"E:/Inbox\"]"
osagent config set destination_root "D:\Organized"
osagent config set worker_count 24
osagent config set ollama_worker_count 4
osagent config set notifications_enabled true
osagent config set daemon_poll_seconds 300

Useful config keys:

• watched_paths
• destination_root
• ollama_model
• ollama_url
• worker_count
• ollama_worker_count
• notifications_enabled
• daemon_poll_seconds
• auto_organize_safe_moves
• thresholds.disk_warn_percent
• thresholds.cpu_pause_percent
• thresholds.memory_pause_percent

Command Reference

osagent --help
osagent doctor
osagent config show
osagent config get watched_paths
osagent config set watched_paths "[\"D:/Downloads\"]"
osagent scan
osagent organize --dry-run
osagent organize --apply
osagent stats
osagent duplicates
osagent suggest
osagent close 12345 --dry-run
osagent approve <action-id>
osagent reject <action-id>
osagent ignore <path>
osagent restore-report
osagent restore --last 5 --dry-run
osagent daemon start
osagent daemon status
osagent daemon stop

For detailed help:

osagent organize --help
osagent config --help
osagent daemon --help

For machine-readable output, put global flags before the subcommand:

osagent --json doctor
osagent --json scan
osagent --no-progress --json suggest

Output Philosophy

OsAgent is designed for two modes:

• Human mode: compact, review-friendly terminal summaries with colors and banners
• Script mode: structured JSON via --json

This keeps day-to-day use readable without making automation painful.

Safety Model

OsAgent is intentionally conservative.

• Safe moves can be automated
• Cleanup, close-process, and review-heavy actions are suggestion-first
• Approval remains explicit for risky actions
• Restore support exists for move operations
• Local fallbacks keep working even when Ollama is unavailable

Background Notifications

To run in the background:

osagent daemon start

To verify:

osagent daemon status

To stop:

osagent daemon stop

If notifications are enabled and review is needed, OsAgent can send a Windows desktop notification and open the generated report when clicked.

Troubleshooting

Ollama suggestions are missing

Run:

osagent doctor
ollama serve
ollama list
osagent config get ollama_model
osagent config get ollama_url

The daemon is not running

Run:

osagent daemon status
osagent daemon start

I want the full raw output

Use:

osagent --json suggest
osagent --json stats
osagent --json doctor

I moved files and want them back

Run:

osagent restore-report
osagent restore --last 10 --dry-run

Contributing

Contributions are welcome.

Good first contribution areas:

• better file classification rules
• richer process recommendations
• safer cleanup heuristics
• improved daemon/report UX
• platform support expansion
• test coverage for edge cases

Recommended workflow:

git clone <your-fork>
cd OsAgent
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .[dev]
.\.venv\Scripts\python.exe -m pytest -q

When contributing:

• keep changes local-first and privacy-aware
• prefer safe defaults
• avoid destructive automation without explicit user intent
• update docs when behavior changes

Roadmap

Near-term:

• richer process and app-level recommendations
• quieter / adaptive progress modes
• daemon logs and better background visibility
• startup integration for Windows login
• improved restore UX and historical reports

Mid-term:

• smarter learning from approvals, rejects, and ignores
• better uninstall and cleanup candidate detection
• more structured Ollama reasoning and fallback reporting
• richer duplicate analysis and reclaim estimates

Long-term:

• tray app / lightweight desktop dashboard
• cross-platform support
• plugin/tool ecosystem for app-specific cleanup workflows
• stronger policy engine for enterprise or power-user rules

Local Development

.\.venv\Scripts\python.exe -m pip install -e .[dev]
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m osagent doctor

Publishing to PyPI

python -m pip install -U build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*

Before publishing:

• update the version in pyproject.toml
• replace placeholder project URLs with your real repository URLs
• run the full test suite

Project Status

OsAgent is already useful for local file hygiene and system review, and it's evolving toward a more capable local desktop operations assistant. The current design favors safety, observability, and recoverability over magical automation.