Smalltalk Skill
Execute Smalltalk code and browse live Squeak/Cuis images via MCP.
Prerequisites
Get the ClaudeSmalltalk repo first:
git clone https://github.com/CorporateSmalltalkConsultingLtd/ClaudeSmalltalk.git
This repo contains:
- MCP server code for Squeak (
MCP-Server-Squeak.st
)
- Setup documentation (
SQUEAK-SETUP.md
, CLAWDBOT-SETUP.md
)
- This Clawdbot skill (
clawdbot/
)
Setup
- Set up Squeak with MCP server — see SQUEAK-SETUP.md
- Configure Clawdbot — see CLAWDBOT-SETUP.md
Usage
# Check setup
python3 smalltalk.py --check
Evaluate code
python3 smalltalk.py evaluate "3 factorial"
python3 smalltalk.py evaluate "Date today"
Browse a class
python3 smalltalk.py browse OrderedCollection
View method source (instance side)
python3 smalltalk.py method-source String asUppercase
View method source (class side)
python3 smalltalk.py method-source "MCPServer class" version
python3 smalltalk.py method-source MCPServer version --class-side
List classes (with optional prefix filter)
python3 smalltalk.py list-classes Collection
Get class hierarchy
python3 smalltalk.py hierarchy OrderedCollection
Get subclasses
python3 smalltalk.py subclasses Collection
List all categories
python3 smalltalk.py list-categories
List classes in a category
python3 smalltalk.py classes-in-category "Collections-Sequenceable"
Define a new class
python3 smalltalk.py define-class "Object subclass: #Counter instanceVariableNames: 'count' classVariableNames: '' poolDictionaries: '' category: 'MyApp'"
Define a method
python3 smalltalk.py define-method Counter "increment
count := (count ifNil: [0]) + 1.
^ count"
Delete a method
python3 smalltalk.py delete-method Counter increment
Delete a class
python3 smalltalk.py delete-class Counter
Operating Modes
Playground (Default)
Stock image, ephemeral. Changes are discarded when daemon stops.
User says: "load Smalltalk skill" or "invoke Smalltalk" — no special flags.
# Start playground daemon
nohup python3 smalltalk-daemon.py start > /tmp/daemon.log 2>&1 &
Dev Mode
User supplies their own image/changes pair. Changes persist across sessions.
User says: "load Smalltalk skill in dev mode with ~/MyProject.image"
# Start dev daemon with custom image
nohup python3 smalltalk-daemon.py start --dev --image ~/MyProject.image > /tmp/daemon.log 2>&1 &
Dev mode sets
SMALLTALK_DEV_MODE=1
so the MCP server keeps the .changes file
(instead of redirecting to /dev/null). The supplied image must have a matching
.changes file alongside it.
Common Commands
# Check status
python3 smalltalk.py --daemon-status
Stop daemon
python3 smalltalk-daemon.py stop
Restart in dev mode
python3 smalltalk-daemon.py restart --dev --image ~/MyProject.image
Commands
| Command | Description |
|---|
--check
| Verify VM/image paths and dependencies |
--daemon-status
| Check if daemon is running |
--debug
| Debug hung system (sends SIGUSR1, captures stack trace) |
evaluate <code>
| Execute Smalltalk code, return result |
browse <class>
| Get class metadata (superclass, ivars, instance methods
and classMethods
) |
method-source <class> <selector> [--class-side]
| View method source code (supports "Class class"
syntax or --class-side
flag) |
define-class <definition>
| Create or modify a class |
define-method <class> <source>
| Add or update a method |
delete-method <class> <selector>
| Remove a method |
delete-class <class>
| Remove a class |
list-classes [prefix]
| List classes, optionally filtered |
hierarchy <class>
| Get superclass chain |
subclasses <class>
| Get immediate subclasses |
list-categories
| List all system categories |
classes-in-category <cat>
| List classes in a category |
explain <code>
| Explain Smalltalk code (requires ANTHROPIC_API_KEY
or OPENAI_API_KEY
) |
explain-method <class> <sel> [--class-side] [--source <code>]
| Fetch method from image and explain it (or use --source
/--source-file
/--source-stdin
to bypass daemon) |
audit-comment <class> <sel> [--class-side] [--source <code>]
| Audit method comment vs implementation (or use --source
/--source-file
/--source-stdin
to bypass daemon) |
audit-class <class>
| Audit all methods in a class (instance + class side) |
generate-sunit <targets> [--force] [--class-name <name>]
| Generate SUnit tests for methods and file into image |
Environment Variables
| Variable | Description |
|---|
SQUEAK_VM_PATH
| Path to Squeak/Cuis VM executable |
SQUEAK_IMAGE_PATH
| Path to Smalltalk image with MCP server |
ANTHROPIC_API_KEY
| API key for Anthropic Claude (preferred for LLM tools) |
ANTHROPIC_MODEL
| Anthropic model (default: claude-opus-4-20250514
) |
OPENAI_API_KEY
| API key for OpenAI (fallback for LLM tools) |
OPENAI_MODEL
| OpenAI model (default: gpt-4o
) |
LLM_PROVIDER
| Force LLM provider: anthropic
or openai
(auto-detected if not set) |
Using with Claude Code (MCP mode)
When Claude Code has a live Smalltalk image connected via MCP,
explain-method
and
audit-comment
can use pre-fetched source code instead of requiring a running daemon. Use
--source
,
--source-file
, or
--source-stdin
to pass the method source directly:
# Inline source (fetched via MCP, passed on command line)
python3 smalltalk.py explain-method SmallInteger + --source "+ aNumber <primitive: 1> ^ super + aNumber"
Source from a file
python3 smalltalk.py audit-comment Integer factorial --source-file /tmp/factorial.st
Source piped via stdin
echo "printString ^ self printStringLimitedTo: 50000" | python3 smalltalk.py explain-method Object printString --source-stdin
The three source flags are mutually exclusive. When none is provided, the daemon is used as before.
Generating SUnit Tests
The
generate-sunit
command uses an LLM to generate SUnit test cases for Smalltalk methods and files them directly into the running image:
# Generate tests for a single method
python3 smalltalk.py generate-sunit "String>>asUppercase"
Generate tests for multiple methods
python3 smalltalk.py generate-sunit "Random>>next" "Random>>nextInt:" "Random>>seed:"
Generate tests for an entire class (all instance methods)
python3 smalltalk.py generate-sunit "OrderedCollection"
Generate tests for class-side methods
python3 smalltalk.py generate-sunit "Date class>>today"
Custom test class name
python3 smalltalk.py generate-sunit "String>>asUppercase" --class-name MyStringTests
Overwrite existing test class
python3 smalltalk.py generate-sunit "String>>asUppercase" --force
Run the generated tests
python3 smalltalk.py evaluate "StringGeneratedTest buildSuite run printString"
The generated TestCase uses standard SUnit assertions (
assert:
,
assert:equals:
,
deny:
,
should:raise:
) and is filed into a
GeneratedSUnit-*
category.
Notes
- Requires xvfb for headless operation on Linux servers
- Uses Squeak 6.0 MCP server (GUI stays responsive if display available)
saveImage
intentionally excluded for safety- MCPServer version 7+ required (v7 adds class-side method support)
- Playground mode: ephemeral, .changes → /dev/null
- Dev mode: persistent, .changes kept, requires
--dev --image PATH
