smalltalk-dev Plugin

Claude Code plugin for AI-driven Smalltalk (Pharo) development.

Also available for Cursor, Windsurf, Antigravity, GitHub Copilot CLI, OpenCode, and Codex CLI.

This plugin provides a minimal, practical toolkit for Smalltalk development using AI skills. It focuses on the essential workflow of editing Tonel files, importing them into Pharo, and running tests.

• Commands: Essential slash commands for import, test, eval, and validation
• Skills: AI-powered development workflow, debugging expertise, and documentation
• MCP Integration: Seamless connection to Pharo and validation servers
• Hooks: Automatic suggestions after file changes

The easiest way to use this plugin is to use the /st-buddy command:

# Start Smalltalk Buddy (once per session)
/st-buddy

# Then ask questions naturally
You: "I want to create a Person class with name and age"
AI:  I'll help you create that! [Creates Tonel files and guides you through the process]

You: "How do I test this?"
AI:  Let me run the tests for you... [Executes tests and shows results]

You: "The test failed, can you help?"
AI:  I'll debug this... [Investigates, identifies issue, and fixes it]

st-buddy-money-short.mp4

/st-buddy is your friendly development partner that:

• Understands what you want to do and routes to the right tools
• Guides you through development, testing, and debugging
• Helps you learn AI-assisted Smalltalk development
• Works naturally through conversation

1. Run /st-buddy once at the start of your session
2. Ask questions naturally about what you want to do
3. AI implements and manages the workflow (editing Tonel, importing, testing)
4. Review results and continue the conversation
5. Iterate until you're satisfied

For experienced users who prefer direct commands, see Commands.md.

Choose one of the following options:

Run a pre-configured Pharo image using smalltalk-interop-docker:

docker compose up -d

Install PharoSmalltalkInteropServer in your Pharo image.

Install Claude Code.

Other AI agents: If you use Cursor, Windsurf, Antigravity, GitHub Copilot CLI, OpenCode, or Codex CLI instead of Claude Code, see Other AI Agents Setup Guide.

Install uv, which is used in MCP.

# Add marketplace from GitHub
claude plugin marketplace add mumez/smalltalk-dev-plugin

# Install the plugin
claude plugin install smalltalk-dev

For local testing and development:

# Clone the repository
git clone https://github.com/mumez/smalltalk-dev-plugin.git
cd smalltalk-dev-plugin

# Add local directory as marketplace
claude plugin marketplace add ./

# Install the plugin
claude plugin install smalltalk-dev

After installation, you should see the custom commands starting with /st-.

The plugin provides essential commands for Smalltalk development:

• /st-buddy - Start your friendly Smalltalk development assistant (recommended starting point)
• /st-init - Load smalltalk-developer skill and explain workflow
• /st-setup-project - Set up Pharo project structure
• /st-eval - Execute Smalltalk code snippets
• /st-lint - Check code quality and best practices
• /st-import - Import Tonel packages to Pharo
• /st-export - Export packages from Pharo
• /st-test - Run SUnit tests
• /st-validate - Validate Tonel syntax

Most users should start with /st-buddy - it will guide you and use the other commands as needed.

For command details and advanced usage, see Commands.md.

The plugin includes specialized AI skills that activate automatically based on your needs:

• smalltalk-developer - Development workflow and best practices
• smalltalk-debugger - Error handling and debugging procedures
• smalltalk-usage-finder - Code usage exploration and analysis
• smalltalk-implementation-finder - Implementation discovery and patterns
• smalltalk-commenter - CRC-style class documentation generation

These skills work behind the scenes when you use /st-buddy, providing specialized knowledge for each task.

Automatically suggests class documentation improvements:

• Detects undocumented classes after file changes (occasionally, not every time)
• Generates CRC-style class comments
• Can be invoked directly: /smalltalk-commenter

Works quietly in the background - you'll get occasional suggestions to improve documentation.

The plugin exposes all tools from both MCP servers:

pharo-interop (22 tools):

• eval: Execute Smalltalk expressions
• import_package, export_package: Package management
• run_class_test, run_package_test: Test execution
• get_class_source, get_method_source: Code inspection
• search_implementors, search_references: Code navigation
• And more...

smalltalk-validator (5 tools):

• validate_tonel_smalltalk_from_file: File validation
• validate_tonel_smalltalk: Content validation
• validate_smalltalk_method_body: Method validation
• lint_tonel_smalltalk_from_file: File linting
• lint_tonel_smalltalk: Content linting

The plugin uses two MCP servers:

1. pharo-interop: Communication with Pharo image
2. smalltalk-validator: Tonel syntax validation

These are configured automatically via .mcp.json. You can customize the Pharo port:

export PHARO_SIS_PORT=8086  # default

# Remove the plugin
claude plugin uninstall smalltalk-dev

If you also want to remove the marketplace entry:

claude plugin marketplace remove smalltalk-dev-marketplace

Note: The marketplace name depends on how you added it. Use claude plugin marketplace list to see the exact name.

