claudlet 0.1.0__tar.gz

claudlet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 claudlet authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claudlet-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+claudlet
+
+Code: MIT License — see LICENSE.
+
+Original creature artwork (rendered entirely in code by src/creature.py):
+CC0 1.0 Universal — public domain dedication.
+https://creativecommons.org/publicdomain/zero/1.0/

claudlet-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: claudlet
+Version: 0.1.0
+Summary: A pixel desktop buddy that reacts to Claude Code in real time
+Author: YeeDochi
+License: CC0-1.0
+Project-URL: Homepage, https://github.com/YeeDochi/Claudlet
+Keywords: claude-code,desktop-pet,pyqt6,hooks
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: PyQt6
+Requires-Dist: pyobjc-framework-Quartz; sys_platform == "darwin"
+Dynamic: license-file
+
+# claudlet 🐾
+
+**English** | [한국어](README.ko.md)
+
+A tiny pixel creature that lives on your desktop and reacts to **Claude Code** in
+real time — it types while Claude works, waits when Claude needs you, celebrates
+when it's done, and roams around while you code. Click it to bring the terminal
+back to the front.
+
+Drawn entirely in code — no image assets — so it's self-contained and original
+(CC0 artwork).
+
+![states](docs/creature_sheet.en.png)
+
+## See it in action
+
+Real desktop capture. Pets perch on the terminal titlebar, roam the desktop, doze
+off (💤) between tasks, and clamber over whatever else is on screen.
+
+![claudlet on the desktop](docs/screenshot.png)
+
+![Pets perch on the terminal and roam the desktop](docs/demo-1.gif)
+*Perching on the terminal, roaming, and dozing between tasks.*
+
+![Dragging a pet while the others nap](docs/demo-2.gif)
+*Grab and drag them around; the rest keep roaming and napping.*
+
+![Pets roaming over the wallpaper](docs/demo-3.gif)
+*They wander over whatever else is on your screen.*
+
+## Install
+
+Install with [pipx](https://pipx.pypa.io) (an isolated app install — pulls the
+deps, incl. `pyobjc-framework-Quartz` on macOS, and puts the `claudlet*`
+commands on your PATH), then wire it into Claude Code:
+
+```bash
+pipx install claudlet
+claudlet-install      # registers the hooks + /claudlet skill (idempotent)
+```
+
+Update later with `pipx upgrade claudlet && claudlet-install`, or from inside
+Claude Code with `/claudlet update`. To install an unreleased revision, point
+pipx at the repo instead: `pipx install "git+https://github.com/YeeDochi/Claudlet@master"`.
+
+<details><summary>Without pipx — one-line source install</summary>
+
+Clones (or updates) to `~/claudlet`, installs deps, registers hooks + skill:
+```bash
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/YeeDochi/Claudlet/master/install.py | python3 -
+```
+```powershell
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/YeeDochi/Claudlet/master/install.py | python -
+```
+</details>
+
+New Claude Code sessions then auto-spawn a pet. Restart any already-running session
+to pick up the hooks — or launch one now with `claudlet`.
+
+Best on **KDE Plasma**. Perching on and riding windows also works on **Windows**
+(Win32) and **macOS** (experimental — needs `pyobjc-framework-Quartz`, which the
+installer adds automatically; the pet self-calibrates window coordinates at
+runtime). Elsewhere the window tricks switch off gracefully and the pet just
+roams. See **[Platform support](docs/platform.md)**.
+
+## What it shows
+
+The creature's pose tracks what Claude is doing — editing, reading, calling MCP,
+spawning subagents, thinking, waiting on your input, celebrating (see the sheet
+above). In **auto / bypass mode** it puts on a VR visor and cruises, with a per-tool
+variant for each activity. It also **perches on and rides your windows** — walking
+along the top or living inside — and clips/hides when the window it's on is covered
+or minimized.
+
+## Docs
+
+- **[Usage & interaction](docs/usage.md)** — drag & throw, click-to-focus, tray menu, motions, autostart, uninstall
+- **[Configuration](docs/configuration.md)** — remap which animation shows for which Claude Code activity
+- **[Platform support](docs/platform.md)** — support matrix + how to test on your OS
+
+## License
+
+Code: **MIT** (see [LICENSE](LICENSE)). Creature artwork: **CC0** (see [NOTICE](NOTICE)).

claudlet-0.1.0/README.md

