CoFit

简体中文 | English

CoFit is a lightweight macOS desktop pet that helps you take short movement breaks while waiting for work to finish. It sits as a floating cat on the desktop, shows small motion prompts, and can launch a custom follow-along exercise video.

The current mascot is based on a custom gray-and-white cat design. The app is built with SwiftPM and AppKit.

Features

• Floating desktop pet window that stays above normal windows.
• Draggable position with automatic restore on next launch.
• Position safety check: if the saved window position is outside visible screens, CoFit returns to the bottom-right corner.
• Manual movement routines for expected wait time:
  • 1 minute
  • 3 minutes
  • 10 minutes
• Sedentary reminder based on keyboard and mouse activity.
• Reminder bubble with direct choices:
  • 1 minute built-in routine
  • 3 minute built-in routine
  • 10 minute built-in routine
  • Open follow-along video
  • Ignore this reminder
• Custom follow-along URL configurable in settings.
• Custom pet appearance from imported GIF files, with one-click restore to the default gray-and-white cat.
• After 5 minutes of continuous computer activity, the idle pet may fall asleep; clicking it or showing a reminder wakes it again.
• Lock screen / screen sleep handling: pet switches to sleeping and pauses animation.
• GIF-based pet animations:
  • idle
  • prompt / paw wave
  • coaching / stretch
  • resting
  • tail wag
  • sleeping
• GIF frame cache to avoid repeated decoding when switching pet states.
• Release .app packaging script.

Current Sedentary Logic

CoFit no longer tries to detect whether Codex is actively running. That signal was not reliable enough from outside the Codex app.

The reminder logic is now intentionally simple:

1. CoFit tracks a continuous active-work timer.
2. If either the keyboard or mouse was active within the last 3 minutes, the active-work timer keeps accumulating.
3. If both keyboard and mouse are inactive for more than 3 minutes, the active-work timer resets.
4. When active-work time reaches the configured sedentary threshold, CoFit shows a reminder.
5. It will not show a reminder while:
   • a movement routine is already running,
   • a reminder is already visible,
   • the app is in reminder cooldown,
   • the screen is locked or sleeping.

Project Structure

.
├── CoFitApp/
│   ├── AppDelegate.swift
│   ├── ExerciseRoutine.swift
│   ├── PetView.swift
│   ├── PetWindow.swift
│   ├── main.swift
│   └── Resources/
│       ├── Animations/
│       └── cofit-mascot.png
├── docs/
│   ├── DEVELOPMENT.md
│   └── DEVELOPMENT.zh-CN.md
├── scripts/
│   └── build_app.sh
├── dist/
│   └── CoFit.app                 # generated app bundle
└── Package.swift

docs/archive/, .build/, and dist/ are local/generated content and are ignored by git.

Requirements

• macOS 14 or newer
• Swift 5.9 or newer
• Xcode Command Line Tools (or Xcode)

CoFit is a macOS app. It cannot run directly on iPhone or iPad.

Quick Start

Clone the repository and run it directly with SwiftPM:

git clone https://github.com/stoneQ-Q/CoFit.git
cd CoFit
swift run CoFit

If you use Codex, open the cloned folder in Codex and ask:

Build and run this project with swift run CoFit.

Codex can execute the same local build command for you. The first build may take a little longer; later launches reuse SwiftPM's build cache. Stop the running process with Control-C in the terminal.

Local source builds do not require a pre-signed app download.

Run in Development

swift run CoFit

To build without launching:

swift build

Build the macOS App

scripts/build_app.sh

The app bundle is generated at:

dist/CoFit.app

You can launch it with:

open dist/CoFit.app

The generated app is intended for local use and is not signed or notarized. Public binary distribution requires an Apple Developer ID signature and Apple notarization. Cloning and building the source locally remains available without that distribution setup.

Settings

Open the pet context menu and choose 设置....

Configurable items:

• enable / disable sedentary reminder,
• sedentary threshold in minutes,
• reminder cooldown in minutes,
• reminder title/body text,
• follow-along button text,
• follow-along URL,
• pet appearance.

For testing, sedentary threshold and cooldown support a minimum of 1 minute.

Custom Pet Appearance

Open the pet context menu, choose 设置..., then use the 宠物形象 section.

You can import a group of GIF files, or select a folder containing GIFs. Recommended names:

idle.gif      # idle
wave.gif      # prompt / paw wave
stretch.gif   # coaching / stretch
relax.gif     # resting
tail.gif      # tail wag
sleep.gif     # sleeping

CoFit copies imported GIFs into:

~/Library/Application Support/CoFit/CustomPet/

Missing custom actions automatically fall back to the built-in gray-and-white cat. Use 恢复默认形象 in settings to remove local custom assets and return to the bundled mascot.

Pet Menu

Right-click the pet to open the context menu:

• start a 1 / 3 / 10 minute movement routine,
• pause / resume current routine,
• stop current routine,
• open follow-along video,
• open sedentary status,
• open settings,
• view 宠物动作 debug states,
• reset pet position,
• quit CoFit.

Notes

• dist/CoFit.app is a generated bundle. Rebuild it after changing source code.
• .build/ is a SwiftPM build cache and can be deleted safely.
• The app currently uses a local bundle identifier: local.cofit.pet.
• CoFit runs as an accessory app (LSUIElement) so it does not show a normal Dock icon.

Privacy

CoFit runs locally. Keyboard and mouse activity is reduced to system idle-time values for sedentary timing; keystrokes, mouse positions, and entered content are not recorded or uploaded. Imported pet GIFs remain in the user's local Application Support directory.

Contributing and Security

Contributions are welcome. See CONTRIBUTING.md before opening a pull request. For security issues, follow SECURITY.md.

License

CoFit source code and bundled project assets are released under the MIT License.