When developing locally and need to test changes:

# Uninstall current version
claude plugin uninstall smalltalk-dev

# Remove marketplace
claude plugin marketplace remove smalltalk-dev-marketplace

# Re-add marketplace
claude plugin marketplace add ./

# Reinstall plugin
claude plugin install smalltalk-dev

1. Edit Tonel files (AI editor is the source of truth)
2. Lint code with /st-lint to check quality
3. Import to Pharo with absolute paths
4. Test after every import

• Use /st-lint before importing to catch issues early
• Add class prefixes to avoid name collisions
• Keep methods focused (15 lines standard, 40 for UI/tests)
• Limit instance variables (max 10 per class)
• Access instance variables through methods, not directly

• Always use absolute paths for imports
• Import multiple packages individually

• AI editor is the source of truth (Tonel files)
• Avoid editing in Pharo directly
• Use export_package only when necessary

• Re-import after every change
• Import main package before test package
• Don't forget to import test packages

• Run tests after every import
• Use run_class_test for specific classes
• Use run_package_test for full packages

• Use /st-eval for quick partial execution
• Capture both results and errors in Array
• Use printString for object serialization
• Debug step-by-step

Make sure PharoSmalltalkInteropServer is running:

SisServer current start.
SisServer current.  "Should show running server"

• Verify absolute path is correct
• Check that .st files are in correct directory
• Ensure package.st exists

1. Check test error message
2. Use /st-validate to check syntax
3. Use /st-eval to debug specific code
4. Fix in Tonel file
5. Re-import and re-test

• Check Pharo Transcript for error messages
• Verify server port matches configuration: SisServer teapotConfig
• Try /st-eval Smalltalk version to test connection

smalltalk-dev-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Plugin metadata
│   └── marketplace.json     # Marketplace configuration
├── .mcp.json                # MCP server configuration
├── commands/
│   ├── st-buddy.md          # /st-buddy - Friendly development assistant
│   ├── st-init.md           # /st-init - Start development session
│   ├── st-setup-project.md  # /st-setup-project - Project boilerplate
│   ├── st-eval.md           # /st-eval - Execute Smalltalk code
│   ├── st-import.md         # /st-import - Import Tonel packages
│   ├── st-export.md         # /st-export - Export packages
│   ├── st-test.md           # /st-test - Run SUnit tests
│   ├── st-lint.md           # /st-lint - Check code quality
│   └── st-validate.md       # /st-validate - Validate Tonel syntax
├── skills/
│   ├── smalltalk-commenter/
│   │   └── SKILL.md         # Documentation specialist skill
│   ├── smalltalk-developer/
│   │   ├── SKILL.md         # Development workflow
│   │   ├── examples/        # Development sessions
│   │   └── references/      # Best practices, Tonel format
│   ├── smalltalk-debugger/
│   │   ├── SKILL.md         # Debugging techniques
│   │   ├── examples/        # Debug scenarios
│   │   └── references/      # Error patterns, inspection, UI debugging
│   ├── smalltalk-usage-finder/
│   │   ├── SKILL.md         # Usage exploration
│   │   ├── examples/        # Usage scenarios
│   │   └── references/      # Usage analysis
│   └── smalltalk-implementation-finder/
│       ├── SKILL.md         # Implementation analysis
│       ├── examples/        # Implementation scenarios
│       └── references/      # Implementation analysis
├── hooks/
│   └── hooks.json           # PostToolUse hook configuration
├── scripts/
│   └── suggest-class-comment.sh     # PostToolUse hook for documentation suggestions
├── extra/
│   ├── setup-cursor.sh              # Setup script for Cursor
│   ├── setup-windsurf.sh            # Setup script for Windsurf
│   ├── setup-antigravity.sh         # Setup script for Antigravity
│   ├── setup-copilot.sh             # Setup script for GitHub Copilot CLI
│   ├── setup-opencode.sh            # Setup script for OpenCode
│   ├── setup-codex.sh               # Setup script for Codex CLI
│   ├── opencode.json                # MCP config for OpenCode
│   └── suggest-class-comment_cursor.sh # Hook script for Cursor
├── doc/
│   ├── Commands.md                  # Commands quick reference
│   └── setup-other-agents.md       # Setup guide for other AI agents
├── README.md                # This file
└── claudedocs/
    └── test-scenarios.md    # Testing documentation

• Introducing smalltalk-dev Plugin

Projects built with this plugin:

• smalltalk-dev-plugin-money-example - Multi-currency Money class with arithmetic operations and exchange rate conversion
• smalltalk-dev-plugin-graph-example - Directed weighted graph with Dijkstra's shortest-path algorithm
• smalltalk-dev-plugin-gui-example - Interactive to-do list app built with the Spec2 framework

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Claude Code
5. Submit a pull request

MIT License - see LICENSE file for details

• MCP Servers:
  • pharo-smalltalk-interop-mcp-server by mumez
  • smalltalk-validator-mcp-server by mumez
• Claude Code: Anthropic
• Pharo: Pharo Project