SUDARI

Product Introduction

1. Definition: SUDARI is a free, open-source desktop companion application — technically categorized as an Electron-based cross-platform desktop pet and ambient productivity utility — built around a hand-animated pixel-art river otter. It runs as a lightweight overlay window on Windows 10/11 (x64) and macOS 12 or later (Apple Silicon and Intel), distributed as a Setup.exe installer, portable EXE, and DMG/ZIP bundles. The current stable build is v3.0.0, licensed under Apache-2.0, and maintained publicly at the GitHub repository seojaeohcode/SUDARI.

2. Core Value Proposition: SUDARI exists to convert an otherwise sterile desktop environment into a low-friction focus and wellbeing layer. It delivers a shell-shaped Pomodoro timer, context-aware micro-reminders (hydrate, stretch, eat), and local AI agent completion signals through a single animated character, without requiring an account, a subscription, cloud connectivity, or telemetry. The primary keyword cluster it occupies — desktop pet, desktop companion, pixel otter, Pomodoro overlay, productivity mascot, Electron desktop app, open-source focus timer — is unified by one proposition: ambient behavioral nudging that users actually tolerate because it is character-driven rather than notification-driven.

Main Features

1. Cursor Tracking and Reactive Animation Engine: The otter continuously follows the user's cursor with its eyes and reacts to physical interaction. Dragging the pet repositions it on the desktop, and the v3.0.0 release added explicit recovery logic for lost mouse capture during drag operations. Head-rubbing triggers distinct happy-eye and heart-particle animation states. The animation system comprises 17 hand-made pixel animations driven by a shared engine that is also exposed to a browser-based playground (web/demo.html) served over a local Python HTTP server, allowing developers to test the same animation logic outside the packaged Electron shell.

2. Input-Reactive Behavior (Kneading and Shell-Cracking): When the user types, SUDARI performs a keyboard-kneading animation on a miniature pixel keyboard. When the user scrolls, it opens and cracks a shell between its paws. Technically, these reactions are powered by a native input hook that receives OS-level input events and derives only activity signals — press counts and scroll events — rather than storing typed text, key codes, or content. Keyboard and scroll reactions on both platforms require the user to grant Accessibility or Input Monitoring permissions via the menu bar option "Enable keyboard & scroll reactions," after which the app must be restarted. All other features remain fully functional without these permissions, which is a deliberate privacy-preserving permission scope.

3. Shell-Shaped Pomodoro Timer with Fireworks Completion: SUDARI includes a built-in Pomodoro timer rendered as a shell that stays physically near the otter sprite, scales together with the pet's selected size, and repositions dynamically to make room for movement. v2.0.0 introduced redrawn shell art with readable focus/break labels and badge text that fits correctly. Completing a focus session triggers a fireworks animation. The timer is accessible through the right-click menu or the tray/menu-bar icon and supports break intervals alongside focus intervals.

4. AI Agent Completion Signals via Loopback HTTP Endpoints: SUDARI exposes a local-only HTTP listener on 127.0.0.1:37421 with two endpoints: /thinking and /done. Developers wire these into their AI tool's start and finish hooks using a single curl command with a one-second max timeout, causing the otter to enter a working state and then celebrate when the task finishes. This works with any tool capable of executing a shell command at task start or completion — including Claude Code, whose hook example is documented in the repository. No AI account, API key, or cloud service is required for SUDARI itself. On Windows PowerShell, curl.exe should be used rather than the curl alias.

5. Wellbeing Micro-Reminders: The application issues gentle, scheduled prompts to drink water, stretch, and eat. These are configurable alongside a pinned note feature and custom name insertion into dialogue lines. Reminders are delivered through the character's dialogue system rather than system notifications, keeping the interaction ambient and non-disruptive.

6. Deep Customization: Fur, Size, Patterns, and Dialogue: Users can choose from eight fur color presets or use a custom color picker, apply one of four patterns, and scale the pet between 2× and 5×. The otter can be positioned anywhere on screen by dragging, and "Peek mode" tucks it against the screen edge for reduced visual footprint. On small displays, the pet automatically resizes to fit. User-authored notes and messages are preserved verbatim and are never translated by the localization layer.

7. Full Localization Across 12 Languages with RTL Support: SUDARI ships with English, Korean, Japanese, Simplified Chinese, Traditional Chinese, Spanish, French, German, Portuguese (Brazil), Italian, Russian, and Arabic. Arabic activates a right-to-left layout for dialogue, menus, timer labels, and settings. Windows setup prompts for language selection at install time (defaulting to English), while portable Windows and macOS builds present a first-launch language picker. The selection persists in the local settings file and governs all UI surfaces consistently.

Problems Solved

1. Pain Point: Standard productivity timers and reminder apps suffer from notification fatigue — they interrupt flow with modal alerts, badge counts, and system-level popups that users quickly mute or dismiss. SUDARI reframes the same behavioral nudging as ambient character animation, which reduces alert habituation and produces sustained engagement. It also addresses the problem of opaque, disconnected AI workflows: developers currently have no lightweight visual feedback for long-running agent tasks, and SUDARI solves this with a sub-second local endpoint that requires no orchestration framework.

2. Target Audience: Primary personas include software developers and engineers running AI coding agents (Claude Code, local LLM tooling) who want completion feedback without switching windows; remote and hybrid knowledge workers managing focus sessions in the Pomodoro method; students and researchers needing lightweight timeboxing; users with ADHD or attention-regulation challenges who benefit from external, low-pressure cues; localization-conscious users in Korean, Japanese, Chinese, Arabic, and European markets; and privacy-first users who reject telemetry-based desktop utilities. Secondary audiences include pixel-art enthusiasts, desktop customization communities, and open-source contributors seeking an approachable Apache-2.0 Electron codebase.

