Skip to content

Commit c6442ac

Browse files
johnmcijohnmci
authored
Merge pull request #11 from CorporateSmalltalkConsultingLtd/clawdbot-skill
Add Clawdbot skill support
2 parents 034995b + 2680a3d commit c6442ac

File tree

4 files changed

+861
-0
lines changed

4 files changed

+861
-0
lines changed

‎CLAWDBOT-SETUP.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Clawdbot Smalltalk Setup
2+
3+
This guide explains how to set up the Smalltalk skill for [Clawdbot](https://github.com/clawdbot/clawdbot).
4+
5+
## Prerequisites
6+
7+
- **Linux x86_64** (tested on Ubuntu 24.04)
8+
- **Python 3.10+**
9+
- **xvfb** for headless operation
10+
11+
## Step 1: Install System Dependencies
12+
13+
```bash
14+
sudo apt update
15+
sudo apt install xvfb
16+
```
17+
18+
## Step 2: Install Squeak VM
19+
20+
Download Squeak 6.0 from https://squeak.org/downloads/
21+
22+
```bash
23+
cd ~
24+
wget https://files.squeak.org/6.0/Squeak6.0-22148-64bit-202312181441-Linux-x64.tar.gz
25+
tar xzf Squeak6.0-22148-64bit-202312181441-Linux-x64.tar.gz
26+
```
27+
28+
## Step 3: Build the Image
29+
30+
Follow [SQUEAK-SETUP.md](SQUEAK-SETUP.md) to:
31+
1. Install OSProcess package
32+
2. File in `MCP-Server-Squeak.st`
33+
3. Register MCPServer for startup
34+
4. Save as `ClaudeSqueak.image`
35+
36+
Or for Cuis, use the provided `ClaudeCuis.image`.
37+
38+
## Step 4: Set Up Sources File
39+
40+
The Smalltalk image needs access to the sources file. Symlink it to your image directory:
41+
42+
```bash
43+
# For Squeak
44+
ln -s ~/Squeak6.0-*/shared/SqueakV60.sources ~/SqueakV60.sources
45+
46+
# Or copy it next to your image
47+
cp ~/Squeak6.0-*/shared/SqueakV60.sources ~/
48+
```
49+
50+
## Step 5: Install the Skill
51+
52+
Copy the skill to your Clawdbot skills directory:
53+
54+
```bash
55+
mkdir -p ~/clawd/skills/smalltalk
56+
cp clawdbot/SKILL.md ~/clawd/skills/smalltalk/
57+
cp clawdbot/smalltalk.py ~/clawd/skills/smalltalk/
58+
chmod +x ~/clawd/skills/smalltalk/smalltalk.py
59+
```
60+
61+
## Step 6: Configure Paths (Optional)
62+
63+
The script auto-detects common paths. If needed, set environment variables:
64+
65+
```bash
66+
export SQUEAK_VM_PATH=~/Squeak6.0-22148-64bit-202312181441-Linux-x64/bin/squeak
67+
export SQUEAK_IMAGE_PATH=~/ClaudeSqueak.image
68+
```
69+
70+
Add to `~/.bashrc` or `~/.profile` to persist.
71+
72+
## Step 7: Verify Setup
73+
74+
```bash
75+
python3 ~/clawd/skills/smalltalk/smalltalk.py --check
76+
```
77+
78+
Expected output:
79+
```
80+
🔍 Checking Clawdbot Smalltalk setup...
81+
82+
✅ xvfb-run found
83+
✅ VM found: /home/user/Squeak6.0-.../bin/squeak
84+
✅ Image found: /home/user/ClaudeSqueak.image
85+
✅ Sources file found: /home/user/SqueakV60.sources
86+
87+
✅ Setup looks good!
88+
```
89+
90+
## Step 8: Test
91+
92+
```bash
93+
python3 ~/clawd/skills/smalltalk/smalltalk.py evaluate "3 factorial"
94+
# Should output: 6
95+
```
96+
97+
## Usage with Clawdbot
98+
99+
Once set up, ask Clawdbot things like:
100+
- "Evaluate `Date today` in Smalltalk"
101+
- "Browse the OrderedCollection class"
102+
- "Show me the source of String>>asUppercase"
103+
- "What are the subclasses of Collection?"
104+
105+
## Troubleshooting
106+
107+
### Dialog boxes blocking (sources file)
108+
```
109+
Squeak cannot locate the sources file...
110+
```
111+
**Fix:** Symlink or copy the sources file next to your image.
112+
113+
### xvfb-run not found
114+
```bash
115+
sudo apt install xvfb
116+
```
117+
118+
### Permission denied on VM
119+
```bash
120+
chmod +x ~/Squeak6.0-*/bin/squeak
121+
```
122+
123+
### No response from MCP server
124+
- Ensure image was saved after `Smalltalk addToStartUpList: MCPServer`
125+
- Check that `--mcp` flag triggers the server
126+
- Verify xvfb is working: `xvfb-run -a echo "works"`
127+
128+
### Debugging a hung system with screenshots
129+
130+
If the MCP server isn't responding, Squeak may be blocked on a dialog (e.g., missing sources file). Capture a screenshot of the virtual display:
131+
132+
```bash
133+
# Start Xvfb on display :99
134+
export DISPLAY=:99
135+
Xvfb :99 -screen 0 1024x768x24 &
136+
137+
# Start Squeak
138+
/path/to/squeak ~/ClaudeSqueak.image --mcp &
139+
140+
# Wait a few seconds, then capture screenshot
141+
sleep 5
142+
import -window root -display :99 /tmp/squeak_debug.png
143+
144+
# View the screenshot to see what's blocking
145+
```
146+
147+
Requires `imagemagick` (`sudo apt install imagemagick`).
148+
149+
### Getting a stack trace with SIGUSR1
150+
151+
Send SIGUSR1 to the Squeak process to dump the current stack to stderr:
152+
153+
```bash
154+
# Find the Squeak process
155+
pgrep -f squeak
156+
157+
# Send signal (replace PID with actual)
158+
kill -USR1 <PID>
159+
```
160+
161+
If Squeak was started with output redirected to a log file:
162+
```bash
163+
/path/to/squeak image.image --mcp > /tmp/squeak.log 2>&1 &
164+
```
165+
166+
The stack trace will appear in `/tmp/squeak.log`, showing what each process is doing:
167+
```
168+
ProcessorScheduler>>#relinquishProcessorForMicroseconds:
169+
EventSensor>>#primGetNextEvent:
170+
Semaphore>>#wait
171+
...
172+
(SIGUSR1)
173+
```
174+
175+
This helps identify what's blocking when the MCP server is unresponsive.
176+
177+
### pthread_setschedparam warning
178+
This is harmless. To suppress, create:
179+
```bash
180+
sudo tee /etc/security/limits.d/squeak.conf << 'EOF'
181+
* hard rtprio 2
182+
* soft rtprio 2
183+
EOF
184+
```
185+
Then log out and back in.
186+
187+
## Architecture
188+
189+
```
190+
Clawdbot
191+
│
192+
▼ exec
193+
smalltalk.py
194+
│
195+
▼ xvfb-run + stdio
196+
Squeak VM + ClaudeSqueak.image
197+
│
198+
▼ MCP JSON-RPC
199+
MCPServer (12 tools)
200+
```

‎README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,20 @@ Developed by John M McIntosh, Corporate Smalltalk Consulting Ltd. 2026
6464
- Requires Python 3.10+ and OpenAI API key
6565
- See [OPENAI-SETUP.md](OPENAI-SETUP.md) for detailed instructions
6666

67+
### Option E: Clawdbot Integration
68+
69+
```
70+
┌─────────────┐ Telegram ┌─────────────────┐ exec/stdio ┌─────────────────┐
71+
│ User │ ◄──────────────► │ Clawdbot │ ◄──────────────► │ Squeak 6.0 │
72+
│ (Mobile/ │ (messages) │ (AI Agent) │ (subprocess) │ MCPServer │
73+
│ Desktop) │ │ │ │ │
74+
└─────────────┘ └─────────────────┘ └─────────────────┘
75+
```
76+
77+
- Enables **Clawdbot** (Telegram/Discord AI agent) to interact with Smalltalk
78+
- Includes debug tools: `--check` (verify setup) and `--debug` (SIGUSR1 stack trace + screenshot)
79+
- See [CLAWDBOT-SETUP.md](CLAWDBOT-SETUP.md) for detailed instructions
80+
6781
## Prerequisites
6882

6983
**For Option B (Cuis Native MCP):**
@@ -85,6 +99,12 @@ Developed by John M McIntosh, Corporate Smalltalk Consulting Ltd. 2026
8599
- **OpenAI API Key** from https://platform.openai.com/api-keys
86100
- **Squeak 6.0** with MCP server (same as Option C)
87101

102+
**For Option E (Clawdbot):**
103+
- **Clawdbot** installed and configured (https://github.com/clawdbot/clawdbot)
104+
- **Squeak 6.0** with MCP server (same as Option C)
105+
- **Xvfb** and **ImageMagick** for headless operation on Linux
106+
- **Python 3.10+** for the skill wrapper
107+
88108
---
89109

90110
## Installation: Option B (Cuis Native MCP)
@@ -305,6 +325,43 @@ python openai_mcp.py
305325
python openai_mcp.py "Evaluate 3 factorial in Smalltalk"
306326
```
307327

328+
## Installation: Option E (Clawdbot)
329+
330+
See [CLAWDBOT-SETUP.md](CLAWDBOT-SETUP.md) for detailed step-by-step instructions.
331+
332+
### Quick Start
333+
334+
1. **Set up Squeak MCP server** (same as Option C)
335+
2. **Install dependencies**:
336+
337+
```bash
338+
sudo apt install xvfb imagemagick
339+
```
340+
341+
3. **Copy skill files** to your Clawdbot workspace:
342+
343+
```bash
344+
cp -r clawdbot/ ~/clawd/skills/smalltalk/
345+
```
346+
347+
4. **Verify setup**:
348+
349+
```bash
350+
python3 ~/clawd/skills/smalltalk/clawdbot/smalltalk.py --check
351+
```
352+
353+
5. **Debug a hung image**:
354+
355+
```bash
356+
python3 ~/clawd/skills/smalltalk/clawdbot/smalltalk.py --debug
357+
```
358+
359+
This generates `/tmp/ClaudeSmalltalkDebug_YYYYMMDD_HHMMSS.html` with:
360+
- Screenshot of the Squeak display
361+
- Full SIGUSR1 stack trace of all processes
362+
363+
---
364+
308365
## Available Tools
309366

310367
| Tool | Description |
@@ -413,6 +470,10 @@ MQTTConnectionTest buildSuite run inspect.
413470
| `openai_mcp.py` | OpenAI bridge for ChatGPT (Option D) |
414471
| `openai_tools.py` | OpenAI tool definitions (Option D) |
415472
| `OPENAI-SETUP.md` | Step-by-step guide for OpenAI setup |
473+
| `clawdbot/` | Clawdbot skill files (Option E) |
474+
| `clawdbot/SKILL.md` | Clawdbot skill definition |
475+
| `clawdbot/smalltalk.py` | Clawdbot wrapper with --check and --debug |
476+
| `CLAWDBOT-SETUP.md` | Step-by-step guide for Clawdbot setup |
416477
| `requirements.txt` | Python dependencies (Options A & D) |
417478
| `MQTT-Cuis.pck.st` | MQTT client library for Cuis (Option A) |
418479
| `ClaudeCuis.pck.st` | Claude handler (Option A) |

‎clawdbot/SKILL.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
name: smalltalk
3+
description: Interact with live Smalltalk image (Cuis or Squeak). Use for evaluating Smalltalk code, browsing classes, viewing method source, defining classes/methods, querying hierarchy and categories.
4+
metadata: {"clawdbot":{"emoji":"💎","requires":{"bins":["python3","xvfb-run"]}}}
5+
---
6+
7+
# Smalltalk Skill
8+
9+
Execute Smalltalk code and browse live Squeak/Cuis images via MCP.
10+
11+
## Setup
12+
13+
See [CLAWDBOT-SETUP.md](../CLAWDBOT-SETUP.md) for installation instructions.
14+
15+
## Usage
16+
17+
```bash
18+
# Check setup
19+
python3 smalltalk.py --check
20+
21+
# Evaluate code
22+
python3 smalltalk.py evaluate "3 factorial"
23+
python3 smalltalk.py evaluate "Date today"
24+
25+
# Browse a class
26+
python3 smalltalk.py browse OrderedCollection
27+
28+
# View method source
29+
python3 smalltalk.py method-source String asUppercase
30+
31+
# List classes (with optional prefix filter)
32+
python3 smalltalk.py list-classes Collection
33+
34+
# Get class hierarchy
35+
python3 smalltalk.py hierarchy OrderedCollection
36+
37+
# Get subclasses
38+
python3 smalltalk.py subclasses Collection
39+
40+
# List all categories
41+
python3 smalltalk.py list-categories
42+
43+
# List classes in a category
44+
python3 smalltalk.py classes-in-category "Collections-Sequenceable"
45+
46+
# Define a new class
47+
python3 smalltalk.py define-class "Object subclass: #Counter instanceVariableNames: 'count' classVariableNames: '' poolDictionaries: '' category: 'MyApp'"
48+
49+
# Define a method
50+
python3 smalltalk.py define-method Counter "increment
51+
count := (count ifNil: [0]) + 1.
52+
^ count"
53+
54+
# Delete a method
55+
python3 smalltalk.py delete-method Counter increment
56+
57+
# Delete a class
58+
python3 smalltalk.py delete-class Counter
59+
```
60+
61+
## Commands
62+
63+
| Command | Description |
64+
|---------|-------------|
65+
| `--check` | Verify VM/image paths and dependencies |
66+
| `--debug` | Debug hung system (sends SIGUSR1, captures stack trace) |
67+
| `evaluate <code>` | Execute Smalltalk code, return result |
68+
| `browse <class>` | Get class metadata (superclass, ivars, methods) |
69+
| `method-source <class> <selector>` | View method source code |
70+
| `define-class <definition>` | Create or modify a class |
71+
| `define-method <class> <source>` | Add or update a method |
72+
| `delete-method <class> <selector>` | Remove a method |
73+
| `delete-class <class>` | Remove a class |
74+
| `list-classes [prefix]` | List classes, optionally filtered |
75+
| `hierarchy <class>` | Get superclass chain |
76+
| `subclasses <class>` | Get immediate subclasses |
77+
| `list-categories` | List all system categories |
78+
| `classes-in-category <cat>` | List classes in a category |
79+
80+
## Environment Variables
81+
82+
| Variable | Description |
83+
|----------|-------------|
84+
| `SQUEAK_VM_PATH` | Path to Squeak/Cuis VM executable |
85+
| `SQUEAK_IMAGE_PATH` | Path to Smalltalk image with MCP server |
86+
87+
## Notes
88+
89+
- Requires xvfb for headless operation on Linux servers
90+
- Uses Squeak 6.0 MCP server (GUI stays responsive if display available)
91+
- `saveImage` intentionally excluded for safety

0 commit comments

Comments
 (0)