pharo-agent

pharo-agent gives a coding agent a Pharo Launcher of its own. It can see the templates the launcher offers, create images from them, start and stop them, and work inside the ones it started: classes, methods, senders, tests, refactorings, critiques, and the rest of what a Pharo IDE does. On macOS and Linux it can also read and edit an image's source as files.

It works with Claude Code, Codex and OpenCode.

What it is made of

This plugin is the glue. Three projects do the work, and each is useful on its own:

• PLexus drives Pharo Launcher. It creates, lists, starts, stops and deletes images, and forwards MCP calls to the server running in each one.
• MCP for Pharo is that server. It works through Pharo's own compiler, refactorings, SUnit, Iceberg and Epicea rather than patching exported text, and it maintains the Pharo guidance a project gets.
• pharo-image-fs projects a live image's source as a filesystem, so ordinary file tools edit the image itself.

The plugin pins one released version of each, so a project gets a set that was tested together, and gives the agent one command surface over the lot.

Requirements

• Node 22.12 or later.
• Pharo Launcher, which is where images and templates come from.
• For editing source as files: macOS, which needs nothing more, or Linux with FUSE 3 (the fuse3 package, installed by default on most distributions). Its daemon is downloaded for you. Where a projection cannot mount, the image starts with its Pharo tools and a warning saying why, rather than failing.

On a Pharo version the pinned MCP does not load on, creating an image fails with the load's own error, unless a load script of your own brings the tools in another way.

Setup

In Claude Code, install it as a plugin:

/plugin marketplace add Evref-BL/pharo-agent-plugin
/plugin install pharo-agent@evref-bl

Then ask the agent to enable Pharo tooling in a project. The plugin carries a setup skill that does it, and declares the pharo MCP server, so a running image's tools reach the chat with nothing configured by hand. Hosts covers enabling it per project rather than everywhere.

Any host can run the CLI instead. In the project directory, once:

npx --yes @evref-bl/pharo-agent init --host <claude|codex|opencode>

What the agent gets

The launcher. image templates names every template the installation offers. image create <name> --template <template> makes an image with the image tools in it, image start <name> starts it, image stop <name> kills it, and image delete <name> deletes it. A project can have as many images as it likes — one per Pharo version, one per subject, one to throw away — and run them at once; image list says which exist and which are running. Images has the rest.

The tools of each running image. Classes, methods, senders, tests and evaluation are advertised; the fuller catalogue, such as packages, repositories, change history and debuggers, is searched rather than listed, so its schemas stay out of the agent's context. The tools belong to the image, so what exists depends on what that image has loaded. Tools covers both, and serving a different MCP from an image.

Source as files, on macOS and Linux. Starting an image mounts its source below .pharo-agent/mounts. A file edited there is compiled into the live image: the files and the tools are two views of one image, not of an export and an image. Setting PHARO_AGENT_PROJECTION=off in the environment starts images without mounting anything.

Guidance for the agent. Setting a project up writes a Pharo guide into it, and a conditional line in the host's own guide pointing at that guide for Pharo work only, so Pharo instructions stay out of unrelated chats. The guide and what it refers to are maintained by the MCP project and copied from the release this plugin pins. Hosts lists the paths it owns.

A way to report what got in its way. The plugin's feedback skill has the agent look back over the conversation for tool calls that failed, misled it or needed a workaround, and draft issues for the tools' maintainers. It offers itself at the end of Pharo work where that happened, searches for existing issues first, and files only the drafts you approve.

Refreshing after an upgrade

Upgrade the plugin the way you installed it, then run the setup command again in the project, naming the same host. That rewrites the generated guide and the files copied with it, from the templates the new version pins.

Images, runtime state and settings are kept, and so is anything outside the block the plugin marks as its own; --mount-root changes only the mount root. Generated and copied files are overwritten, so keep project-specific instructions out of them. Refreshing a project upgrades neither the installed plugin nor the code inside a running image; Images covers the image side.

Reading further

pharo-agent --help gives the command overview, and --help on a command gives its options, defaults and an example. Help works before a project is set up.

• Hosts — what setup writes, and installing as a plugin.
• Images — what an image is, templates and categories, starting and stopping, several images at once.
• Tools — the advertised surface, finding the rest, the stdio bundle, and serving a different MCP.