pharo-agentic-browser

Agentic AI Coding Workspace for Pharo

pharo-agentic-browser brings Pharo AI coding to your image as a native agentic coding environment: a Pharo-native UI tool for managing multiple AI coding agent sessions — Claude Code, Gemini CLI, OpenCode, and others — in parallel from inside your Pharo image. It enables AI-assisted Smalltalk development by letting each session, called a topic, work as an autonomous agent on your code: you type a request, the agent works, and pauses only when it needs your approval.

Presentation

• Introducing Pharo Agentic Browser
• pharo-agentic-browser in 3 minutes — a demo of generating a URL-routing Trie class from a simple prompt, using OpenCode with the GPT-5.6 Terra model.

Overview

+---------------------+-------------------------------------------+
|   Topics            |  [Human] @QueryClass refactor this        |
|                     |                                           |
|                     +-------------------------------------------+
| ❇️DB Optimization  |  [AI] I'll refactor QueryClass. First,    |
|  UI Improvement     |       let me check the current code...    |
| ✓Fix Tests         |                                           |
|                     |  [System] UserList-Core was modified;     |
|  [+ New Topic]      |           .st files have been updated     |
|                     |  [AI] May I modify DBAdapter#connect?  　 |
|                     |  [Human] yes                              |
+---------------------+-------------------------------------------+

The core workflow:

1. Create a topic and select an ACP-compatible agent (Gemini CLI, Claude Code, OpenCode, etc.)
2. Type a request in the chat pane — mention code context with @ClassName or @ClassName>>method
3. The AI starts working (task decomposition, code changes, tests)
4. When the AI needs human judgment, it pauses and asks in the chat
5. Respond in plain text — the AI resumes
6. Topic status is always visible in the sidebar

Why pharo-agentic-browser?

• Native to the image — runs inside Pharo itself, with @ClassName code mentions and automatic tracking of package changes made by human and the agent, instead of bolting an external tool onto your workflow
• Mobile access — the Web UI is a browser-based interface served over WebSocket, so you can check on and steer topics from a phone or tablet, not just a desktop Pharo image
• Multi-agent orchestration — the Scripting DSL coordinates multiple coding agents across sequential and parallel steps, with automatic result injection between them, instead of driving one agent session at a time
• Agent-agnostic — works with any ACP-compatible agent (Claude Code, Gemini CLI, OpenCode, and others), so you aren't locked into a single vendor's CLI or IDE plugin
• Conversational human-in-the-loop — approvals happen as plain-text chat replies, not modal dialogs, so you can steer a topic without breaking flow

Features

