Fregoli

#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 an assistant chat in the lower right. 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 CLI is always fregoli in full, never freg.

#Current status

Last updated 26 September 2026 · main@95f9711

All 25 automated tests pass on the main branch in continuous integration, and the same suite passes on a local machine apart from the Docker build, which needs Docker. The tests show that Fregoli starts with its web page, agent connection and chat panel, and that chat messages reach a connected agent, or a simple built-in stand-in when none is available. New plugins can be loaded while the app runs and change the page without a restart, and a broken plugin is refused without disturbing what is already there. The agent can read the live page, highlight elements and wait for the user to click one. The latest release is fregoli/v0.3.2.

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, and the app always listens on port 8080 on the local machine only. Running it inside Hermetarium is recommended but untested end to end. Releases are source archives only. Seven issues are open. Three concern the container: the server is likely unreachable from outside it, the image leaves out some files, and a network tool Hermetarium needs is unverified. Two are small mismatches between the docs and the command line. One notes that the settings file is never written, so plugins loaded at runtime are gone after a restart. One notes that the spec says the agent's tool server is started differently than the code does it.

#Key concepts

#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

Run the tests (the merge gate):

npm test

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

docker build -t fregoli:local .
docker run --rm -p 8080:8080 fregoli:local

Note: the server currently listens on 127.0.0.1 inside the container, so the published port is likely unreachable from the host (see Current status).

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

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

Full CLI and HTTP reference: usage guide.

#HTTP API

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

#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.