_{Just a silly example of live app modification}

Pi owns the providers, models, sessions, history, tools, commands, and extensions. It reasons, writes code, and runs tools.

Livecraft sits on top of it.

Whatever Pi can send, Livecraft can receive. Whatever Pi can read, Livecraft can send.

You configure Pi as usual. Livecraft just calls it instead of keeping a second provider or model configuration.

Pi already provides an exceptional experience in the terminal, no doubt about it.

Sadly, a terminal can't (yet) do it all. A browser is handy for the parts that benefit from space and interactivity: graphs, small buttons, and advanced interactions (images, videos, 3D?).

For example, I embedded a Session Analysis widget that lets you monitor usage, token consumption, and cost in real time, as well as identify the costliest tool calls based on multiple criteria.

"But I can do that in the terminal"

Yeah, you sure can! Now what about representing all that data in a graph and clicking on any point to jump back to the corresponding turn or tool call in the conversation so you can analyze it further?

"Technically I can still do that in a terminal"

What about displaying fully interactive HTML pages directly in the tool result block? SVGs? Rendered Markdown? What about spawning confetti when a task ends?

"Meh"

Well, maybe Livecraft isn't for you then :3

The whole point is that the UI lives in this repository and is hot-reloaded by Vite while all Pi sessions stay alive, so the model can change it while you use it. When something in the interface is annoying, the usual loop is:

1. Ask the model to change it
2. Watch it happen live
3. Use it from now on

All documentation in the project (except this README) is primarily meant to be read by agents (you can still read it, dw). Start with the documentation index.

You need Node.js 24+, npm, and a configured Pi. Native Windows, Linux, and WSL are supported. On Windows, Pi itself requires Bash; Git for Windows is the simplest source, or configure shellPath in ~/.pi/agent/settings.json. A global npm installation should expose pi.cmd through PATH; Livecraft resolves its package entry point and never sends Pi arguments through cmd.exe.

Fork the repository, then run:

git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
cd YOUR-REPOSITORY

npm install
npm run dev # this allows hot reloading

To launch Livecraft from any directory, link this checkout once in each shell environment you use:

npm link
pi-livecraft

WSL/Linux and native Windows have separate global npm paths: run npm link from a checkout visible to each environment. The command always runs this repository's npm run dev.

Open http://127.0.0.1:5173 and you should see Livecraft.

Everything was designed to be easily navigable, extensible, and craftable by an AI agent, so you can try ideas quickly, just like with Pi!

These are systems already present that you can build on top of or completely replace. You can also build totally new ones. Once the fork is done, it's YOUR Livecraft

• Workspaces and parallel sessions: create, switch, reopen, and monitor Pi sessions across several workspaces. Running and newly completed sessions remain visible in the list wherever you are

• A Pi-native composer: send text and images, use slash commands, stop a request, choose the models, thinking levels, and saved prompts exposed by Pi, and steer or queue follow-ups while Pi is working

• Isolated prompts: run a one-off Pi prompt from a widget, command, or anywhere really. By default it uses the cheapest available model in your Pi installation, returns one answer, and does not add anything to the active conversation

• Extension dialogs: handle Pi's standard select, confirm, input, and editor requests, plus structured questionnaires from Livecraft extensions

• Livecraft-specific Pi extensions: craft extensions meant to be loaded into Pi only when working with Livecraft, to improve your Livecraft's UX/UI.

• Live conversations: responses, activity, tool execution, usage, costs, errors, updates, notifications... I mean, everything Pi sends, Livecraft sees

• Enhanced tool call rendering: allow for complex (or simpler) tool call rendering. As an example, HTML, SVG, Markdown, and CSV will render directly, with the source still available and colorized with just a click

• Contextual chat message actions: build buttons on any tool call or session message. One example is the embedded copy input/output action available on all messages and tool call results

• Session analysis: real-time usage analysis of the session. All the data is shown as interactive graphs. Click any point to jump back to the corresponding turn or tool call in the session. This one is a very good example of the potential here!

• Todos: add tasks before you forget them while the session is running. Morph these todos into real sessions with a single click. They are persisted per workspace (I used this feature heavily while developing Livecraft)

