Ultimate

[!NOTE]

A personal project, shared as inspiration. Ultimate is not a library or a product with users to support. Copy

what you like, fork it, do whatever you want with it. I don't review issues or pull requests, and I change things as

I go, fundamental ones included, without migration paths or regard for anyone building on top. Whether that works

for you is your call. See CONTRIBUTING.md.

A coding agent you specialize for the project you work on. Start it in your repository and it is Pi's coding agent in a web UI. Then build what this project needs into it, such as custom tools, panels, subagents, skills, or whole screens, and keep them in the project's .ultimate/ folder. Everyone who works on the project boots the same specialized agent, and it still feels familiar in every project, because the core is always the same.

Built on Pi Durable: the conversation, every tool call, and every subagent are committed to SQLite before anything is shown, so Ultimate can rewrite its own UI, extensions, and core without losing its place.

How to use it

• Specialize it for your project. Working on a web shop? Ask Ultimate for what makes work on that shop easier: a

• Commit them with the project. .ultimate/ is part of the repository, so everyone who opens the project gets the

• One familiar core everywhere. The conversation, Pi's tools, the model and login, and the way it works are the same

• Everything on, switch off what you don't need. A fresh Ultimate is Pi's coding agent with every built-in:

• A forest of conversation trees. Each root keeps a read-only context: branch intents, latest conversation abstracts,

• You can build whole applications in it, too. A surface is a full-screen app next to the docked agent.

• Lean and malleable. Like Pi and Pi Durable, the core stays as small as possible and everything else is

Start

By default you get Pi's coding agent in a web UI: read, write, edit, bash, codemode, and browser debugging tools, with the conversation, model and thinking controls, login, and footer, plus every other built-in building block.

Needs Node 26 and pnpm, and a pi login (Ultimate shares ~/.pi/agent: credentials, models, settings; personal skills and instructions go in ~/.ultimate/skills/ and ~/.ultimate/AGENTS.md). The screenshot and browser tools need a Chromium: /usr/bin/chromium, Google Chrome, Playwright's cached Chromium, or ULTIMATE_CHROMIUM=.

pnpm install
pnpm start          # Ultimate on its own repository; opens http://127.0.0.1:4747
pnpm link --global  # once, in this clone, to get the ultimate command
cd ~/Projects/app && ultimate
pnpm cli            # emergency terminal agent when the UI, server or database is broken

• No pi login yet? Open the command palette (Ctrl+K, ⌘K on macOS) → "Log in to a provider". Logins are shared

• First start on a machine shows Get ready: log in to a provider and choose a model. Continue opens @ultimate,

• A folder with its own .ultimate/ asks once: its setup or your global one. Its extensions, agents, and skills

• The Extensions panel (right panel, or Ctrl+K → "Extensions…") lists every extension and turns it on or off

• On another machine: ssh -L 4747:127.0.0.1:4747 , then open http://127.0.0.1:4747. Ultimate only listens on

• When everything is broken: pnpm cli in the clone (or ultimate --cli in a project) opens Pi's terminal agent

• Several machines, one project: join the cloud on each (⌘K → Join cloud fleet), back the project up from the

Terminal status

pnpm start / ultimate shows a compact live terminal dashboard: the public URL, supervisor/core lifecycle, core generation and PID, embedded Vite readiness, registered extension services, and the last event. Routine Vite/HMR output updates the dashboard instead of scrolling; warnings and errors remain in scrollback. Redirected output is plain text with no dashboard escape sequences. Detailed, timestamped JSON lines (including routine output and diagnostics) are appended to /supervisor.log; this file is not automatically rotated. A log-write failure warns once and does not stop supervision.

Services are status reports, not separate processes. Automations reports ready · durable scheduler when the harness opens; this does not claim that all runs are idle. Process topology and durable scheduling are unchanged. Supervisor changes require a manual stop and restart with pnpm start; a core swap does not reload bin/.

In your project

ultimate [dir] [--port N] [--no-open] starts Ultimate for a project (default: the current directory) and opens it as its own chromeless window in a Chrome-family browser (http://ultimate.localhost:), or a tab when there is none. Running it again for a running project opens another window instead. Ultimate's own source stays in the clone; the tools and the conversation work in your project.

• .ultimate/ in your project tailors it: extensions/, agents/, skills/, and an optional settings.json

• State lives in ~/.ultimate/projects/-/ (ULTIMATE_HOME overrides it), so each project keeps its

• Actions let an extension's UI call its server code: export const actions = { … } in server.ts, then

Building blocks

Built-ins live in the clone's extensions/, and every one is on by default; tailscale exposes Ultimate only to your own Tailscale login. Each folder's README describes the building block.

Turn them off in ~/.ultimate/settings.json for this machine or /.ultimate/settings.json for this project:

{ "extensions": { "disable": ["tailscale", "claude-code"] } }

See discovery and settings for precedence, enabling extensions, project trust and live updates.

Surfaces

A surface is a full-screen app made of extensions: the Agent surface is the conversation you start with; another can be anything you build. Switch in the title bar, ⌘K → "Switch to …", or mod+1…9. The agent stays docked on every surface, and the choice is durable: reloads, other tabs, and restarts land on the same view. documents provides the Documents tab; surface UI contributions themselves work without it.

What to try

• Start a new project with Set up with @ultimate on Start here (or Continue on the first-run Get ready page).

• Ask it anything about this repository; watch tool calls, diffs, and thinking stream in.
• "Build a surface for …" — a whole app with its UI, server actions, and the agent docked beside it; switch to it while

• "Build a small extension that …" — it reads extensions/README.md, writes

• "Take a screenshot of yourself and tell me what looks off" — it can see and drive its own UI.
• "Delegate to a worker: …" — subagents run as their own conversations (Agents tab, open #id).
• "Use codemode to check which of your extensions failed to load" — one sandboxed script over its own runtime.
• Change something in server/ and ask it to restart: a new process boots and type-checks next to the old one, and the

• Press Ctrl+Alt+B for the right panel: To-dos, Tasks, Activity, Automations (schedules and watching scripts),

• Use @ultimate's row at the top of the sidebar (on phones, the top-bar @ultimate button) to ask for work, explore an idea, or start an independent line of work. Its messages and questions appear in its transcript, with answer cards beneath questions; open questions also wait at the top of the right panel's To-dos tab until you answer or dismiss them, and @ultimate's mark turns amber meanwhile.

How it is put together

AGENTS.md is Ultimate's guide to itself: which path holds what, how each layer reloads, and the conventions. Everything that is not core plumbing is an extension folder with a server.ts (agent) and/or web.tsx (UI) facet; extensions/README.md is the guide to writing them.

Develop

pnpm dev                          # the server alone, without the supervisor
pnpm check                        # format, lint, types
pnpm test                         # fast in-process tests on scripted model responses
pnpm test:e2e                     # tests that spawn real supervisors and instances

License

MIT.