• Multi-topic management — run multiple AI agent sessions in parallel
• Status tracking — per-topic state machine (initial → working → waitingForHuman → endTurn → goalAchieved)
• Human-in-the-loop — conversation-style approval flow (no modal dialogs)
• Agent-agnostic — works with any ACP-compatible agent
• Goal setting — set a completion condition; the AI works autonomously until the goal is achieved, then reports back
• Session persistence — topic list and state are saved to ab-topics.fuel via Fuel and survive image restarts
• Code mentions — type @ClassName or @ClassName>>methodName in chat to embed the Tonel source as ACP resources
• MCP server support — configure MCP servers via mcp.json; built-in Smalltalk MCP servers can be auto-merged
• Working directory management — per-topic working directory for better context; custom paths for existing projects
• Topic template — seed every new topic's working directory from topic-template, so coding-agent config (CLAUDE.md, AGENTS.md, .claude, .opencode, etc.) doesn't need to be set up per topic
• Multiple package prefixes — track multiple package families (e.g. #('ACP-*' 'BaselineOfACP')) per topic
• Image change watching — AbTopicRelatedPackagesWatcher monitors image changes, inserts system messages into chat, and asks for confirmation before synching packages
• Web UI — browser-based interface via WebSocket (docs/web-ui.md)
• Scripting API — headless DSL for coordinating multiple topics from code; supports sequential and parallel steps with automatic result injection (docs/scripting.md)

Requirements

• Pharo 12+
• pharo-acp
• SState
• PharoSmalltalkInteropServer
• At least one ACP-compatible agent installed (e.g. claude-agent-acp, gemini --acp)

Installation

In a Pharo image, open a Playground and evaluate:

Metacello new
    baseline: 'AgenticBrowser';
    repository: 'github://mumez/pharo-agentic-browser:main/src';
    load.

To also load the test suite:

Metacello new
    baseline: 'AgenticBrowser';
    repository: 'github://mumez/pharo-agentic-browser:main/src';
    load: 'Tests'.

Web UI (optional)

Load the server-side package:

Metacello new
    baseline: 'AgenticBrowser';
    repository: 'github://mumez/pharo-agentic-browser:main/src';
    load: 'WebUI'.

For client setup and full usage, see docs/web-ui.md.

Scripting (optional)

Load the Scripting package to create and coordinate multiple topics from code, with no UI:

Metacello new
    baseline: 'AgenticBrowser';
    repository: 'github://mumez/pharo-agentic-browser:main/src';
    load: 'Scripting'.

For the full DSL reference and examples, see docs/scripting.md.

Installing all packages

If you'd like to install all of these packages at once, you can use the 'all' group.

Metacello new
    baseline: 'AgenticBrowser';
    repository: 'github://mumez/pharo-agentic-browser:main/src';
    load: 'all'.

Usage

Open the browser window:

AgenticBrowser open.

1. Click + New Topic
2. Enter a title and select an agent
3. (Optional) Enter an existing project directory
4. Click Create — the topic appears in the left sidebar
5. Right-click the topic and choose Set Target Packages... to configure which packages to watch
6. Type a request and press Send — status changes to ❇️ (working)
7. When the AI requests permission, the Send button changes to Confirm and Cancel to Deny, and status shows ?
8. Click Confirm to approve or Deny to reject
9. The AI resumes; when finished, status changes to ● (endTurn)

You can also right-click a topic to Rename..., Delete, or Set Goal....

Note: The first message in each topic is automatically prefixed with /st-buddy to activate the Smalltalk buddy agent mode.

Code Mentions

In the chat input, you can reference Pharo classes or methods by prefixing them with @:

@QueryClass @DBAdapter>>connect please refactor this

When you send the message, AgenticBrowser resolves each mention to its Tonel source and attaches it as an ACP text resource alongside the prompt. The AI agent receives the exact code without any copy-paste.

You can also drag and drop directly from Pharo tools into the input field:

• Drag a class from the System Browser class list → inserts @ClassName
• Drag a method from the System Browser method list → inserts @ClassName>>methodName

Screen Captures

Click the [ ] button in the status bar to capture a screen area and attach it to your next message.

1. Click the button — the cursor changes to a crosshair
2. Drag to select the area you want to capture
3. A mention like @sc-20260528-001.png is inserted into the input field
4. Send — the PNG is attached to the prompt as an image resource

The file is saved to <agenticBrowserRoot>/screenshots/sc-YYYYMMDD-NNN.png. You can also reference a previously captured file manually by typing @sc-YYYYMMDD-NNN.png in the input field.

File Attachments

Click the + button in the status bar to attach any file from disk.

1. Click the button — a file selection dialog opens
2. Choose a file — a mention like [filename] is inserted into the input field
3. Send — the file's contents are attached to the prompt as a text resource

Deleting the [filename] mention text before sending removes the attachment. If the file's contents exceed AbSettings >> maxAttachmentSize (default: 5 MB), the attached text is truncated.

Topic Template

When a new topic's working directory is created, AgenticBrowser copies the contents of <agenticBrowserRoot>/topic-template into it.

By default this template holds a CLAUDE.md and AGENTS.md tailored for the smalltalk-dev plugin, generated the first time the template directory is accessed. You can replace these with your own customized versions.

You can also place coding-agent project config directories here, such as .claude or .opencode, containing skills, commands, and rules shared across topics. This saves you from reconfiguring the coding agent for every new topic.

Note: The template is only copied into working directories created under the AgenticBrowser root. It is not copied when you set a custom directory path pointing at an existing project.

Goal Setting

Right-click a topic and choose Set Goal... to enter a completion condition (e.g., all tests pass). AgenticBrowser sends a goal notification prompt to the AI:

Goal has been set: all tests pass. When the goal is achieved, summarize and
report in result-<topic-id>.md. Keep retrying until the goal is achieved.

The AI works autonomously. When it creates result-<topic-id>.md in the working directory, AgenticBrowser reads it, stores the result, and transitions the topic to ✓ (#goalAchieved). From that state, the topic can only be reset to initial (effectively archived).

Two hooks fire when a goal is achieved:

• Announcement — AbTopicGoalAchieved is announced via the topic's own announcer, carrying the topic and goal (AbTopicGoal). Subscribe with:

  topic announcer
      when: AbTopicGoalAchieved
      do: [:ann | Transcript crShow: ann topic title , ' achieved: ' , ann goal result].
  

• Callback block — register an optional block on the topic with whenGoalAchieved:. The block receives the AbTopicGoal as its argument (or takes zero arguments):

  topic whenGoalAchieved: [:goal | Transcript crShow: goal result].
  

Session Persistence

Topics are saved automatically to ab-topics.fuel in the AgenticBrowser root directory using Pharo's Fuel serializer. You can also save and restore manually:

AbTopicManager save.
AbTopicManager load.

MCP Servers

Place a mcp.json file in your AgenticBrowser root directory (default: <imageDir>/agentic-browser/mcp.json) to configure MCP servers passed to the agent on session start:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-server-package"],
      "env": {"API_KEY": "value"}
    }
  }
}

