KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#codex #developer-tools #typescript #ai-agents #claude-code #python #mcp #react #cli #macos #ai-agent #deepseek-harness

Desktop-Tiny-Agent-Framework

★ 80 Open GitHub ↗

Desktop Tiny Agent is a lightweight, modular desktop intelligent agent framework. It offers plugin extensibility, task scheduling (sync/async), configuration management, and unified logging, supporting dynamic plugin loading for task execution. With an out-of-the-box CLI and examples, it’s ideal for quickly building extensible automation assistants

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Desktop Tiny Agent

[![PyPI version](https://badge.fury.io/py/desktop-tiny-agent.svg)](https://badge.fury.io/py/desktop-tiny-agent)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://badge.fury.io/py/desktop-tiny-agent.svg)](https://badge.fury.io/py/desktop-tiny-agent)
[![Code Coverage](https://img.shields.io/badge/coverage-80%25-green.svg)](https://badge.fury.io/py/desktop-tiny-agent)

A lightweight, modular desktop intelligent agent framework designed for rapidly building desktop automation applications.

## 🚀 Features

- **Lightweight**: Core engine only requires a few MB, starts quickly
- **Modular**: Plugin-based architecture, load functionality on demand
- **Cross-platform**: Supports Windows, macOS, and Linux
- **Easy to extend**: Simple API design, rapid plugin development
- **Flexible configuration**: Supports multiple configuration methods
- **Real-time monitoring**: Built-in task execution monitoring and logging system
- **CLI support**: Provides complete command-line interface
- **Async support**: Supports both synchronous and asynchronous operation modes

## 💡 Project Purpose

Desktop Tiny Agent is a powerful desktop automation framework that can help you with:

### 🖥️ System Monitoring & Management
- **Real-time monitoring**: Monitor CPU, memory, disk usage to detect system issues promptly
- **Process management**: View and manage running processes, optimize system performance
- **Resource statistics**: Generate system resource usage reports for performance tuning
- **Automated maintenance**: Automatically clean temporary files, free up disk space

### 📁 File Management Automation
- **Smart organization**: Automatically categorize and organize documents, images, videos, etc.
- **Batch operations**: Batch rename, move, copy files to improve work efficiency
- **File monitoring**: Monitor specified directory changes, automatically backup important files
- **Duplicate detection**: Identify and handle duplicate files, save storage space

### 🔄 Task Scheduling & Automation
- **Scheduled tasks**: Set up scheduled execution of system maintenance, data backup, etc.
- **Conditional triggers**: Automatically execute corresponding operations based on system status or file changes
- **Task chains**: Combine multiple tasks into workflows for complex automation
- **Failure retry**: Intelligent retry mechanism ensures reliable task execution

### 🛠️ Development & Operations Tools
- **Development assistant**: Automate code formatting, test running, build deployment
- **Environment management**: Automatically configure development environment, manage dependencies
- **Log analysis**: Collect and analyze application logs, quickly locate issues
- **Performance testing**: Automated performance testing, continuous application performance monitoring

### 🏠 Personal Life Assistant
- **Desktop organization**: Automatically organize desktop icons, maintain clean work environment
- **Media management**: Automatically download, categorize, organize music, videos, images
- **Reminder notifications**: Timely reminders for important matters, manage personal schedule
- **Data synchronization**: Automatically sync important files to cloud, prevent data loss

## 📋 Specific Application Scenarios

### Scenario 1: Developer's Automated Workflow
```python
# Automated code quality checks
agent.schedule_task("run_tests", "daily")
agent.schedule_task("format_code", "on_save")
agent.schedule_task("update_dependencies", "weekly")
```

### Scenario 2: System Administrator's Monitoring Tool
```python
# Real-time system monitoring
agent.execute_task("start_monitoring", interval=30)
agent.schedule_task("cleanup_temp_files", "daily")
agent.schedule_task("backup_important_data", "weekly")
```

### Scenario 3: Content Creator's Media Management
```python
# Automated media file organization
agent.execute_task("organize_files", source="~/Downloads", target="~/Media")
agent.schedule_task("backup_media", "daily")
agent.execute_task("remove_duplicates", path="~/Pictures")
```

### Scenario 4: Office Worker's Document Automation
```python
# Automated document backup and organization
agent.schedule_task("backup_documents", "hourly")
agent.execute_task("organize_files", source="~/Documents")
agent.schedule_task("cleanup_recycle_bin", "weekly")
```

## 📋 System Requirements

- **Python**: 3.8 or higher
- **Operating System**: Windows 10+, macOS 10.14+, Ubuntu 18.04+
- **Memory**: Minimum 128MB RAM
- **Disk Space**: Minimum 50MB available space

## 🏗️ Architecture

```
Desktop Tiny Agent
├── Core Engine
├── Plugin System
├── Task Scheduler
├── Configuration Manager
├── API Gateway
└── Plugin Store
```

## 📁 Project Structure

```
project-new/
├── config/                 # Configuration directory
│   └── agent_config.yaml  # Agent configuration file
├── docs/                  # Documentation directory
│   ├── project-structure.md
│   └── user-guide.md
├── examples/              # Example code
│   └── basic_usage.py    # Basic usage examples
├── plugins/               # Built-in plugins
│   ├── file_manager.py   # File management plugin
│   └── system_monitor.py # System monitoring plugin
├── src/                   # Source code
│   └── desktop_tiny_agent/
│       ├── core/         # Core modules
│       ├── utils/        # Utility modules
│       └── cli.py       # Command-line interface
├── tests/                 # Test code
├── pyproject.toml        # Project configuration
└── README.md
```

## 📦 Quick Start

### Installation

#### Install from PyPI (Recommended)

```bash
pip install desktop-tiny-agent
```

#### Install from Source

```bash
git clone https://github.com/desktop-tiny-agent/desktop-tiny-agent.git
cd desktop-tiny-agent
pip install -e .
```

#### Development Environment Installation

```bash
git clone https://github.com/desktop-tiny-agent/desktop-tiny-agent.git
cd desktop-tiny-agent
pip install -e ".[dev]"
```

### Basic Usage

#### Python API Usage

```python
from desktop_tiny_agent import Agent

# Create agent instance
agent = Agent()

# Register plugins
agent.load_plugin("file_manager")
agent.load_plugin("system_monitor")

# Execute task
agent.execute_task("monitor_system")

# More practical examples
# 1. System monitoring
system_info = agent.execute_task("get_system_info")
cpu_usage = agent.execute_task("get_cpu_info")
memory_info = agent.execute_task("get_memory_info")

# 2. File management
agent.execute_task("organize_files", source="~/Downloads", target="~/Organized")
agent.execute_task("backup_file", source="~/Documents", target="~/Backup")

# 3. Task scheduling
agent.schedule_task("cleanup_temp_files", "daily")
agent.schedule_task("backup_important_data", "weekly")
agent.schedule_task("check_system_health", "2h")
```

#### Command Line Usage

```bash
# View help
desktop-tiny-agent --help

# Start agent
desktop-tiny-agent start

# List available plugins
desktop-tiny-agent plugins list

# Execute task
desktop-tiny-agent task execute get_system_info

# View agent status
desktop-tiny-agent status

# More practical commands
# System monitoring
desktop-tiny-agent task execute get_cpu_info
desktop-tiny-agent task execute get_memory_info
desktop-tiny-agent task execute start_monitoring --interval 30

# File management
desktop-tiny-agent task execute list_directory --path ~/Documents
desktop-tiny-agent task execute organize_files --source ~/Downloads --target ~/Organized
desktop-tiny-agent task execute backup_file --source ~/Pictures --target ~/Backup

# Task scheduling
desktop-tiny-agent task schedule cleanup_temp_files --interval daily
desktop-tiny-agent task schedule backup_data --interval weekly
desktop-tiny-agent task schedule health_check --interval 2h

# View task status
desktop-tiny-agent task list
desktop-tiny-agent task status cleanup_temp_files
```

## ⚙️ Configuration

### Configuration File Locations

- **Global configuration**: `~/.config/desktop-tiny-agent/config.yaml`
- **Project configuration**: `./config/agent_config.yaml`
- **Environment variables**: Support configuration override via environment variables

### Configuration Example

```yaml
# config/agent_config.yaml
agent:
  name: "My Desktop Agent"
  version: "1.0.0"
  log_level: "INFO"
  plugins_dir: "./plugins"
  
plugins:
  system_monitor:
    enabled: true
    interval: 30
    metrics: ["cpu", "memory", "disk", "network"]
    alert_thresholds:
      cpu_usage: 80
      memory_usage: 85
      disk_usage: 90
  
  file_manager:
    enabled: true
    watch_dirs: ["~/Documents", "~/Downloads", "~/Pictures"]
    auto_backup: true
    backup_schedule: "daily"
    organize_rules:
      documents: ["*.pdf", "*.doc", "*.docx", "*.txt"]
      images: ["*.jpg", "*.png", "*.gif"]
      videos: ["*.mp4", "*.avi", "*.mov"]
    
  # Custom plugin configuration
  custom_plugin:
    enabled: true
    api_key: "${CUSTOM_API_KEY}"
    webhook_url: "https://webhook.site/your-endpoint"

tasks:
  default_timeout: 300
  max_concurrent: 5
  retry_count: 3
  
  # Predefined tasks
  scheduled_tasks:
    daily_cleanup:
      task: "cleanup_temp_files"
      schedule: "0 2 * * *"  # 2 AM daily
      enabled: true
    
    weekly_backup:
      task: "backup_important_data"
      schedule: "0 3 * * 0"  # 3 AM every Sunday
      enabled: true
    
    health_check:
      task: "check_system_health"
      schedule: "*/30 * * * *"  # Every 30 minutes
      enabled: true

notifications:
  enabled: true
  channels: ["desktop", "email", "webhook"]
  email:
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    username: "${EMAIL_USERNAME}"
    password: "${EMAIL_PASSWORD}"
```

## 🔌 Plugin Development

### Basic Plugin Structure

```python
from desktop_tiny_agent import Plugin

class MyPlugin(Plugin):
    name = "my_plugin"
    version = "1.0.0"
    description = "My custom plugin"
    author = "Your Name"
    
    def on_load(self):
        """Called when plugin loads"""
        print("Plugin loaded")
    
    def on_unload(self):
        """Called when plugin unloads"""
        print("Plugin unloaded")
    
    def execute(self, task_name, **kwargs):
        """Execute task"""
        if task_name == "my_task":
            return self.do_something()
        return {"error": "Unknown task"}
    
    def do_something(self):
        return {"result": "Task completed"}
```

### Plugin Lifecycle

1. **Load phase**: `on_load()` method is called
2. **Run phase**: Plugin executes tasks normally
3. **Unload phase**: `on_unload()` method is called

### Plugin Publishing

```bash
# Build plugin package
python setup.py sdist bdist_wheel

# Publish to PyPI
twine upload dist/*
```

## 🧪 Testing and Development

### Running Tests

```bash
# Run all tests
pytest

# Run tests with coverage report
pytest --cov=desktop_tiny_agent --cov-report=html

# Run specific test file
pytest tests/test_agent.py
```

### Code Quality Checks

```bash
# Code formatting
black src/ tests/
isort src/ tests/

# Code checking
flake8 src/ tests/
mypy src/

# Run all checks
pre-commit run --all-files
```

### Development Tools

- **pytest**: Testing framework
- **black**: Code formatting
- **isort**: Import sorting
- **flake8**: Code style checking
- **mypy**: Type checking
- **pre-commit**: Git hook management

## 📚 Documentation

- [User Guide](docs/user-guide.md) - Detailed usage instructions
- [Project Structure](docs/project-structure.md) - Project architecture explanation
- [Plugin Development Guide](docs/plugin-development.md) - Plugin development tutorial
- [API Reference](docs/api-reference.md) - Complete API documentation
- [Configuration Guide](docs/configuration.md) - Configuration options detailed explanation

## 🚨 Troubleshooting

### Common Issues

#### 1. Plugin Loading Failure

```bash
# Check plugin directory permissions
ls -la plugins/

# View detailed error logs
desktop-tiny-agent --log-level DEBUG
```

#### 2. Task Execution Timeout

```yaml
# Increase timeout in configuration file
tasks:
  default_timeout: 600  # 10 minutes
```

#### 3. High Memory Usage

```yaml
# Limit concurrent tasks
tasks:
  max_concurrent: 3
```

### Getting Help

- **GitHub Issues**: [Report Issues](https://github.com/desktop-tiny-agent/desktop-tiny-agent/issues)
- **Discussions**: [Community Discussions](https://github.com/desktop-tiny-agent/desktop-tiny-agent/discussions)
- **Wiki**: [Usage Tips](https://github.com/desktop-tiny-agent/desktop-tiny-agent/wiki)

## 📈 Performance Optimization

### Recommended Configuration

```yaml
agent:
  log_level: "WARNING"  # Use WARNING level in production
  
plugins:
  system_monitor:
    interval: 60  # Increase monitoring interval
    
tasks:
  max_concurrent: 3  # Limit concurrency
  default_timeout: 300  # Set reasonable timeout
```

### Monitoring Metrics

- CPU usage rate
- Memory usage
- Task execution time
- Plugin response time

## 🔄 Changelog

### v0.1.0 (Current Version)

- ✨ Initial version release
- 🔌 Basic plugin system
- 📋 Task scheduling functionality
- ⚙️ Configuration management
- 🖥️ CLI interface

### Coming Soon

- 🌐 Web management interface
- 📊 Visual monitoring dashboard
- 🔐 Permission management system
- 📱 Mobile support

## 🤝 Contributing

We welcome all forms of contributions!

### Ways to Contribute

1. **Report Bugs**: Report issues in [GitHub Issues](https://github.com/desktop-tiny-agent/desktop-tiny-agent/issues)
2. **Feature Suggestions**: Propose suggestions in [Discussions](https://github.com/desktop-tiny-agent/desktop-tiny-agent/discussions)
3. **Code Contributions**: Fork the project and submit Pull Requests
4. **Documentation Improvements**: Help improve documentation and examples
5. **Community Support**: Answer other users' questions

### Development Process

1. Fork the project repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Create a Pull Request

### Code Standards

- Follow PEP 8 code style
- Add appropriate type annotations
- Write test cases
- Update relevant documentation

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

## 🌟 Acknowledgments

Thanks to all developers who contributed to this project!

### Core Contributors

- [Desktop Tiny Agent Team](https://github.com/desktop-tiny-agent) - Core development team

### Open Source Dependencies

- [Click](https://github.com/pallets/click) - Command-line interface library
- [Pydantic](https://github.com/pydantic/pydantic) - Data validation library
- [Rich](https://github.com/Textualize/rich) - Terminal beautification library
- [Watchdog](https://github.com/gorakhargosh/watchdog) - File monitoring library

## 📞 Contact Us

- **Project Homepage**: [https://github.com/desktop-tiny-agent/desktop-tiny-agent](https://github.com/desktop-tiny-agent/desktop-tiny-agent)
- **Documentation**: [https://desktop-tiny-agent.readthedocs.io/](https://desktop-tiny-agent.readthedocs.io/)
- **Issue Reports**: [GitHub Issues](https://github.com/desktop-tiny-agent/desktop-tiny-agent/issues)
- **Community Discussions**: [GitHub Discussions](https://github.com/desktop-tiny-agent/desktop-tiny-agent/discussions)
- **Email**: team@desktop-tiny-agent.com

---

⭐ If this project helps you, please give us a star!

Desktop-Tiny-Agent-Framework

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README