https://github.com/pharo-llm/pharo-agent
A agent for interacting with the Pharo image from the terminal.
https://github.com/pharo-llm/pharo-agent
agents pharo pharo-llm
Last synced: 16 days ago
JSON representation
A agent for interacting with the Pharo image from the terminal.
- Host: GitHub
- URL: https://github.com/pharo-llm/pharo-agent
- Owner: pharo-llm
- License: mit
- Created: 2026-03-26T12:57:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-21T14:10:44.000Z (about 1 month ago)
- Last Synced: 2026-05-21T22:27:11.687Z (about 1 month ago)
- Topics: agents, pharo, pharo-llm
- Language: Smalltalk
- Homepage:
- Size: 93.8 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# PharoAgent
[](https://github.com/pharo-llm/pharo-agent)
[](https://github.com/pharo-llm/pharo-agent/blob/master/LICENSE)
[](https://github.com/pharo-llm/pharo-agent/pulls)
[](https://github.com/pharo-llm/pharo-agent)
[](https://github.com/pharo-llm/pharo-agent/actions/workflows/CI.yml)
PharoAgent is a lightweight TCP server for Pharo that lets external tools send Smalltalk snippets for evaluation and trigger browser navigation commands.
To install stable version of `PharoAgent` in your image you can use:
```smalltalk
Metacello new
githubUser: 'pharo-llm' project: 'pharo-agent' commitish: 'X.X.X' path: 'src';
baseline: 'LLMPharoAgent';
load
```
For development version install it with this:
```smalltalk
Metacello new
githubUser: 'pharo-llm' project: 'pharo-agent' commitish: 'main' path: 'src';
baseline: 'LLMPharoAgent';
load.
```
## Start the agent
In the Playground, run:
```smalltalk
PharoAgent start
````
To use a custom port:
```smalltalk
PharoAgent startOn: 4044
```
## Restart cleanly
If you reloaded the class and want a fresh restart, run:
```smalltalk
PharoAgent stop.
PharoAgent resetDefault.
PharoAgent start
```
## Evaluate an expression
```bash
echo "3 + 4" | nc localhost 4044
```
Expected output:
```text
7
```
## Open a class browser
```bash
echo "OPEN_CLASS_BROWSER String" | nc localhost 4044
```
## Talk to the live image from Claude Code, Codex, or Qwen (MCP)
PharoAgent ships with an MCP server (`LLM-Pharo-MCP`) that exposes the running
image over HTTP so CLI agents like [Claude Code](https://claude.com/claude-code),
Codex, or Qwen Code can talk directly to it — evaluate Smalltalk, open browsers,
read class and method source, create classes, and compile methods — without
spawning a fresh headless Pharo per call.
### Start the MCP server
In a Playground:
```smalltalk
PharoAgent startMcp.
"or on a custom port"
PharoAgent startMcpOn: 4046.
```
The server listens on `http://localhost:4046/mcp` by default. Override with the
`PHARO_MCP_PORT` environment variable before launching the image.
To stop it:
```smalltalk
PharoAgent stopMcp.
```
### Configure your CLI agent
The repo ships a ready-to-use `.mcp.json` at the root:
```json
{
"mcpServers": {
"pharo": {
"type": "http",
"url": "http://localhost:4046/mcp"
}
}
}
```
Claude Code picks it up automatically when started from the repo root. For
Codex, Qwen or any other MCP-speaking client, point its MCP config at the same
URL.
### Registered tools
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------- |
| `pharo_eval` | Evaluate a Smalltalk expression, returns its `printString` |
| `pharo_open_class_browser` | Open a System Browser on the given class |
| `pharo_open_method_browser` | Open a System Browser on `ClassName>>selector` |
| `pharo_class_source` | Return the class definition and its selector list |
| `pharo_method_source` | Return the source of a single method |
| `pharo_create_class` | Create a class in the live image |
| `pharo_compile_method` | Compile an instance-side or class-side method |
### Registered resources
| URI | Description |
| ----------------------------------------- | --------------------------------------- |
| `pharo://system/info` | Pharo version, package count, image path |
| `pharo://class/{className}` | Class definition + method list |
| `pharo://method/{className}/{selector}` | Source of a single method |
### Example terminal-driven edits
Once the MCP server is running, a connected terminal agent can ask Pharo to do
real image edits such as:
- create `MyCounter` as a subclass of `Object` in package `Demo-Core`
- compile `value ^ 42` on `MyCounter`
- compile `default ^ self new` on the class side of `MyCounter`