opencat 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. opencat-0.1.0/LICENSE +21 -0
  2. opencat-0.1.0/PKG-INFO +175 -0
  3. opencat-0.1.0/README.md +158 -0
  4. opencat-0.1.0/opencat/__init__.py +3 -0
  5. opencat-0.1.0/opencat/__main__.py +5 -0
  6. opencat-0.1.0/opencat/app.py +2417 -0
  7. opencat-0.1.0/opencat/cli.py +41 -0
  8. opencat-0.1.0/opencat/config.py +66 -0
  9. opencat-0.1.0/opencat/generate_placeholder_gifs.py +181 -0
  10. opencat-0.1.0/opencat/generate_placeholders.py +269 -0
  11. opencat-0.1.0/opencat/history.py +208 -0
  12. opencat-0.1.0/opencat/platform_utils.py +95 -0
  13. opencat-0.1.0/opencat/protocol.py +48 -0
  14. opencat-0.1.0/opencat/state.py +10 -0
  15. opencat-0.1.0/opencat/ui/__init__.py +1 -0
  16. opencat-0.1.0/opencat/ui/app.js +127 -0
  17. opencat-0.1.0/opencat/ui/assets/README.md +13 -0
  18. opencat-0.1.0/opencat/ui/assets/connecting.gif +0 -0
  19. opencat-0.1.0/opencat/ui/assets/done.gif +0 -0
  20. opencat-0.1.0/opencat/ui/assets/error.gif +0 -0
  21. opencat-0.1.0/opencat/ui/assets/idle.gif +0 -0
  22. opencat-0.1.0/opencat/ui/assets/manifest.json +12 -0
  23. opencat-0.1.0/opencat/ui/assets/sleeping.gif +0 -0
  24. opencat-0.1.0/opencat/ui/assets/talking.gif +0 -0
  25. opencat-0.1.0/opencat/ui/assets/thinking.gif +0 -0
  26. opencat-0.1.0/opencat/ui/floating.css +57 -0
  27. opencat-0.1.0/opencat/ui/floating.html +18 -0
  28. opencat-0.1.0/opencat/ui/floating.js +75 -0
  29. opencat-0.1.0/opencat/ui/index.html +33 -0
  30. opencat-0.1.0/opencat/ui/style.css +157 -0
  31. opencat-0.1.0/opencat/ws_client.py +125 -0
  32. opencat-0.1.0/opencat.egg-info/PKG-INFO +175 -0
  33. opencat-0.1.0/opencat.egg-info/SOURCES.txt +37 -0
  34. opencat-0.1.0/opencat.egg-info/dependency_links.txt +1 -0
  35. opencat-0.1.0/opencat.egg-info/entry_points.txt +2 -0
  36. opencat-0.1.0/opencat.egg-info/requires.txt +3 -0
  37. opencat-0.1.0/opencat.egg-info/top_level.txt +1 -0
  38. opencat-0.1.0/pyproject.toml +31 -0
  39. opencat-0.1.0/setup.cfg +4 -0