• Git: review status, diffs, changed files, and unpushed commits; commit, push, reset, or revert without leaving the conversation

• Provider quotas: see OpenAI Codex and GitHub Copilot usage windows in one panel (I only use these, ahah. Feel free to add your provider.)

• Terminal: open an installed native Windows, Linux, or WSL terminal in the current workspace from the rail, palette, or a shortcut

• Editable color themes: start from Light or Dark, or build from either one. An agent can do it, but save your tokens and edit the theme manually. Choose a theme, then edit its 8 source colors; everything else will be derived from them. You now have your theme

• Command palette and editable shortcuts: commands share one registry. Sidebar widgets get their commands automatically. Use Alt+K to show the command palette

• Local preferences: conversation display, workspace restoration, shortcuts, terminal command, panel sizes, and widget state stay in the browser

• Flexible layout: don't like the side panels? **** them; you can do whatever you want

• Notifications: routine notices disappear on their own and errors remain until dismissed

Pi Livecraft's repository is a starting point. Forks are expected to drift away from upstream, and there is no requirement to keep them synchronized.

In fact, DO update the core and do your thing. Upstream won't change except for small bug fixes. No more features!

Use it for a while. When something gets in the way, ask the model to change it and keep the result if it helps :)

Some reasonable first changes to test it:

• turn a repeated prompt or workspace command into a one-click action;
• give an important Pi tool a presentation that matches its output;
• add a right-rail widget for context you repeatedly hunt down;
• combine messages, forms, and actions into a recurring workflow;
• remove every feature you do not use;
• add something objectively unnecessary but personally delightful

Upstream stays conservative and mostly takes bug fixes. New workflows and product choices should live in the forks that need them.

The list above shows what exists. The guides below show where a change belongs and which focused check covers it.

The documentation index links the feature contracts, backend capabilities, widgets, and focused checks behind each surface.

Everything runs locally!

The browser renders the application. A local backend handles Livecraft features and carries Pi's events back to the page.

A separate manager starts and owns the Pi processes, so refreshing the browser or restarting the backend does not close them, because the manager lives outside the Vite hot reload domain.

flowchart LR
    subgraph Livecraft["Pi Livecraft"]
        direction LR
        Browser(["React browser"])
        Backend["Local backend"]
        Manager["Pi process manager"]
        Supervisor["Manager supervisor"]

        Browser <-->|"HTTP + SSE"| Backend
        Backend <-->|"Local JSON Lines"| Manager
        Supervisor -.->|"guarded lifecycle"| Manager
    end

    Manager <-->|"Pi public RPC"| Pi(["Pi<br/><code>pi --mode rpc</code>"])

Vite can update the frontend while a session stays open. The backend can also restart without closing active Pi processes.

If manager code changes, Livecraft shows a persistent notice and waits. The manager is not replaced until you ask and Pi is idle. Sessions closed during the replacement remain available in history. That's the trick. Cool, right? :)

The manager talks to Pi through its public RPC protocol. Livecraft extensions use Pi's public extension API so you're in good hands.

Git, todos, terminal launching, and browser preferences remain local Livecraft features. There is no Livecraft extension system, so you can break it all!

Read the architecture guide for the full flow. Read the manager lifecycle guide if you want to mess with the manager's process supervision.

When these extensions are installed and configured in Pi, Livecraft already contains the logic and UI for them, since they are the apples to my Pi (holy...)

• @nerisma/pi-agents: adds specialized agents with focused prompts, restricted tool sets, and isolated delegation. When Pi exposes /agent, Livecraft displays an agent picker.
• @nerisma/pi-auto-title: names sessions from their first prompt, which makes parallel histories much easier to scan.

Just to be clear, these are NOT mandatory. Pi Livecraft can work with anything; these are just my preferences, and they work by default :)

npm run typecheck
npm run lint
npm test
npm run build

Pi provides the agent runtime, sessions, tools, and extension model. It does the actual work; Livecraft is a local web interface built around it.

Focused bug reports and bug fixes are welcome upstream. Workflow features belong in the forks that need them. Do your thing!

Pi Livecraft is available under the MIT License.