@evref-bl/pharo-agent 0.12.1 → 0.12.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +3 -7
- package/README.md +90 -47
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills/pharo-setup/SKILL.md +1 -1
package/.mcp.json
CHANGED
package/README.md
CHANGED
|
@@ -1,8 +1,44 @@
|
|
|
1
1
|
# pharo-agent
|
|
2
2
|
|
|
3
|
-
`pharo-agent` gives a coding agent a
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
`pharo-agent` gives a coding agent a Pharo Launcher of its own. It can see the
|
|
4
|
+
templates the launcher offers, create images from them, start and stop them,
|
|
5
|
+
and work inside the ones it started: classes, methods, senders, tests,
|
|
6
|
+
refactorings, critiques, and the rest of what a Pharo IDE does. On macOS it
|
|
7
|
+
can also read and edit an image's source as files.
|
|
8
|
+
|
|
9
|
+
It works with Claude Code, Codex and OpenCode.
|
|
10
|
+
|
|
11
|
+
## What it is made of
|
|
12
|
+
|
|
13
|
+
This plugin is the glue. Three projects do the work, and each is useful on its
|
|
14
|
+
own:
|
|
15
|
+
|
|
16
|
+
- [PLexus](https://github.com/Evref-BL/PLexus) drives Pharo Launcher. It
|
|
17
|
+
creates, starts and stops a project's images, keeps their state outside the
|
|
18
|
+
images, and forwards MCP calls to the server running in each one.
|
|
19
|
+
- [MCP for Pharo](https://github.com/Evref-BL/MCP) is that server. It works
|
|
20
|
+
through Pharo's own compiler, refactorings, SUnit, Iceberg and Epicea rather
|
|
21
|
+
than patching exported text, and it maintains the Pharo guidance a project
|
|
22
|
+
gets.
|
|
23
|
+
- [pharo-image-fs](https://github.com/Evref-BL/pharo-image-fs) projects a live
|
|
24
|
+
image's source as a filesystem, so ordinary file tools edit the image
|
|
25
|
+
itself.
|
|
26
|
+
|
|
27
|
+
The plugin pins one released version of each, so a project gets a set that was
|
|
28
|
+
tested together, and gives the agent one command surface over the lot.
|
|
29
|
+
|
|
30
|
+
## Requirements
|
|
31
|
+
|
|
32
|
+
- Node 22.12 or later.
|
|
33
|
+
- [Pharo Launcher](https://pharo-project.github.io/pharo-launcher/), which is
|
|
34
|
+
where images and templates come from.
|
|
35
|
+
- For editing source as files: macOS with [fuse-t](https://www.fuse-t.org/),
|
|
36
|
+
installed with `brew install --cask fuse-t`. Its daemon is downloaded for
|
|
37
|
+
you. Everywhere else images start with their Pharo tools and no projection,
|
|
38
|
+
rather than failing.
|
|
39
|
+
|
|
40
|
+
The image tools cover Pharo 12 to 15. An image outside that range still
|
|
41
|
+
starts, and says what it will not have.
|
|
6
42
|
|
|
7
43
|
## Setup
|
|
8
44
|
|
|
@@ -14,57 +50,64 @@ In Claude Code, install it as a plugin:
|
|
|
14
50
|
```
|
|
15
51
|
|
|
16
52
|
Then ask the agent to enable Pharo tooling in a project. The plugin carries a
|
|
17
|
-
setup skill that
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
rather than everywhere.
|
|
53
|
+
setup skill that does it, and declares the `pharo` MCP server, so a running
|
|
54
|
+
image's tools reach the chat with nothing configured by hand.
|
|
55
|
+
[Hosts](docs/hosts.md) covers enabling it per project rather than everywhere.
|
|
21
56
|
|
|
22
|
-
Any host can run the CLI instead
|
|
23
|
-
In the project directory:
|
|
57
|
+
Any host can run the CLI instead. In the project directory, once:
|
|
24
58
|
|
|
25
59
|
```sh
|
|
26
60
|
npx --yes @evref-bl/pharo-agent init --host <claude|codex|opencode>
|
|
27
61
|
```
|
|
28
62
|
|
|
29
|
-
That is all of it. `init` writes the project's Pharo guidance and copies the
|
|
30
|
-
workflow skills that guidance refers to. From there the agent registers the
|
|
31
|
-
image the project needs, starts it and uses its tools by following what was
|
|
32
|
-
written; ask it for Pharo work as you would for anything else.
|
|
33
|
-
|
|
34
|
-
## Refreshing an existing project
|
|
35
|
-
|
|
36
|
-
After upgrading the plugin/CLI through your usual installation method, re-run
|
|
37
|
-
`pharo-agent init --host <claude|codex|opencode>` from the project root with
|
|
38
|
-
the same host. This refreshes the generated guidance, skills, and references
|
|
39
|
-
using that CLI version's pinned templates. Image declarations, existing plugin
|
|
40
|
-
settings, and guidance outside the host's managed block are preserved when
|
|
41
|
-
you omit `--mount-root`.
|
|
42
|
-
|
|
43
|
-
Generated/copied files are overwritten, so keep project-specific instructions
|
|
44
|
-
outside them. Refreshing project files does not upgrade the installed package
|
|
45
|
-
or update, restart, or save existing images. See [Hosts](docs/hosts.md) for
|
|
46
|
-
the file ownership rules and [Images](docs/images.md) for image-side MCP updates.
|
|
47
|
-
|
|
48
|
-
## Requirements
|
|
49
|
-
|
|
50
|
-
Node 22.12 or later.
|
|
51
|
-
|
|
52
|
-
Images and their Pharo tools run anywhere Node does. The source projection is
|
|
53
|
-
the exception: it needs macOS with [fuse-t](https://www.fuse-t.org/), whose
|
|
54
|
-
daemon is downloaded for you. Everywhere else an image starts with its tools
|
|
55
|
-
and says that the projection is not available, rather than failing.
|
|
56
|
-
|
|
57
63
|
## What the agent gets
|
|
58
64
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
65
|
+
**The launcher.** `image templates` names every template the installation
|
|
66
|
+
offers. `image add <id> --template <name>` declares an image, and
|
|
67
|
+
`image start <id>` creates it from that template the first time and starts it.
|
|
68
|
+
A project can declare as many images as it likes — one per Pharo version, one
|
|
69
|
+
to throw away — and run them at once; `image list` says what is declared and
|
|
70
|
+
what is running. [Images](docs/images.md) has the rest.
|
|
71
|
+
|
|
72
|
+
**The tools of each running image.** Classes, methods, senders, tests and
|
|
73
|
+
evaluation are advertised; the fuller catalogue, such as packages,
|
|
74
|
+
repositories, change history and debuggers, is searched rather than listed, so
|
|
75
|
+
its schemas stay out of the agent's context. The tools belong to the image, so
|
|
76
|
+
what exists depends on what that image has loaded. [Tools](docs/tools.md)
|
|
77
|
+
covers both, and serving a different MCP from an image.
|
|
78
|
+
|
|
79
|
+
**Source as files, on macOS.** Starting an image mounts its source below
|
|
80
|
+
`.pharo-agent/mounts`. A file edited there is compiled into the live image:
|
|
81
|
+
the files and the tools are two views of one image, not of an export and an
|
|
82
|
+
image.
|
|
83
|
+
|
|
84
|
+
**Guidance for the agent.** Setting a project up writes a Pharo guide into it,
|
|
85
|
+
and a conditional line in the host's own guide pointing at that guide for
|
|
86
|
+
Pharo work only, so Pharo instructions stay out of unrelated chats. The guide
|
|
87
|
+
and what it refers to are maintained by the MCP project and copied from the
|
|
88
|
+
release this plugin pins. [Hosts](docs/hosts.md) lists the paths it owns.
|
|
89
|
+
|
|
90
|
+
## Refreshing after an upgrade
|
|
91
|
+
|
|
92
|
+
Upgrade the plugin the way you installed it, then run the setup command again
|
|
93
|
+
in the project, naming the same host. That rewrites the generated guide and
|
|
94
|
+
the files copied with it, from the templates the new version pins.
|
|
95
|
+
|
|
96
|
+
Image declarations, runtime state and settings are kept, as long as you omit
|
|
97
|
+
`--mount-root`, and so is anything outside the block the plugin marks as its
|
|
98
|
+
own. Generated and copied files are overwritten, so keep project-specific
|
|
99
|
+
instructions out of them. Refreshing a project upgrades neither the installed
|
|
100
|
+
plugin nor the code inside a running image; [Images](docs/images.md) covers
|
|
101
|
+
the image side.
|
|
102
|
+
|
|
103
|
+
## Reading further
|
|
104
|
+
|
|
105
|
+
`pharo-agent --help` gives the command overview, and `--help` on a command
|
|
106
|
+
gives its options, defaults and an example. Help works before a project is set
|
|
107
|
+
up.
|
|
108
|
+
|
|
109
|
+
- [Hosts](docs/hosts.md) — what setup writes, and installing as a plugin.
|
|
67
110
|
- [Images](docs/images.md) — templates and categories, several images at once,
|
|
68
111
|
Pharo versions outside the MCP range.
|
|
69
|
-
- [Tools](docs/tools.md) — the advertised surface, finding the rest,
|
|
70
|
-
|
|
112
|
+
- [Tools](docs/tools.md) — the advertised surface, finding the rest, the stdio
|
|
113
|
+
bundle, and serving a different MCP.
|
package/package.json
CHANGED
package/plugin.json
CHANGED
|
@@ -8,7 +8,7 @@ Run this only when the user asks to enable or refresh Pharo tooling in this proj
|
|
|
8
8
|
From the project root, run the released CLI that matches this plugin:
|
|
9
9
|
|
|
10
10
|
```sh
|
|
11
|
-
npx --yes @evref-bl/pharo-agent@0.12.
|
|
11
|
+
npx --yes @evref-bl/pharo-agent@0.12.2 init --host claude
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
Name the host this chat runs in: `--host claude` in Claude Code,
|