Fregoli
A web application an agent can rewrite while it is running: capabilities are Cordis plugins mounted and unmounted in a live Node process.
· 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:
- What if you no longer have to buy software off the shelf, but can build it yourself?
- What if software is not delivered fully baked, but can change constantly?
- 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 checkoutRun the tests (the merge gate):
npm testContainer 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:localThe 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:
| Path | Method | What |
|---|---|---|
/ | GET | Canvas + assistant slot |
/chat | POST | {"text":"…"} → reply (ACP or stub) |
/plugins | GET | Mounted fibers |
/load | POST | {"file":"/abs/path/plugin.ts"} |
/unload | POST | {"name":"draw"} |
/observe | GET | The tab on screen plus nextCanvas, the canvas served on the next load |
/bridge/* | GET/POST | Page bridge: snapshots, highlight, actions, reload, wait for user click |
#Architecture & layout
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.
| Path | Contents |
|---|---|
src/cli.ts, src/boot.ts, src/kernel.ts | CLI entry, boot sequence, Cordis context |
src/loader.ts, src/config.ts | Plugin loader/unloader, fregoli.json handling |
src/mcp.ts | MCP 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 |