{"id":51842147,"url":"https://github.com/uiu-developers-hub/desktop-pet","last_synced_at":"2026-07-23T07:01:28.914Z","repository":{"id":371774663,"uuid":"1303200397","full_name":"UIU-Developers-Hub/desktop-pet","owner":"UIU-Developers-Hub","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-16T21:29:04.000Z","size":2424,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T23:47:21.100Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UIU-Developers-Hub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-16T20:06:04.000Z","updated_at":"2026-07-16T21:29:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/UIU-Developers-Hub/desktop-pet","commit_stats":null,"previous_names":["uiu-developers-hub/desktop-pet"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/UIU-Developers-Hub/desktop-pet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UIU-Developers-Hub%2Fdesktop-pet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UIU-Developers-Hub%2Fdesktop-pet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UIU-Developers-Hub%2Fdesktop-pet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UIU-Developers-Hub%2Fdesktop-pet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UIU-Developers-Hub","download_url":"https://codeload.github.com/UIU-Developers-Hub/desktop-pet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UIU-Developers-Hub%2Fdesktop-pet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35793062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-23T07:01:27.943Z","updated_at":"2026-07-23T07:01:28.900Z","avatar_url":"https://github.com/UIU-Developers-Hub.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Desktop Pet\n\nDesktop Pet is a Windows desktop companion built with Python, PyQt6, SQLite, and\nOllama. It lives on the desktop as a transparent always-on-top sprite, opens a\ntabbed chat/task panel on click or hotkey, tracks coarse work sessions locally,\nand can offer gentle proactive nudges when the user has due tasks, a long active\nstreak, a focus pause, a distraction pattern, or high local device load.\n\nThe project is small enough to clone, run, inspect, and contribute to without a\nlarge framework. It is also privacy-conscious: the keyboard hook keeps timing\nmetadata only, foreground-window tracking stores coarse app buckets instead of\nraw titles, and long-term assistant context is stored as summaries rather than\nraw transcripts.\n\n## Feature List\n\n### Desktop Companion\n\n- Transparent, always-on-top pet sprite with alpha masking so transparent pixels\n  do not steal clicks.\n- Draggable sprite that snaps back to the desktop ground line when released.\n- Idle, talking, and rest visuals, with renderer support for reaction/action\n  sprite strips from `assets/sprites/`, CatPackFree, or generated placeholders.\n- Idle attention behavior that can face the user or glance toward the active app\n  window using coarse window geometry.\n- Lightweight proactive mini-bubble that opens the full panel when clicked.\n- System tray app with quick access to chat, work-status questions, and quit.\n- Global hotkey support, defaulting to `Ctrl+Alt+Space`.\n\n### Chat And Planning\n\n- Tabbed panel for Chat, Tasks, and Archive, with minimize, fullscreen, and\n  Settings controls.\n- Chat quick actions for day planning, next-step selection, and work-status\n  review.\n- Markdown rendering in assistant replies, including fenced code blocks and\n  links.\n- Natural-language todo creation and completion through structured model replies.\n- Task planner with quick add, optional due dates, priority, notes, filters,\n  completion, restore, delete, and archive views.\n- SQLite storage for open tasks, completed tasks, priorities, notes, due dates,\n  and timestamps.\n- Persistent summarized memory for user preferences, project plans, working\n  style, and compact conversation rollups, so chat context survives restarts\n  without storing raw transcripts.\n\n### Focus And Nudges\n\n- Work tracking based on Windows idle time and coarse foreground app buckets.\n- Recent work-pattern summaries for prompts and planning.\n- Focus-sleep mode during intense typing, followed by a short privacy-safe\n  check-in after the user pauses.\n- Scheduled nudges for due tasks, long active streaks, and return-from-break\n  moments.\n- Smart proactive nudges for distractions, overdue tasks, productive streaks,\n  brief jokes, and local resource pressure.\n- Deterministic fallback nudge text when the model is unavailable or output\n  cannot be parsed.\n\n### Models, Settings, And Voice\n\n- Ollama local chat support, Ollama Cloud support, and automatic cloud fallback\n  when local CPU/RAM is high and cloud credentials are configured.\n- Settings dialog for local/cloud hosts, model names, model detection, default\n  chat route, request timeout, cloud fallback, API key storage, and voice output.\n- Device telemetry gate that avoids starting local model calls when the machine\n  is already busy.\n- Optional Microsoft SAPI voice output for pet replies, using the default\n  Windows voice.\n- Friendly offline, timeout, model-missing, and credential-error messages.\n\n## Requirements\n\n- Windows 10 or newer.\n- Python 3.11 or newer.\n- Ollama for local model calls.\n- A pulled local model, by default `nemotron-3-nano:4b`.\n- Optional: an Ollama Cloud API key for cloud routing/fallback.\n- Optional: the default Windows voice for spoken pet replies.\n\nThe app uses Windows-specific dependencies (`pywin32`, `keyboard`, and Win32 idle\nAPIs), so Linux/macOS are not supported runtime targets.\n\n## Quick Start\n\nClone the repository, create a virtual environment, install dependencies, and\nrun the app:\n\n```powershell\ngit clone \u003cyour-fork-or-repo-url\u003e desktop-pet\ncd desktop-pet\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npip install -r requirements.txt\npython main.py\n```\n\nFor local chat, make sure Ollama is running and the configured model is\navailable:\n\n```powershell\nollama serve\nollama pull nemotron-3-nano:4b\nollama list\n```\n\nIf Ollama is not reachable, the app still opens and returns friendly fallback\nmessages for model-backed features.\n\n## Usage\n\n- Left-click the pet, left-click the tray icon, or press `Ctrl+Alt+Space` to\n  open the task/chat panel.\n- Right-click the tray icon for the menu.\n- Drag the pet to move it temporarily; it snaps back to the bottom ground line on\n  release.\n- Use the Tasks tab to add, filter, complete, restore, and delete tasks.\n- Use the Chat tab to ask planning questions or create todos in natural\n  language.\n- Open Settings from the panel to choose local/cloud routing, set hosts/models,\n  detect models, save an Ollama Cloud API key, set request timeout, enable cloud\n  fallback, and turn voice replies on or off.\n- Click a proactive mini-bubble to open the full panel with the same message in\n  context.\n\n## Start With Windows\n\nAfter creating `.venv` and installing dependencies, run:\n\n```powershell\n.\\enable_startup.bat\n```\n\nThe script creates a per-user Startup shortcut that launches `main.py` with\n`.venv\\Scripts\\pythonw.exe`. To remove the shortcut, run:\n\n```powershell\n.\\disable_startup.bat\n```\n\n## Configuration\n\nDefault values live in `config.py`. User-edited LLM settings are saved to\n`data/settings.json`, which is ignored by Git because it can contain a cloud API\nkey.\n\nCommon settings:\n\n```python\nHOTKEY = \"ctrl+alt+space\"\nPROACTIVE = True\nOLLAMA_URL = \"http://localhost:11434\"\nOLLAMA_MODEL = \"nemotron-3-nano:4b\"\nOLLAMA_CLOUD_URL = \"https://ollama.com\"\nOLLAMA_CLOUD_MODEL = \"gpt-oss:120b\"\nOLLAMA_CLOUD_FALLBACK = True\nCHAT_PROVIDER = \"auto\"\nLLM_TIMEOUT_SECONDS = 30\nLLM_DEVICE_GATING = True\n```\n\nSmart nudge and work tracking thresholds are also in `config.py`, including\ntyping intensity, wake-check-in delays, idle thresholds, break intervals, CPU/RAM\nlimits, proactive cooldowns, and memory limits. User-edited values for routing,\nmodel names, timeout, cloud fallback, API key, and voice output are stored in\n`data/settings.json`.\n\n## Data and Privacy\n\nRuntime data is created under `data/`:\n\n- `data/pet.db`: tasks, work sessions, and summarized assistant memory such as\n  durable preferences, project context, and rolling conversation rollups.\n- `data/settings.json`: local/cloud model routing settings and optional cloud API\n  key, plus the voice-output preference.\n\nThe app does not store raw chat transcripts, keyboard-hook typed text, raw window\ntitles, screenshots, or screen contents. See [docs/PRIVACY.md](docs/PRIVACY.md)\nfor the privacy boundary that contributors should preserve.\n\n## Project Layout\n\n```text\ndesktop-pet/\n  main.py                  # Qt application composition and tray wiring\n  config.py                # Defaults for paths, timings, models, and thresholds\n  enable_startup.bat       # Register a per-user Windows Startup shortcut\n  disable_startup.bat      # Remove the Startup shortcut\n  ai/\n    llm_client.py          # Ollama local/cloud client and routing\n  data/\n    scheduler.py           # Qt timer for due tasks and break events\n    settings_store.py      # JSON settings loader/saver\n    todo_store.py          # SQLite todo store\n    work_store.py          # SQLite work-session store\n    memory_store.py        # SQLite summarized memory store\n  pet/\n    behavior.py            # Pet state machine and proactive behavior\n    chat_bubble.py         # Chat, planner, archive, and todo extraction UI\n    device_monitor.py      # CPU/RAM/battery snapshots\n    hotkeys.py             # Global hotkey wrapper\n    input_activity.py      # Timestamp-only keyboard activity monitor\n    mini_bubble.py         # Lightweight proactive speech bubble\n    renderer.py            # Sprite rendering, masking, dragging, and animation\n    settings_dialog.py     # LLM routing/settings dialog\n    smart_nudge.py         # Smart nudge selection and message generation\n    voice.py               # Optional Microsoft SAPI voice output\n    window_tracker.py      # Foreground window geometry helpers\n    work_tracker.py        # Idle/work-session tracker\n  assets/\n    pet_icon.png           # Tray/header/startup shortcut icon\n    sprites/               # Runtime sprite strips\n    CatPackFree/           # Fallback sprite pack\n  docs/\n    ARCHITECTURE.md\n    PRIVACY.md\n    USER_CONTEXT.md\n```\n\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for runtime flow, threading,\ndata model, LLM routing, and asset loading notes.\n\n## Development\n\nInstall dependencies and run the app from the repository root:\n\n```powershell\npip install -r requirements.txt\npython main.py\n```\n\nRun the syntax check before submitting changes:\n\n```powershell\npython -m compileall -q main.py config.py ai data pet\n```\n\nThere is not a full automated test suite yet. When changing behavior, manually\ntest the affected tray, panel, task, tracking, or LLM workflow on Windows.\n\n## Contributing\n\nContributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), keep\nchanges focused, and update docs when behavior or privacy boundaries change.\n\nImportant contribution rules:\n\n- Do not persist typed text.\n- Do not store or send raw foreground window titles.\n- Keep blocking LLM/network calls off the Qt UI thread.\n- Keep Windows-only imports guarded so modules remain easy to inspect.\n- Do not commit `.venv/`, `data/pet.db`, `data/settings.json`, `__pycache__/`, or\n  other generated local state.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuiu-developers-hub%2Fdesktop-pet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuiu-developers-hub%2Fdesktop-pet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuiu-developers-hub%2Fdesktop-pet/lists"}