opencat-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Jacobzwj
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
opencat-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,175 @@
1
+ Metadata-Version: 2.4
2
+ Name: opencat
3
+ Version: 0.1.0
4
+ Summary: OpenCat — a cute floating desktop cat companion for OpenClaw AI
5
+ License: MIT
6
+ Keywords: opencat,openclaw,desktop-pet,ai-chat
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Operating System :: OS Independent
9
+ Classifier: Topic :: Desktop Environment
10
+ Requires-Python: >=3.10
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Requires-Dist: customtkinter>=5.2
14
+ Requires-Dist: Pillow>=10.0
15
+ Requires-Dist: websocket-client>=1.6
16
+ Dynamic: license-file
17
+
18
+ <p align="right">
19
+ <a href="README.zh-CN.md">中文</a> | English
20
+ </p>
21
+
22
+ <p align="center">
23
+ <img src="docs/idle.gif" width="120" />
24
+ </p>
25
+
26
+ <h1 align="center">OpenCat — Desktop Client for OpenClaw</h1>
27
+
28
+ <p align="center">
29
+ <b>A cute desktop skin for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> — same commands, same AI, just cuter.</b><br>
30
+ <code>pip install</code>, run <code>opencat</code>, done. Everything you do in OpenClaw works here.
31
+ </p>
32
+
33
+ <p align="center">
34
+ <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python&logoColor=white" />
35
+ <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" />
36
+ <img src="https://img.shields.io/badge/license-MIT-green" />
37
+ </p>
38
+
39
+ <table align="center">
40
+ <tr>
41
+ <td align="center" colspan="4"><b>Idle</b> (random rotation)</td>
42
+ <td align="center"><b>Thinking</b></td>
43
+ <td align="center"><b>Done</b></td>
44
+ <td align="center"><b>Sleeping</b></td>
45
+ </tr>
46
+ <tr>
47
+ <td align="center"><img src="docs/idle.gif" width="90" /><br><sub>yarn ball</sub></td>
48
+ <td align="center"><img src="docs/error.gif" width="90" /><br><sub>scratching</sub></td>
49
+ <td align="center"><img src="docs/connecting.gif" width="90" /><br><sub>rolling</sub></td>
50
+ <td align="center"><img src="docs/talking.gif" width="90" /><br><sub>running</sub></td>
51
+ <td align="center"><img src="docs/thinking.gif" width="90" /><br><sub>eating</sub></td>
52
+ <td align="center"><img src="docs/done.gif" width="90" /><br><sub>pooping</sub></td>
53
+ <td align="center"><img src="docs/sleeping.gif" width="90" /><br><sub>sleeping</sub></td>
54
+ </tr>
55
+ </table>
56
+
57
+ ---
58
+
59
+ ## Why OpenCat?
60
+
61
+ If you're running [OpenClaw](https://github.com/openclaw/openclaw) as your AI gateway, you might find:
62
+
63
+ - **The official web panel is too cluttered** — you just want a quick, clean chat window
64
+ - **Telegram / WhatsApp bots need a VPN** if you're in mainland China
65
+ - **You want something that feels alive** — not another chat tab buried in your browser
66
+
67
+ OpenCat puts a pixel-art cat on your desktop. Click it, and a warm-toned chat window pops up. That's it. No browser, no VPN, no noise.
68
+
69
+ ## Screenshots
70
+
71
+ <table>
72
+ <tr>
73
+ <td align="center"><b>Chat + Cat</b></td>
74
+ <td align="center"><b>History Sidebar</b></td>
75
+ </tr>
76
+ <tr>
77
+ <td><img src="docs/chat.png" width="400" /></td>
78
+ <td><img src="docs/chat-history.png" width="480" /></td>
79
+ </tr>
80
+ <tr>
81
+ <td><sub>Click the cat to open the chat window. Warm pastel UI with streaming AI replies.</sub></td>
82
+ <td><sub>Conversation history with color-coded bookmarks. Switch or delete sessions anytime.</sub></td>
83
+ </tr>
84
+ </table>
85
+
86
+ **Toolbar:** `A-`/`A+` adjust font size &nbsp;|&nbsp; cube toggles 3D cat &nbsp;|&nbsp; `+` new chat &nbsp;|&nbsp; book icon opens history
87
+
88
+ ## Features
89
+
90
+ - **Floating cat widget** — always on top, draggable, with animated states (idle, thinking, talking, sleeping...)
91
+ - **Warm pastel chat UI** — clean, minimal, purpose-built for quick conversations
92
+ - **Streaming responses** — see the AI reply in real-time, token by token
93
+ - **Conversation history** — sessions are saved locally and browsable from the sidebar
94
+ - **Image attachments** — paste or drag images into the chat (clipboard + file picker)
95
+ - **Cross-platform** — Windows, macOS, Linux (native transparency on Windows, graceful fallback elsewhere)
96
+ - **Remote connection** — connect to an OpenClaw gateway on another machine via Tailscale or any network
97
+ - **Lightweight** — pure Python, ~100 KB installed, no web runtime
98
+
99
+ ## Chat Commands
100
+
101
+ OpenCat supports [OpenClaw](https://github.com/openclaw/openclaw) native commands — type them directly in the chat input:
102
+
103
+ | Command | Description |
104
+ |---------|-------------|
105
+ | `/status` | View current session status and token usage |
106
+ | `/new` | Start a new conversation (resets server session) |
107
+ | `/compact` | Compress context to save tokens |
108
+ | `/think <level>` | Set thinking depth |
109
+ | `/stop` | Abort the current response |
110
+ | `/clear` | Clear local chat display (does not reset server session) |
111
+ | `/help` | Show all available commands |
112
+
113
+ ## Quick Start
114
+
115
+ ### Prerequisites
116
+
117
+ You need a running [OpenClaw](https://github.com/openclaw/openclaw) gateway. OpenCat connects to it via WebSocket.
118
+
119
+ ### Install
120
+
121
+ ```bash
122
+ pip install git+https://github.com/Jacobzwj/opencat.git
123
+ ```
124
+
125
+ ### Run
126
+
127
+ ```bash
128
+ opencat
129
+ ```
130
+
131
+ OpenCat reads your gateway config from `~/.openclaw/openclaw.json` automatically.
132
+
133
+ ### CLI Options
134
+
135
+ ```bash
136
+ opencat --host 100.64.0.3 # Connect to a remote OpenClaw (e.g. via Tailscale)
137
+ opencat --port 18789 # Override gateway port
138
+ opencat --token your-token # Override gateway token
139
+ opencat --debug # Enable debug logging
140
+ ```
141
+
142
+ ## Development
143
+
144
+ ```bash
145
+ git clone https://github.com/Jacobzwj/opencat.git
146
+ cd opencat
147
+ pip install -e .
148
+ opencat
149
+ ```
150
+
151
+ ## How It Works
152
+
153
+ ```
154
+ ┌──────────┐ WebSocket ┌──────────────┐
155
+ │ OpenCat │ ◄───────────► │ OpenClaw │ ───► LLM API
156
+ │ (desktop) │ streaming │ (gateway) │
157
+ └──────────┘ └──────────────┘
158
+ ```
159
+
160
+ OpenCat is a pure client — it connects to your self-hosted OpenClaw gateway over WebSocket, sends messages, and streams back responses. All AI logic, model selection, and API keys stay on the gateway side.
161
+
162
+ ## Customizing the Cat
163
+
164
+ Cat animations live in `opencat/ui/assets/` and are mapped via `manifest.json`. Replace them with your own pixel art:
165
+
166
+ | State | What happens | Default GIF |
167
+ |-------|-------------|-------------|
168
+ | **Idle** | Connected, waiting for user. Randomly rotates through a pool. | `idle.gif`, `error.gif`, `connecting.gif`, `talking.gif` |
169
+ | **Thinking** | User sent a message, waiting for AI + streaming reply | `thinking.gif` (eating) |
170
+ | **Done** | Response complete, stays until next message | `done.gif` (pooping) |
171
+ | **Sleeping** | Not connected to OpenClaw | `sleeping.gif` (sleeping in box) |
172
+
173
+ ## License
174
+
175
+ MIT
opencat-0.1.0/README.md ADDED
@@ -0,0 +1,158 @@
1
+ <p align="right">
2
+ <a href="README.zh-CN.md">中文</a> | English
3
+ </p>
4
+
5
+ <p align="center">
6
+ <img src="docs/idle.gif" width="120" />
7
+ </p>
8
+
9
+ <h1 align="center">OpenCat — Desktop Client for OpenClaw</h1>
10
+
11
+ <p align="center">
12
+ <b>A cute desktop skin for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> — same commands, same AI, just cuter.</b><br>
13
+ <code>pip install</code>, run <code>opencat</code>, done. Everything you do in OpenClaw works here.
14
+ </p>
15
+
16
+ <p align="center">
17
+ <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python&logoColor=white" />
18
+ <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" />
19
+ <img src="https://img.shields.io/badge/license-MIT-green" />
20
+ </p>
21
+
22
+ <table align="center">
23
+ <tr>
24
+ <td align="center" colspan="4"><b>Idle</b> (random rotation)</td>
25
+ <td align="center"><b>Thinking</b></td>
26
+ <td align="center"><b>Done</b></td>
27
+ <td align="center"><b>Sleeping</b></td>
28
+ </tr>
29
+ <tr>
30
+ <td align="center"><img src="docs/idle.gif" width="90" /><br><sub>yarn ball</sub></td>
31
+ <td align="center"><img src="docs/error.gif" width="90" /><br><sub>scratching</sub></td>
32
+ <td align="center"><img src="docs/connecting.gif" width="90" /><br><sub>rolling</sub></td>
33
+ <td align="center"><img src="docs/talking.gif" width="90" /><br><sub>running</sub></td>
34
+ <td align="center"><img src="docs/thinking.gif" width="90" /><br><sub>eating</sub></td>
35
+ <td align="center"><img src="docs/done.gif" width="90" /><br><sub>pooping</sub></td>
36
+ <td align="center"><img src="docs/sleeping.gif" width="90" /><br><sub>sleeping</sub></td>
37
+ </tr>
38
+ </table>
39
+
40
+ ---
41
+
42
+ ## Why OpenCat?
43
+
44
+ If you're running [OpenClaw](https://github.com/openclaw/openclaw) as your AI gateway, you might find:
45
+
46
+ - **The official web panel is too cluttered** — you just want a quick, clean chat window
47
+ - **Telegram / WhatsApp bots need a VPN** if you're in mainland China
48
+ - **You want something that feels alive** — not another chat tab buried in your browser
49
+
50
+ OpenCat puts a pixel-art cat on your desktop. Click it, and a warm-toned chat window pops up. That's it. No browser, no VPN, no noise.
51
+
52
+ ## Screenshots
53
+
54
+ <table>
55
+ <tr>
56
+ <td align="center"><b>Chat + Cat</b></td>
57
+ <td align="center"><b>History Sidebar</b></td>
58
+ </tr>
59
+ <tr>
60
+ <td><img src="docs/chat.png" width="400" /></td>
61
+ <td><img src="docs/chat-history.png" width="480" /></td>
62
+ </tr>
63
+ <tr>
64
+ <td><sub>Click the cat to open the chat window. Warm pastel UI with streaming AI replies.</sub></td>
65
+ <td><sub>Conversation history with color-coded bookmarks. Switch or delete sessions anytime.</sub></td>
66
+ </tr>
67
+ </table>
68
+
69
+ **Toolbar:** `A-`/`A+` adjust font size &nbsp;|&nbsp; cube toggles 3D cat &nbsp;|&nbsp; `+` new chat &nbsp;|&nbsp; book icon opens history
70
+
71
+ ## Features
72
+
73
+ - **Floating cat widget** — always on top, draggable, with animated states (idle, thinking, talking, sleeping...)
74
+ - **Warm pastel chat UI** — clean, minimal, purpose-built for quick conversations
75
+ - **Streaming responses** — see the AI reply in real-time, token by token
76
+ - **Conversation history** — sessions are saved locally and browsable from the sidebar
77
+ - **Image attachments** — paste or drag images into the chat (clipboard + file picker)
78
+ - **Cross-platform** — Windows, macOS, Linux (native transparency on Windows, graceful fallback elsewhere)
79
+ - **Remote connection** — connect to an OpenClaw gateway on another machine via Tailscale or any network
80
+ - **Lightweight** — pure Python, ~100 KB installed, no web runtime
81
+
82
+ ## Chat Commands
83
+
84
+ OpenCat supports [OpenClaw](https://github.com/openclaw/openclaw) native commands — type them directly in the chat input:
85
+
86
+ | Command | Description |
87
+ |---------|-------------|
88
+ | `/status` | View current session status and token usage |
89
+ | `/new` | Start a new conversation (resets server session) |
90
+ | `/compact` | Compress context to save tokens |
91
+ | `/think <level>` | Set thinking depth |
92
+ | `/stop` | Abort the current response |
93
+ | `/clear` | Clear local chat display (does not reset server session) |
94
+ | `/help` | Show all available commands |
95
+
96
+ ## Quick Start
97
+
98
+ ### Prerequisites
99
+
100
+ You need a running [OpenClaw](https://github.com/openclaw/openclaw) gateway. OpenCat connects to it via WebSocket.
101
+
102
+ ### Install
103
+
104
+ ```bash
105
+ pip install git+https://github.com/Jacobzwj/opencat.git
106
+ ```
107
+
108
+ ### Run
109
+
110
+ ```bash
111
+ opencat
112
+ ```
113
+
114
+ OpenCat reads your gateway config from `~/.openclaw/openclaw.json` automatically.
115
+
116
+ ### CLI Options
117
+
118
+ ```bash
119
+ opencat --host 100.64.0.3 # Connect to a remote OpenClaw (e.g. via Tailscale)
120
+ opencat --port 18789 # Override gateway port
121
+ opencat --token your-token # Override gateway token
122
+ opencat --debug # Enable debug logging
123
+ ```
124
+
125
+ ## Development
126
+
127
+ ```bash
128
+ git clone https://github.com/Jacobzwj/opencat.git
129
+ cd opencat
130
+ pip install -e .
131
+ opencat
132
+ ```
133
+
134
+ ## How It Works
135
+
136
+ ```
137
+ ┌──────────┐ WebSocket ┌──────────────┐
138
+ │ OpenCat │ ◄───────────► │ OpenClaw │ ───► LLM API
139
+ │ (desktop) │ streaming │ (gateway) │
140
+ └──────────┘ └──────────────┘
141
+ ```
142
+
143
+ OpenCat is a pure client — it connects to your self-hosted OpenClaw gateway over WebSocket, sends messages, and streams back responses. All AI logic, model selection, and API keys stay on the gateway side.
144
+
145
+ ## Customizing the Cat
146
+
147
+ Cat animations live in `opencat/ui/assets/` and are mapped via `manifest.json`. Replace them with your own pixel art:
148
+
149
+ | State | What happens | Default GIF |
150
+ |-------|-------------|-------------|
151
+ | **Idle** | Connected, waiting for user. Randomly rotates through a pool. | `idle.gif`, `error.gif`, `connecting.gif`, `talking.gif` |
152
+ | **Thinking** | User sent a message, waiting for AI + streaming reply | `thinking.gif` (eating) |
153
+ | **Done** | Response complete, stays until next message | `done.gif` (pooping) |
154
+ | **Sleeping** | Not connected to OpenClaw | `sleeping.gif` (sleeping in box) |
155
+
156
+ ## License
157
+
158
+ MIT
opencat-0.1.0/opencat/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """OpenCat 鈥?A cute desktop cat companion for OpenClaw."""
2
+
3
+ __version__ = "0.1.0"
opencat-0.1.0/opencat/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ from opencat.cli import main
2
+
3
+
4
+ if __name__ == "__main__":
5
+ main()