3. Use Cases: SUDARI is essential in scenarios such as a 25-minute deep-work block where the user needs a visual focus anchor without a full-screen timer; an AI agent running a multi-minute refactor or test suite where the /thinking and /done hooks provide passive status feedback; a long typing session in an IDE or terminal where the kneading animation confirms input activity at a glance; a scrolling-heavy research session where the shell-cracking reaction provides tactile-feeling feedback; and hydration or posture management during back-to-back video calls. It is also used in development environments as a test subject for Electron overlay windowing, sprite-generation pipelines, and multi-language UI testing.

Unique Advantages

1. Differentiation: Unlike commercial desktop pet applications that bundle ads, account systems, or cloud sync, SUDARI is fully open source under Apache-2.0 with the sprite generator, artwork, and complete source code included in the repository. Unlike conventional Pomodoro apps (browser extensions, menu-bar-only timers), SUDARI couples the timer to a persistent animated character that reacts to real input events. Unlike AI observability dashboards, SUDARI requires zero integration framework — a single curl call to a loopback port is sufficient. It also differentiates on permission discipline: the input hook derives only activity counts, and processing stays local.

2. Key Innovation: The core innovation is the combination of a character-driven ambient interface with a minimal, stateless local integration protocol. The 127.0.0.1:37421 endpoint design means SUDARI never needs outbound network access, credentials, or a daemon, making it compatible with air-gapped and privacy-restricted environments. The shared animation engine — usable both inside Electron and in a plain browser via web/demo.html — allows the same 17-animation state machine to be prototyped and tested independently of the packaged app. Configuration is deliberately trivial: a single local JSON file at %APPDATA%\sudari\config.json on Windows or ~/Library/Application Support/sudari/config.json on macOS, with no registry writes, no cloud backup, and no analytics pipeline.

3. Build and Extensibility Advantages: Developers can clone the repository, run npm ci, and start a local instance with npm start on Node.js 22.12 or later; test suites are exposed via npm test and npm run test:smoke. Platform builds use npm run dist on Windows and npm run dist:mac on macOS, and sprite regeneration requires only Python with Pillow. No Python or Node.js runtime is required to use the packaged application. Because builds are unsigned, Windows SmartScreen may prompt for confirmation and macOS Gatekeeper may block the ad-hoc signed, non-notarized app — a documented tradeoff of independent, open-source distribution that the project addresses with a dedicated Mac installation guide and published SHA-256 checksums.

Frequently Asked Questions (FAQ)

1. Is SUDARI free, and does it require an account or send telemetry? Yes, SUDARI is completely free and open source under the Apache-2.0 license. It requires no account, no subscription, and no sign-in. The application sends no analytics or telemetry of any kind. Its only network listener is bound to loopback at 127.0.0.1:37421 to receive optional AI agent signals, and all settings are stored locally in a JSON file under %APPDATA%\sudari\config.json on Windows or ~/Library/Application Support/sudari/config.json on macOS.

2. Does SUDARI record what I type? No. The native input handler receives OS-level input events but only counts key presses and scroll events as activity signals. It does not store typed text, key codes, or content, and no input data leaves the machine. Keyboard and scroll reactions are opt-in and require you to grant Accessibility or Input Monitoring permission, after which the app must be restarted; every other feature works without those permissions.

3. Which file should I download for Windows or Mac? For Windows 10/11 on an x64 Intel or AMD processor, download Sudari-3.0.0-Setup.exe for a standard install or Sudari-3.0.0-Portable.exe for a no-installation run. For Mac, open  → About This Mac: if it reports "Chip: Apple M…", download Sudari-3.0.0-mac-arm64.dmg; if it reports "Processor: Intel…", download Sudari-3.0.0-mac-x64.dmg. ZIP alternatives and SHA-256 checksums are listed on the release page. The product name "MacBook Air" or "MacBook Pro" alone does not indicate the chip architecture.

4. How do I connect SUDARI to my AI agent or coding tool? Call the local endpoints from your tool's start and finish hooks using curl --max-time 1 http://127.0.0.1:37421/thinking at task start and curl --max-time 1 http://127.0.0.1:37421/done at completion. On Windows PowerShell, use curl.exe. This works with any tool that can execute a shell command at task start or completion, including Claude Code, for which a hook example is provided in the repository documentation. The integration is optional and requires no AI account for SUDARI itself.

5. Why does macOS say the app is damaged or blocked, and why does Windows SmartScreen warn me? SUDARI builds are unsigned and, on macOS, ad-hoc signed but not Apple-notarized, so Gatekeeper and SmartScreen may display warnings. Version 3.0.0 repaired Mac bundle signatures and added checks that launch the actual DMG and ZIP apps. On Windows, verify the download originates from the official seojaeohcode/SUDARI repository, then choose "More info → Run anyway." On macOS, follow the repository's dedicated Mac installation guide for "damaged" or blocked-app messages.

6. How much can I customize the otter, and how many languages are supported? SUDARI offers eight fur color presets plus a custom color picker, four patterns, and scaling from 2× to 5×, with automatic resizing on small displays. You can drag the otter to reposition it, insert your own name into dialogue, pin a personal note, and enable Peek mode to tuck it against the screen edge. The interface supports 12 languages — English, Korean, Japanese, Simplified Chinese, Traditional Chinese, Spanish, French, German, Portuguese (Brazil), Italian, Russian, and Arabic — with Arabic rendering in a right-to-left layout. Your own notes and messages are never altered by the localization system.