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)
saveImageintentionally 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