pihme / fregoli

Fregoli

A web application an agent can rewrite while it is running: capabilities are Cordis plugins mounted and unmounted in a live Node process.

CI · releases tagged fregoli/vX.Y.Z

#What it is

Fregoli is a web application an agent can rewrite while it is running. Instead of editing files and restarting the process, capabilities are Cordis plugins that are mounted and unmounted in a live Node process. The name comes from Leopoldo Fregoli (1867–1936): one performer, many appearances, no restart of the show.

On start you get a canvas on port 8080 and a small figure in the lower right: that figure is the chat. You describe what you want, and the page stays as it is while the agent works. When the reply is finished and there is something new to show, the page updates once and the chat is still there. Chat goes to the Grok CLI over ACP when grok is on PATH, otherwise to an in-process stub. Grok receives an MCP server that lets it observe the page, load and unload plugins, highlight elements and wait for the user to click.

The three questions

Fregoli is built around three questions:

  1. What if you no longer have to buy software off the shelf, but can build it yourself?
  2. What if software is not delivered fully baked, but can change constantly?
  3. What if AI does not just build the software, but can then also take on tasks inside that software that deterministic software cannot do?

The CLI is always fregoli in full, never freg.

#Current status

Last updated 7 November 2026 · main@e5f530a

All 44 automated tests pass on the main branch in continuous integration, which runs them in a pinned Nix environment. They show that Fregoli starts with its web page, agent connection and chat panel, and that chat messages reach a connected agent, or a built-in stand-in when none is available. While the agent works, the page stays as it is and updates once when the reply is finished. A failed send is shown, and a reply that repeats the previous one still appears, also after a server restart. Plugins can be loaded while the app runs, a broken one is refused, and the setup is kept in a settings file. The agent can read the live page, highlight elements and wait for the user to click one. The container image builds and serves its page. The latest release is fregoli/v1.0.0.

This is a first version: it works in principle but feels clunky, and the first reply is usually very long. The tests use a stand-in for the Grok command-line tool, so chat with the real Grok CLI is not covered. There is no login on the web page or its HTTP interface. The container image listens on all network interfaces, so it should only run where no untrusted machine can reach it. Running it inside Hermetarium is untested end to end, and releases are source archives only. Three issues are open, all planned work: a short silent film of a live edit, a look at free models for the agent, and a study of what fills the agent's context, so that replies get faster and a session stops growing with every turn.

#Key concepts

Cordis kernel

The kernel is Cordis (npm cordis). Every capability is a plugin, or “fiber”, that can be mounted and disposed at runtime.

Web plugin

HTTP on TCP 8080: the canvas, the assistant slot, a JSON API and the page bridge (DOM snapshot, highlight, user click).

Agent plugin

Spawns grok agent --always-approve stdio and speaks ACP. Falls back to a stub without grok. Unloading the plugin kills the child.

Assistant plugin

Lower-right chat panel behind a Helferlein figure, with a Point button. A separate plugin: replaceable and removable. Starting with --assistant forces the stock one for that start.

Loader gate

Mounts extra plugins from fregoli.json or POST /load. A plugin whose apply fails does not become ACTIVE and does not replace the canvas.

MCP tools for Grok

src/mcp.ts: list_plugins, load_plugin, unload_plugin, observe_page (the tab on screen plus nextCanvas), highlight, wait_click, reload_page (held until the reply finishes).

#Working with the agent

Click the figure to open the chat, type what you want and send. One line shows what the agent is doing, such as Working (read file); the same step again shows a count. The page you are looking at stays as it is. When the reply is finished and the page has changed, the figure turns away, the page loads the result once, and the chat stays open on the latest message. If sending fails, the chat says so and Send works again. A reply that runs longer than five minutes stops and is not tried again on its own.

Point shows which part of the page you mean. With the chat open, press Point at the top of the panel, move over the page and click the element. A chip above the message box names it, such as Button · Save, and your message then begins with Pointed at Button “Save”. Escape or Point again backs out; the chat itself cannot be pointed at.

This is an MVP: it works in principle, and the first reply is usually very long. Making it faster is planned for 2.0 in #36.

#Getting started

Needs Node 22+. For a real agent, the Grok CLI on PATH (authenticated via Grok CLI login or XAI_API_KEY).

git clone https://github.com/pihme/fregoli.git
cd fregoli
npm ci
npx tsx src/cli.ts              # http://127.0.0.1:8080/
npx tsx src/cli.ts --assistant  # force the stock assistant UI
npx tsx src/cli.ts --version
npm link                        # puts `fregoli` on PATH; uses the tsx in this checkout

Run the tests (the merge gate):

npm test

Container image (Hermetarium is a recommended habitat, not a requirement):

docker build -t fregoli:local --build-arg FREGOLI_VERSION="$(git describe --tags --match 'fregoli/v*' 2>/dev/null || echo dev)" .
docker run --rm -p 8080:8080 fregoli:local

The image listens on 0.0.0.0:8080 and includes the shipped plugins, fregoli.json and the Fregoli skill. A local process listens on 127.0.0.1 unless you pass --host or set FREGOLI_HOST.

Saved config lives in fregoli.json in the process working directory:

{ "assistant": true, "plugins": [] }

The product contract is in the specification.

#HTTP API

Base http://127.0.0.1:8080. Selected endpoints:

PathMethodWhat
/GETCanvas + assistant slot
/chatPOST{"text":"…"} → reply (ACP or stub)
/pluginsGETMounted fibers
/loadPOST{"file":"/abs/path/plugin.ts"}
/unloadPOST{"name":"draw"}
/observeGETThe tab on screen plus nextCanvas, the canvas served on the next load
/bridge/*GET/POSTPage bridge: snapshots, highlight, actions, reload, wait for user click

#Architecture & layout

Node process · Cordis kernelBrowsercanvas + assistantweb pluginHTTP :8080 · canvas · page bridgeassistant pluginlower-right chatagent pluginACP clientloaderfregoli.json · POST /loadcanvas pluginsshipped · runtimeMCP serversrc/mcp.tsGrok CLIgrok agent … stdioHTTPACPspawnsHTTP API

The agent plugin spawns grok agent --always-approve stdio and passes the MCP server spec in ACP session/new; Grok starts src/mcp.ts with FREGOLI_URL pointing back at this process. Shipped plugins (plugins/shipped/) mount at boot; runtime plugins via fregoli.json or POST /load.

PathContents
src/cli.ts, src/boot.ts, src/kernel.tsCLI entry, boot sequence, Cordis context
src/loader.ts, src/config.tsPlugin loader/unloader, fregoli.json handling
src/mcp.tsMCP server handed to Grok
src/plugins/{web,agent,assistant}/Boot plugins (tracked)
plugins/shipped/Canvas plugins shipped with the repo; every *.ts mounts at boot
plugins/runtime/Plugins the agent writes at runtime (gitignored)
.grok/skills/fregoli-app/Grok skill: how to change the running app
tests/node:test suites run via tsx
docs/images/Diagrams used in the readme and on this site