CLAWED for macOS & Linux (runs from source)
============================================

Clawed ships as a single Python file on macOS and Linux.
You need Python 3.9+ with Tkinter — that's the only requirement.

MACOS
1. Install Python from https://python.org (includes Tkinter),
   or with Homebrew:  brew install python python-tk
2. Run:  python3 pet.py
3. First run asks your name + optional API key (Google Gemini from
   aistudio.google.com/apikey, OpenRouter from openrouter.ai/keys, or
   Mistral from console.mistral.ai — all free). You can also set it
   later: right-click -> "Set API key...".
4. Full features are one click away: right-click the crab ->
   "Enable window surfing (install Mac helper)..." — that installs the
   small pyobjc-framework-Quartz helper and switches on window surfing,
   cursor stealing and instant idle detection. (Same thing by hand:
   pip3 install pyobjc-framework-Quartz)
5. macOS permissions — allow these when asked, each unlocks features:
   - Automation ("System Events"): lets Clawed see which app is focused.
   - Accessibility: lets it read window TITLES too — this is what makes
     the YouTube intervention and app-aware chatter work on a Mac.
     (System Settings -> Privacy & Security -> Accessibility -> add your
     terminal or Python.)
   - Screen Recording: for the AI screen help (only used with your key).

LINUX
1. Install Tkinter and the optional helpers:
   Debian/Ubuntu:  sudo apt install python3-tk python3-xlib xdotool xprintidle wmctrl gnome-screenshot
   Fedora:         sudo dnf install python3-tkinter python3-xlib xdotool xprintidle wmctrl gnome-screenshot
   (or, in any environment:  pip install python-xlib)
2. Run:  python3 pet.py
   (python-xlib = clean see-through crab with NO background box (highly
    recommended) · xdotool = active-window detection + cursor stealing ·
    wmctrl = window surfing (standing on your windows) · xprintidle =
    sleep/idle features · gnome-screenshot/scrot/grim = AI screen help.
    All optional.)

PLATFORM NOTES
- Opening the menu on a Mac: the crab's menu is a right-click menu. On a
  MacBook trackpad that's a two-finger click (or hold Control and click); with
  a mouse it's the right button. Everything (walk, football, sleep, set API
  key, quit, ...) lives there.
- Window surfing (standing on your windows) and cursor stealing work on all
  three platforms: Windows out of the box; macOS via the one-click helper in
  the right-click menu; Linux with wmctrl (surfing) + xdotool (stealing).
  Without those optional bits the crab just keeps to the bottom of the screen.
- Sounds: Windows uses real tones; macOS uses soft built-in system sounds;
  Linux is silent (no zero-dependency tone generator). Toggle in right-click
  -> Sounds.
- On Linux, install python-xlib (see above) and the crab is clipped to its
  own pixels with the X SHAPE extension — a real see-through cut-out with no
  box, and it works even without a compositor. Without python-xlib it falls
  back to a small dark tile behind the crab.
- Closing the terminal can NOT close the pet. On macOS, Clawed now moves
  itself into its own background session on EVERY launch — plain
  `python3 pet.py`, `nohup`, `&`, or an IDE run all survive closing or even
  quitting Terminal.app. The terminal returns to a prompt right away while
  the crab keeps running. To stop it: right-click -> "Quit (close
  completely)". (To run in the foreground for debugging, launch with
  CLAWED_DETACHED=1 python3 pet.py — output stays in the terminal.)
- Say yes to "start automatically" in setup and it installs (and registers) a
  LaunchAgent on macOS or an autostart entry on Linux, so Clawed returns at
  your next login.

Settings live next to pet.py in config.json (name, gemini_key,
openrouter_key, openrouter_model, mistral_key, mistral_model, watch_repos). Your key is yours alone —
it never leaves your machine except to call your chosen AI provider.

Support: subhajitmahata844@gmail.com