@@ -0,0 +1,85 @@
+# claudlet 🐾
+
+**English** | [한국어](README.ko.md)
+
+A tiny pixel creature that lives on your desktop and reacts to **Claude Code** in
+real time — it types while Claude works, waits when Claude needs you, celebrates
+when it's done, and roams around while you code. Click it to bring the terminal
+back to the front.
+
+Drawn entirely in code — no image assets — so it's self-contained and original
+(CC0 artwork).
+
+![states](docs/creature_sheet.en.png)
+
+## See it in action
+
+Real desktop capture. Pets perch on the terminal titlebar, roam the desktop, doze
+off (💤) between tasks, and clamber over whatever else is on screen.
+
+![claudlet on the desktop](docs/screenshot.png)
+
+![Pets perch on the terminal and roam the desktop](docs/demo-1.gif)
+*Perching on the terminal, roaming, and dozing between tasks.*
+
+![Dragging a pet while the others nap](docs/demo-2.gif)
+*Grab and drag them around; the rest keep roaming and napping.*
+
+![Pets roaming over the wallpaper](docs/demo-3.gif)
+*They wander over whatever else is on your screen.*
+
+## Install
+
+Install with [pipx](https://pipx.pypa.io) (an isolated app install — pulls the
+deps, incl. `pyobjc-framework-Quartz` on macOS, and puts the `claudlet*`
+commands on your PATH), then wire it into Claude Code:
+
+```bash
+pipx install claudlet
+claudlet-install      # registers the hooks + /claudlet skill (idempotent)
+```
+
+Update later with `pipx upgrade claudlet && claudlet-install`, or from inside
+Claude Code with `/claudlet update`. To install an unreleased revision, point
+pipx at the repo instead: `pipx install "git+https://github.com/YeeDochi/Claudlet@master"`.
+
+<details><summary>Without pipx — one-line source install</summary>
+
+Clones (or updates) to `~/claudlet`, installs deps, registers hooks + skill:
+```bash
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/YeeDochi/Claudlet/master/install.py | python3 -
+```
+```powershell
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/YeeDochi/Claudlet/master/install.py | python -
+```
+</details>
+
+New Claude Code sessions then auto-spawn a pet. Restart any already-running session
+to pick up the hooks — or launch one now with `claudlet`.
+
+Best on **KDE Plasma**. Perching on and riding windows also works on **Windows**
+(Win32) and **macOS** (experimental — needs `pyobjc-framework-Quartz`, which the
+installer adds automatically; the pet self-calibrates window coordinates at
+runtime). Elsewhere the window tricks switch off gracefully and the pet just
+roams. See **[Platform support](docs/platform.md)**.
+
+## What it shows
+
+The creature's pose tracks what Claude is doing — editing, reading, calling MCP,
+spawning subagents, thinking, waiting on your input, celebrating (see the sheet
+above). In **auto / bypass mode** it puts on a VR visor and cruises, with a per-tool
+variant for each activity. It also **perches on and rides your windows** — walking
+along the top or living inside — and clips/hides when the window it's on is covered
+or minimized.
+
+## Docs
+
+- **[Usage & interaction](docs/usage.md)** — drag & throw, click-to-focus, tray menu, motions, autostart, uninstall
+- **[Configuration](docs/configuration.md)** — remap which animation shows for which Claude Code activity
+- **[Platform support](docs/platform.md)** — support matrix + how to test on your OS
+
+## License
+
+Code: **MIT** (see [LICENSE](LICENSE)). Creature artwork: **CC0** (see [NOTICE](NOTICE)).

claudlet-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claudlet"
+dynamic = ["version"]
+description = "A pixel desktop buddy that reacts to Claude Code in real time"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "CC0-1.0" }
+authors = [{ name = "YeeDochi" }]
+keywords = ["claude-code", "desktop-pet", "pyqt6", "hooks"]
+dependencies = [
+    "PyQt6",
+    "pyobjc-framework-Quartz; sys_platform == 'darwin'",
+]
+
+[project.urls]
+Homepage = "https://github.com/YeeDochi/Claudlet"
+
+[project.scripts]
+claudlet = "claudlet.pet:main"
+claudlet-attach = "claudlet.attach:_cli"
+claudlet-hook = "claudlet.hook:_cli"
+claudlet-motion = "claudlet.motion:_cli"
+claudlet-install = "claudlet.install:main"
+claudlet-uninstall = "claudlet.uninstall:_cli"
+claudlet-install-hooks = "claudlet.install_hooks:main"
+claudlet-config = "claudlet.configcli:_cli"
+claudlet-macos-diag = "claudlet.macos_diag:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "claudlet.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+claudlet = ["skill/*"]

claudlet-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claudlet-0.1.0/src/claudlet/__init__.py

@@ -0,0 +1,2 @@
+"""claudlet — a pixel desktop buddy that reacts to Claude Code."""
+__version__ = "0.1.0"

claudlet-0.1.0/src/claudlet/__main__.py

@@ -0,0 +1,4 @@
+from claudlet.pet import main
+
+if __name__ == "__main__":
+    main()

claudlet-0.1.0/src/claudlet/attach.py