When AbSettings >> useDefaultMcpServers is true (the default), the built-in smalltalk-interop and smalltalk-validator MCP servers are automatically merged with your mcp.json entries. User entries take precedence over the defaults. Set useDefaultMcpServers to false to use only your mcp.json.

Image Change Watching

Watching starts automatically when a topic first connects (on the first Send).

Supported Agents

Any ACP compatible coding agent can be used. The following agents are available as presets in the New Topic dialog:

Strongly Recommended: Install the smalltalk-dev-plugin in your agent. It provides Smalltalk-aware skills and MCP servers that agents can use to work directly with Pharo inside the session.

Adding a Custom Agent

To add a custom agent, edit ab-settings.json directly in a text editor. Alternatively, from a Playground:

AbSettings default codingAgents: (AbSettings default codingAgents copyWith:
    {'name' -> 'my-agent'.
    'command' -> #('my-agent' '--acp')} asDictionary).
AbSettings save.

Package Structure

Architecture

State Machine (SState)

Each topic has an FSM with five states:

#initial ──promptSent──▶ #working ──permissionRequested──▶ #waitingForHuman
                             ▲                                      │
                             └──────────humanResponded──────────────┘
                             │
                          turnEnded
                             ▼
                          #endTurn ──promptSent──▶ #working
                             │
                          goalReached
                             ▼
                          #goalAchieved ──reset──▶ #initial

Human-in-the-Loop Approval

When the AI requests permission, AbTopicHandler#requestPermission: puts the UI into approval mode (Send button becomes Confirm, Cancel becomes Deny). When the user clicks a button, the UI returns to normal mode.

Goal Setting (AbTopicGoal)

AbTopicGoal holds the goal description, result text (once achieved), and an optional callback block. It manages the result file path (result-<topicId>.md in the working directory). After each end_turn, AbTopic>>checkGoalAchievement checks whether the file exists; if so, the topic transitions to #goalAchieved and fires an AbTopicGoalAchieved announcement.

Code Mentions (AbCodeMentionParser / AbCodeMentionEmbedder)

AbCodeMentionParser scans raw chat input for @Foo and @Foo>>bar tokens and returns AbCodeMention value objects. AbCodeMentionEmbedder resolves each mention to its Tonel source using TonelWriter and produces URL→content associations. AbChatPresenter calls both before sending and passes the resolved resources to AbTopic>>sendPrompt:withResources:.

MCP Servers (AbMcpServersLoader)

AbMcpServersLoader reads mcp.json from AbSettings>>defaultAgenticBrowserRootDirectory, optionally merges built-in Smalltalk server definitions (controlled by AbSettings>>useDefaultMcpServers), and returns an OrderedCollection of ACPMcpServer. AbTopicSession calls it on every connect and passes the result to the ACP session params (newSessionBy:, resumeSessionBy:, loadSessionBy:).

Working Directory (AbWorkingDirectory)

Each topic has a working directory at <imageDir>/agentic-browser/<safe-topic-name>-<uuid8>/. The UUID suffix ensures stability even if the topic title changes.
You can also set a custom working directory path when creating a topic from an existing project directory.

Package Change Watcher (AbTopicRelatedPackagesWatcher)

AbTopicRelatedPackagesWatcher subscribes to SystemAnnouncer for MethodAnnouncement and ClassAnnouncement. When a method or class is saved:

• If the package matches any of the topic's packagePrefixes, it inserts a message into the chat (e.g. "AgenticBrowser-Core was modified; .st files have been updated") and confirms exporting the package
• If the package does not match, it add the package to updatedExternalPackageNames. They can be moved to tracked packages by 'Apply Updated External Packages' menu
• Changes during import are suppressed to avoid re-export loops

Settings

Settings are managed by AbSettings and persisted as ab-settings.json in the AgenticBrowser root directory. There are two levels: global defaults and per-topic overrides.

Global Settings

Open the Settings dialog from the Settings… menu in the browser window's menu bar. The dialog covers timeout values, timeout options, and MCP server preferences.

Per-Topic Settings

Each topic starts with a copy of the global settings. Right-click a topic in the sidebar and choose Edit Settings... to open the settings dialog for that topic alone.

Per-topic settings are persisted with the topic via Fuel when AbTopicManager save is called.

Skills

• skills/ — Agent skills for coding agents, for use by anyone with AgenticBrowser installed (e.g. ab-scripting-feature-dev, which generates and runs Scripting DSL orchestrations for feature development in your own project)

Related Projects

• pharo-acp — ACP client library for Pharo
• SState — Simple state machine library for Pharo
• PharoSmalltalkInteropServer — HTTP API server for Pharo package import/export/test
• smalltalk-dev-plugin — AI agents plugin providing Smalltalk-aware skills and slash commands

License

MIT