Clax for Pi

Publish HTML pages from Pi to a local Clax server, view them in a browser, and get the comments people leave on them back into the session.

Pi's extension API has no MCP support, so this extension calls the Clax daemon's REST API directly and registers the tools in process. The tools take the same arguments and return the same JSON as the Clax MCP tools.

Install

From a clone of the Clax repository (nothing needs building), run pi install <clone>/plugins/pi. Or run just install in the clone: it builds and installs clax into ~/.cargo/bin and runs clax init, which pi installs this package from the copy built into the binary (~/.clax/marketplace/plugins/pi) and points it at that binary. The extension has no runtime dependencies beyond the modules Pi provides to extensions (@mariozechner/pi-coding-agent, typebox), so it needs no npm install.

The extension finds its binary by running the package's copy of the plugins' wrapper, scripts/ensure-clax.sh, so it runs the same clax as the other plugins: CLAX_BIN, else the bin setting in ~/.clax/config.toml (clax bin set <path>), else the Clax release the package pins, downloaded into ~/.clax/bin/<version>/ the first time the extension needs the daemon. PATH is never consulted. just dev pi loads it from the checkout instead, with -ne so an installed copy does not load twice (which turns off your other Pi extensions for that session too). status reports binary: the path it runs and that binary's version. clax doctor --agent pi checks the binary, the installed package, its skill, and the daemon's Pi sessions.

What it adds

• Forty-two tools: clax_publish, clax_read, clax_list, clax_delete, clax_open, clax_pin, clax_unpin, clax_tag, clax_tags, clax_fork, clax_asset_upload, clax_status, clax_comments_read, clax_comments_reply, clax_comments_resolve, clax_comments_handoff, clax_watch, clax_wait_for_feedback, clax_working, clax_draft, clax_git_remote, clax_ask, clax_where_to_ask, clax_connect_instance, clax_publish_public, and the data tools clax_db_get, clax_db_list, clax_db_query, clax_db_set, clax_db_update, clax_db_delete, clax_db_str_replace, clax_db_batch, and the report queue tools clax_queue_list, clax_queue_claim, clax_queue_renew, clax_queue_release, clax_queue_reply, clax_queue_resolve, clax_queue_get, clax_queue_fix, clax_queue_watch. Pi keeps every tool in one namespace, hence the prefix. Relative file paths resolve against the Pi session's working directory.
• On session start, the extension finds the daemon for $CLAX_HOME (default ~/.clax), starting it with clax serve when none is running, and registers the Pi session (harness pi, Pi's session ID, the working directory). Publishes are attributed to that session. When no daemon can be started then, the first tool call tries again. If the session is ended under the extension, the next tool call registers a new one. On session shutdown the session is ended. The registration names the repository and branch of the working directory, read from its files, which name the agent.
• Remote mode: on a machine connected to another person's Clax with clax connect (remote.json and remote.key in $CLAX_HOME, and CLAX_REMOTE not 0), the extension talks to that daemon instead and never starts a local one. Every request is signed with the machine's key, as the other clients sign them, and names the session with the secret its registration was answered, which the extension keeps in memory and in $CLAX_HOME/remote-sessions/pi-s-<Pi session ID>.json (0600) until the session ends. A comment's clip is fetched into $CLAX_HOME/remote-cache/clips/ and the payload names that file.
• The clax skill (skills/clax/SKILL.md): when to publish, the page contract, and the comment loop.
• The /clax command: /clax open [ID] opens the gallery or an artifact, /clax list lists artifacts, /clax status shows the daemon and session.

clax.dev and other hosted Clax instances

Not directly, yet. Pi has no built-in MCP support, and this extension talks to a daemon by its REST API with a local daemon's token or a clax connect machine key, so it cannot use a hosted Clax's agent token. Use it with a Clax on your machine and publish from there: sign that Clax in to clax.dev (clax remote add https://clax.dev, or press Publish to clax.dev on any artifact), then publish a page with Publish to clax.dev in the browser, clax push <ID>, or the clax_publish_public tool, which asks you first. Comments people leave on the public copy come back to the local page and reach Pi as any local comment does.

The comment loop

People comment on a page in the browser and send a thread to the agent with Send to agent or @agent. Pi has no hooks, so those comments reach the session in three ways:

• Tool results: every successful clax_* call except clax_wait_for_feedback gets the comments sent since the last call, in its JSON feedback array and as a trailing text block starting with --- and [clax] N comments sent to you:. A failed fetch leaves the result as it was.
• clax_wait_for_feedback: returns as soon as a comment arrives.
• Follow-up messages: once the session is registered, the extension long-polls the daemon (50 s per poll, pausing 5 s after a failed poll or one that came back empty in under a second) for comments on artifacts the session watches with replies on, and hands each batch to Pi with sendUserMessage(text, {deliverAs: "followUp"}). When Pi is idle this starts a turn at once; while it is working the message waits until the current work is done. While the agent is inside clax_wait_for_feedback, the daemon hands comments to the wait and answers these polls empty at once, so the loop pauses. The poll only finds a running daemon; it never starts one. It stops on session shutdown.

A comment handed over as a follow-up message counts as seen only once the agent reads, replies to, or resolves its thread; until then it is resent on a later tool result after two minutes, at most three times.

Tool failures are reported as error results holding {"error": {"code", "message", ...}, "feedback": []}; when the daemon cannot be reached the code is daemon_unreachable and log names <CLAX_HOME>/logs/daemon.log.

Environment

• CLAX_HOME: the Clax home (default ~/.clax).
• CLAX_BIN: the clax binary to run, ahead of the bin setting and the pinned release; when set it must be a usable clax.
• CLAX_NO_OPEN: when set, open returns the URL without starting a browser.

Developing

just dev pi starts Pi on a fresh build with this extension and its skill loaded from the checkout, on a separate home and port; "Developing Clax" in the top-level README has the details. just install updates your everyday install.

just pi-test installs the dev dependencies and runs the typecheck and the tests, which start a real daemon with cargo run. scripts/smoke-pi.sh (manual) runs pi -p with only this extension loaded against scratch Pi and Clax homes, and checks that the session was registered.