@@ -0,0 +1,86 @@
+"""claudlet-attach — bring up a pet for a Claude Code session (or standalone).
+
+A console entry point so the /claudlet skill can just run `claudlet-attach`
+instead of shelling into `python3 -c "import hostinfo; ..."` — which breaks under
+a pipx install, where the package lives in an isolated venv the system python
+can't import. Detects the session id and host, skips if a pet is already
+attached (via the same liveness handshake the hook uses), and launches a
+detached pet bound to the session.
+
+    claudlet-attach                 attach to this session (env/newest transcript)
+    claudlet-attach --session <id>  attach to a specific session
+    claudlet-attach --standalone    an unattached, decorative roaming pet
+"""
+import glob
+import os
+import subprocess
+import sys
+
+from claudlet import hostinfo
+
+
+def _newest_session_id():
+    """Fallback when $CLAUDE_CODE_SESSION_ID is unset: the session id of the
+    most recently modified transcript under ~/.claude/projects/."""
+    files = glob.glob(os.path.expanduser("~/.claude/projects/*/*.jsonl"))
+    if not files:
+        return None
+    newest = max(files, key=os.path.getmtime)
+    return os.path.splitext(os.path.basename(newest))[0]
+
+
+def _launch(extra_args):
+    """Launch a detached `python -m claudlet` that outlives this call."""
+    kw = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL,
+          "stderr": subprocess.DEVNULL}
+    if os.name == "posix":
+        kw["start_new_session"] = True            # own process group; survives us
+    # ensure the child interpreter can import claudlet from a source checkout
+    # (pipx/pip installs already have it importable; the extra PYTHONPATH is harmless)
+    env = dict(os.environ)
+    src_dir = os.path.dirname(os.path.dirname(os.path.abspath(hostinfo.__file__)))
+    env["PYTHONPATH"] = src_dir + os.pathsep + env.get("PYTHONPATH", "")
+    subprocess.Popen([sys.executable, "-m", "claudlet"] + extra_args, env=env, **kw)
+
+
+def _arg_value(argv, flag):
+    if flag in argv:
+        i = argv.index(flag)
+        if i + 1 < len(argv):
+            return argv[i + 1]
+    return None
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if "--standalone" in argv:
+        _launch([])
+        print("standalone pet running")
+        return 0
+
+    session_id = (_arg_value(argv, "--session")
+                  or os.environ.get("CLAUDE_CODE_SESSION_ID")
+                  or _newest_session_id()
+                  or "default")
+    host = hostinfo.detect_host()
+
+    if hostinfo.pet_alive(session_id):
+        print("already attached to session %s (host=%s)" % (session_id, host))
+        return 0
+
+    _launch(["--session", session_id, "--host", host])
+    print("attached to session %s (host=%s)" % (session_id, host))
+    return 0
+
+
+def _cli():
+    """console-script entry point; never hard-fails the caller."""
+    try:
+        sys.exit(main())
+    except Exception:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    _cli()

claudlet-0.1.0/src/claudlet/configcli.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""claudlet-config — locate, inspect, scaffold, and open the user config.
+
+Usage:
+    claudlet-config            # show path, status, effective values, ignored entries
+    claudlet-config --path     # print the absolute config path only
+    claudlet-config init       # create a starter template if none exists
+    claudlet-config open       # open the config in the OS default editor
+
+Thin presentation/scaffold layer over petconfig — all path/schema/validation
+logic lives there. The /claudlet skill documents the schema so Claude can edit
+the JSON directly and re-run this command to validate.
+"""
+import json
+import os
+import sys
+
+from claudlet import petconfig
+from claudlet.state_engine import MAPPABLE_STATES, DEFAULT_EVENT_STATES
+
+
+def diagnose(raw):
+    """Split a parsed config dict into what load_config accepts vs silently
+    drops. Pure. Returns {"accepted": <petconfig._clean result>, "ignored":
+    [human-readable strings]} so a typo'd state or unknown slot is visible
+    instead of degrading to defaults with no feedback."""
+    accepted = petconfig._clean(raw)
+    ignored = []
+
+    for key, val in (raw.get("tools") or {}).items():
+        if not (isinstance(key, str) and val in MAPPABLE_STATES):
+            ignored.append("tools.%s=%r (not a valid state)" % (key, val))
+    for key, val in (raw.get("events") or {}).items():
+        if key not in DEFAULT_EVENT_STATES:
+            ignored.append("events.%s=%r (unknown event slot)" % (key, val))
+        elif val not in MAPPABLE_STATES:
+            ignored.append("events.%s=%r (not a valid state)" % (key, val))
+    for key, val in (raw.get("raw_events") or {}).items():
+        if not (isinstance(key, str) and val in MAPPABLE_STATES):
+            ignored.append("raw_events.%s=%r (not a valid state)" % (key, val))
+    if "lang" in raw and raw.get("lang") not in ("ko", "en", "auto"):
+        ignored.append("lang=%r (use ko | en | auto)" % (raw.get("lang"),))
+
+    return {"accepted": accepted, "ignored": ignored}
+
+
+_DEFAULTS = {"tool_states": {}, "event_states": {}, "raw_events": {},
+             "lang": "auto"}
+
+
+def build_report(path=None):
+    """Inspect the config file at `path` (default: the resolved config_path).
+    Returns {"path", "status": found|missing|invalid, "error"?, "accepted",
+    "ignored"}. Never raises."""
+    path = os.path.abspath(path or petconfig.config_path())
+    if not os.path.exists(path):
+        return {"path": path, "status": "missing",
+                "accepted": dict(_DEFAULTS), "ignored": []}
+    try:
+        with open(path, encoding="utf-8") as f:
+            raw = json.load(f)
+    except (OSError, ValueError) as e:
+        return {"path": path, "status": "invalid", "error": str(e),
+                "accepted": dict(_DEFAULTS), "ignored": []}
+    if not isinstance(raw, dict):
+        return {"path": path, "status": "invalid",
+                "error": "top-level JSON must be an object",
+                "accepted": dict(_DEFAULTS), "ignored": []}
+    d = diagnose(raw)
+    return {"path": path, "status": "found",
+            "accepted": d["accepted"], "ignored": d["ignored"]}
+
+
+# A valid, minimal starting point (per-key guidance lives in `show`, the skill
+# doc, and docs/configuration.md — JSON has no comments).
+TEMPLATE = {
+    "lang": "auto",
+    "tools": {"Bash": "work_computer"},
+    "events": {},
+    "raw_events": {},
+}
+
+
+def init_config(path=None):
+    """Create a starter template at `path` if it doesn't exist. Returns True if
+    a file was created, False if one was already there (never clobbers)."""
+    path = os.path.abspath(path or petconfig.config_path())
+    if os.path.exists(path):
+        return False
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(TEMPLATE, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    return True
+
+
+def _open_command(path, platform=None, name=None):
+    """How to open `path`: an argv list for a subprocess, or the string
+    "startfile" meaning use os.startfile (Windows). Pure."""
+    platform = sys.platform if platform is None else platform
+    name = os.name if name is None else name
+    if name == "nt":
+        return "startfile"
+    if platform == "darwin":
+        return ["open", path]
+    return ["xdg-open", path]
+
+
+def _launch(path):
+    cmd = _open_command(path)
+    if cmd == "startfile":
+        os.startfile(path)                      # noqa: Windows only
+    else:
+        import subprocess
+        subprocess.Popen(cmd)
+
+
+def open_config(path=None):
+    """Scaffold the config if missing, then open it in the OS default editor.
+    Best-effort (never raises); returns the absolute path so the caller can
+    print it as a fallback."""
+    path = os.path.abspath(path or petconfig.config_path())
+    init_config(path)
+    try:
+        _launch(path)
+    except Exception:
+        pass
+    return path
+
+
+def render(r):
+    """Human-readable text for a build_report() result."""
+    acc = r["accepted"]
+    status = r["status"]
+    if status == "invalid":
+        status += " (%s)" % r.get("error", "")
+    elif status == "missing":
+        status += " (built-in defaults apply)"
+    lines = [
+        "config: " + r["path"],
+        "status: " + status,
+        "lang:   " + acc["lang"],
+        "tools:      " + json.dumps(acc["tool_states"], ensure_ascii=False),
+        "events:     " + json.dumps(acc["event_states"], ensure_ascii=False),
+        "raw_events: " + json.dumps(acc["raw_events"], ensure_ascii=False),
+    ]
+    if r["ignored"]:
+        lines.append("ignored (present in the file but dropped — fix these):")
+        lines += ["  - " + s for s in r["ignored"]]
+    lines += [
+        "---",
+        "valid states: " + ", ".join(sorted(MAPPABLE_STATES)),
+        "event slots:  " + ", ".join(DEFAULT_EVENT_STATES),
+        "edit the file (or ask Claude via /claudlet config), then restart the pet.",
+    ]
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    arg = argv[0] if argv else ""
+
+    if arg == "--path":
+        print(os.path.abspath(petconfig.config_path()))
+        return 0
+    if arg == "init":
+        path = os.path.abspath(petconfig.config_path())
+        created = init_config(path)
+        print(("created " if created else "already exists: ") + path)
+        return 0
+    if arg == "open":
+        print("opening " + open_config())
+        return 0
+    print(render(build_report()))
+    return 0
+
+
+def _cli():
+    """console-script entry point (never raise from the CLI)."""
+    try:
+        sys.exit(main(sys.argv[1:]))
+    except Exception:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    _cli()