Apps

An app is a small program that runs in a window of the desktop and has an icon of its own there. Some apps are built into exe, a set of extra ones comes with the installer, and any other is a folder holding two files. That makes an app a good thing to ask a coding agent to build for you.

What apps are for

For you:

• Tools on the desktop. Notes, a to-do list, tide charts, a proofreader, a dictionary: each opens in a window beside your VMs and terminals, and fills the screen on a phone.
• Stickies. A note can stand on the desk by itself, as Mac OS 9's Stickies did, and looks as one of its notes did: press the pushpin at a note's foot in Notes, and it becomes a small window in the note's colour that stays where you put it, on every desk that syncs. Drag it by its thin title bar, size it by the box on its corner or by its edges, press the box at the bar's right end or double-click the bar to collapse it, and press the box at its left end to put the note back in Notes alone. Each is a page of Notes, so what you type there is in Notes too.
• Data that stays yours. Each app keeps its data in private storage on this machine, and joined desks sync it.
• Windows that keep up. When an app's files change, its open windows reload by themselves once you are not using them.
• An app made to order. When no app does what you want, ask an agent for one. It is two files in a folder, and nothing has to be built or restarted.
• Whole programs on the desk. A program that runs beside exe can bring apps of its own: Planet and Writer publish a site, and Easel sets Claude painters to work.

For a coding agent, such as Claude Code or Codex:

• A whole app is a small job. An app is a folder with an app.json and an index.html: plain HTML, CSS and JavaScript.
• No build and no restart. The daemon serves the folder straight from disk, and each edit reaches the open windows by itself.
• Storage is provided. An app saves its own data through /v1/apps/<Name>/data/<file>, and files you should see go to the Workspace.
• The conventions are written down. The exe-apps repository holds the extra apps and, in its README.md and CLAUDE.md, how an app is laid out, how it talks to the desktop and how it saves.

Open an app

Double-click an app's icon on the desktop; on a phone, tap it. The factory desktop menu lists the same apps under Apps, and a line of your own there can open one; see Desktop context menu.

An app also opens in a browser tab of its own. Add /apps/ to the desktop's address: the page lists every app this node has as an icon. Click one, and it fills the tab; on a phone it opens as it does in the desktop's phone window. The page uses the API token you gave the desktop in that browser.

The built-in apps

These are part of exe itself, and each has a chapter of its own.

Built-in app IDs use lowercase names; their display titles come from app.json. Three of them had other IDs once (Mac OS 9, Hub, BluePencil). Older links and saved settings still work, and existing app data keeps its original storage and sync namespace.

The extra apps

The installer offers a set of extra apps: Notes, Paint, Ping, Tides, Todo, Weather and World Clock, from exe-apps. Say yes and they go into ~/.exe/apps. Say no and Extras brings them later.

An update brings their new versions, except for an app you edited or removed; see Updating.

Ping

Ping, one of the extra apps, watches how fast the network reaches the places you care about, the way SmokePing does. Every five minutes it sends twenty pings to each address on its list and graphs what came back.

• For you: see at a glance whether a server, your router or your provider is slow or drops packets, now and over the last year.
• SmokePing's graphs. RRDtool draws them from files in SmokePing's own layout, so they look and read as SmokePing's do.
• For an agent: the last round of every address is one HTTP call.

exe itself does the measuring, not the window: it goes on while the window is closed, and the files are in ~/.exe/ping. Each machine measures from where it stands, so joined desks do not share the list.

Ping needs two programs on the machine:

• RRDtool, which keeps and draws the numbers: sudo apt install rrdtool on Debian and Ubuntu, brew install rrdtool on a Mac. Until it is there, the window says so and nothing is measured.
• fping, which sends the pings as SmokePing sends them: sudo apt install fping or brew install fping. Without it, Ping uses the system's ping, one process for each address.

Ping looks for both at every round, so after you install one, it starts without a restart.

Watch an address

• Add: type an IP address or a host name in the field at the top, and press Return or Add. Its first twenty pings go out at once; after that it is measured with the others, every five minutes on the clock.
• The row shows the name and the address, the median time of the last round, and how many of the twenty pings were lost. The square before the name is in SmokePing's colour for that loss.
• Rename or move: click the row to open it, change Name or Address, and press Return. A new address keeps the history.
• Remove: click × twice. The history goes with it.

Read the graphs

A closed row shows the last 10 hours: the median as a blue line in a band of its spread. An open row shows SmokePing's four graphs: the last 3 hours, 30 hours, 10 days and 360 days.

• The smoke is each round's twenty pings in order. The darker the grey, the nearer the median.
• The median is the line through the smoke, in the colour of the round's loss: green for none, blues and purples for a few, red for 11 to 19 of the 20. When all 20 are lost, nothing is drawn.
• The scale goes a fifth past the highest median of the span. One slow ping does not flatten the rest: it runs off the top.
• Zoom: drag across one of the four graphs, and it shows the span you dragged over. Back returns it to its own span.

In a window under 680 pixels wide, a phone's too, the legend puts its figures two to a line, so each graph fits the window's width.

Ping for an agent

Extras

Four things add to exe and are not part of it: the extra apps, Planet, Easel and Projects. Extras turns each on and off. Open it with Extras… on the Apps card of Help → Welcome….

It has a step for each extra and a last one that makes the changes:

1. Extra Apps, Planet, Easel, Projects. Each page says what the extra is and how it stands on this machine, and has one check box. Tick it to have the extra on this desktop, clear it to take it off.
2. Review. What will change, extra by extra. Nothing has changed until you press Apply here. The desktop's icons follow by themselves.

What turning an extra on does depends on where it comes from:

Turning Planet, Easel or Projects off changes only exe's configuration. The program's files stay, and its daemon keeps running until you stop it.

Planet, Easel and Projects are programs of their own, built from their source. While one is not on this machine its check box is grey, and the page gives a line to hand a coding agent, such as the one in the Claude Code window, which installs it. If the program is here and exe did not find it, type its folder and press Find.

An agent turns an extra on with POST /v1/extras/<name> and {"on": true}, where the name is apps, planet, easel or projects; GET /v1/extras says how each stands.

Where an app lives

Icons beyond the built-ins are desktop apps: folders in ~/.exe/apps, each just an app.json plus an index.html, served straight from disk. The folder's name is the app's ID.

apps_dirs in ~/.exe/config.json names more folders to look in. It is on the Daemon tab of Configuration; see Configuration. That is how a program beside exe adds its apps.

When two apps have the same name, the one in ~/.exe/apps wins over one in apps_dirs, and either wins over a built-in app.

Have an agent build an app

1. Tell an agent that works on this machine what the app should do. The Claude Code and Codex windows are such agents.
2. Have it make a folder for the app in ~/.exe/apps, with an app.json and an index.html in it.
3. Choose File → Refresh. The new app's icon appears on the desktop.
4. Open the app. From then on, each change the agent makes shows in the open window by itself.

The extra apps in the same folder are worked examples, and exe-apps holds the conventions.

An app.json looks like this:

{
  "title": "Tides",
  "icon": "icon.svg",
  "window": { "width": 620, "height": 420, "grow": true }
}

title is the name you see, and without one the folder's name is used. icon is a picture in the folder. window is the size the window opens at, with grow true when the app draws a resize corner of its own.

An app worth reading while the daemon cannot be reached says so with offline. A device that has had the desktop open over HTTPS then keeps a copy, and the alert shown when the daemon is not answering offers the app. "offline": true keeps the app's own files. To keep what it shows as well, name it:

"offline": {
  "keep": ["/v1/apps/Reader/data/list.json"],
  "fixed": ["/v1/svc/reader/files/"],
  "wanted": "/v1/svc/reader/wanted"
}

• keep lists whole addresses. Each is asked of the daemon as always and its last answer is kept. When the daemon does not answer, the app gets the kept answer, with the time it was kept in the X-Exe-Kept header, in milliseconds. That header is how the app knows to say it is showing a copy and to stop offering changes.
• fixed lists the starts of addresses whose content never changes, such as files named by their hash. One is kept the first time it is asked for, and answered from the copy after that.
• wanted is an address that answers a JSON list of fixed addresses, written relative to itself, to fetch ahead of time.

An address has to be the app's own folder or data, a service's (/v1/svc/…) or a shared /platinum/ file; any other is left out.

Where an app keeps its data

Each app gets private storage under ~/.exe/appdata, in a folder of its own, plus the shared Workspace. The private storage is for the app's own state, at most 100 MB a file. The Workspace is for files you want to see and use elsewhere; see Workspace and files.

Joined desks sync app data; see Joining desks together. The lists that Notes, Todo, World Clock and Weather keep, and Blue Pencil's drafts, merge record by record, so edits made on two desks at once both survive. Any other file syncs whole.

An open window keeps up with its app

When the app's files change, on this desk or while a tablet slept, each open window of it reloads once you are not using it:

• At once in a tab you are not looking at.
• After a few quiet seconds for a closed window, which is hidden and still loaded.
• After half a minute without a key or a click for a window on screen.
• Never while it holds words you have typed and not saved.

The window comes back on the file it last had open.

Saves are guarded too: a window still on older code cannot take back a note, a to-do or a field that newer ones wrote.

Writer and Planet

Two apps come with exe-planet, the site builder that runs beside exe. Its apps folder goes in apps_dirs, and its daemon is the service planet: Extras sets both.

Writer edits any Markdown file in the Workspace: the text on the left, the page it makes on the right, saved as you type. An edit made elsewhere reloads a clean file and leaves an unsaved one alone.

Planet is three columns like the Mac app:

• Your sites.
• The chosen site's posts, pages and drafts, as a list view.
• The chosen article's built page.

New Post and Edit open the article in Writer; right-click a site or an article for the rest.

A to-do list in a post (- [ ] words) can be ticked in that page: click an item's box and its line in the Markdown flips. This works on a site that wears Paper, Platinum or Sepia.

A post can be read in more than one language. Beside its index.md, write the post in another language as index.ja.md (or index.en.md, index.zh-hans.md): a title: line in its front matter, then the text. Each language becomes a page of its own. A reader whose browser is in that language is taken to it, and ?lang=ja on any address of the site asks for it by name. On a site that wears Paper or Platinum a post shows the languages it can be read in beside its date, and the home page, the archive and a tag list each post under the reader's title. In the Planet window, click a language in the page to see that page; Edit then opens that language's file.

Publish a Planet site

Publish… is where a site leaves this node. Everything on the sheet is off until you turn it on.

• On the web. Expose the site under a name in your domain. It gets the same route, DNS record and tunnel rule a VM's Expose makes; see Publishing to the web.
• On IPFS. Send every changed build to IPFS under a key this node keeps.
• Both. Each new CID then also goes to the name's DNSLink record (_dnslink.<name>), so IPFS gateways find the site by its name too.

Export… bundles the site with its key for another node.

Announce posts on a hub

The same sheet can put an exposed site on an exe hub; see The Hub.

Turn on Announce and give the hub's address. This node invites the site's own key there; the site's key is also its IPNS name and a Solana address.

From then on each post you publish, which is a draft moved into Posts, announces itself on the hub under the site's name, with a link back.

Under the post on your site, a Reply window and a Replies window show the answers it gets, live. A reader replies with a Solana wallet that meets the hub's gate, signing a message and never a transaction.

Posts published before you turned Announce on stay put. Right-click one and choose Announce on Hub to send it.

Easel

Easel comes with exe-easel, which runs Claude painters at an oil paint simulator beside exe. Its apps folder goes in apps_dirs, and its daemon is the service easel: Extras sets both.

A studio is a folder holding an easel, a box of tubes and a brief. New Studio… makes one, and Start Painter… sets a Claude painter to work there. The painter is Claude Code with Opus 5.5 unless you pick another model, and it is given nothing but the easel.

The painter mixes its paint from the tubes and lays it on with simulated brushes, a chunk of Lua at a time. It looks at the canvas between chunks and keeps a journal, and it stops when it is happy with the picture.

The window follows the painter live, a tab for each view:

When a painter is done, the picture finishes itself a couple of minutes later: it dries right through, is varnished and lets its paint crack. A Replay movie of it being painted again follows. Both are made again whenever the painting changes.

Finish… and Replay… are there only to redo them another way: no varnish, a longer movie. Save to Workspace puts the picture and the movie in the Workspace's Easel folder.

Projects

Projects is a list of what is to be done in each of your projects, kept where you and your coding agents can both read and write it. A bug you spot, an idea, a loose end an agent mentions at the end of a task: each becomes an issue, with an address such as EXE-12 that names it for good, so "fix EXE-12" is a whole instruction. You can hand an issue to Claude Code or Codex from its menu, see on the issue while an agent is at work on it, and read the agent's plan and report under it afterwards. Projects and coding agents, below, says how.

Projects comes with exe-projects, an issue tracker that runs beside exe. Its apps folder goes in apps_dirs, and its daemon is the service projects: Extras sets both.

The window has three columns: your projects on the left, a project's issues in the middle and the chosen issue on the right. A project has a short name in capitals, such as EXE, and its issues are numbered from one: EXE-12 names the same issue for good.

Right-click an issue for what can be done to it: close or reopen it, edit it, Star it, copy its address, or send it to a coding agent. A starred issue wears a yellow star where the list has its dot, and on the issue's own line, and Unstar takes it off. The pop-up at the top right lists the open, the closed, all or the starred issues.

A file attached to an issue is kept in IPFS, which takes Kubo on this machine; without it everything else works. Anyone who learns such a file's address can fetch it, so attach nothing private.

Click a picture under an issue to see it in a picture window. When the issue has more than one, Left and Right show the one before and the one after, or a sideways swipe on a phone, and the window's top line says which it is, 2 of 5.

Projects and coding agents

An issue holds what an agent needs to start: what is wanted, the discussion so far and any screenshots. An agent can also write back, so its plan, its report and the commit that did the work end up on the issue, where you will look for them, not in a conversation that has scrolled away.

The work goes round like this:

1. Write it down. File an issue. If it is about something on screen, attach a screenshot.
2. Hand it over. Right-click the issue and choose Send to Claude Code or Send to Codex. The agent's window opens, or comes forward, with a new session in the project's working directory. The session's first message is the whole issue with its comments, and a note that asks the agent to read the project's instructions, do the work, check it and report.
3. Watch it work. While the agent's turn runs, a line under the issue's title says so: a green dot, the agent, how long it has been at work, and the session's name. The line goes when the turn ends.
4. Read what came back. An agent that has been told about the tracker comments its plan as a checklist, ticks it as it goes, reports, and closes the issue with its commit. What it found on the way can become an issue of its own.
5. Go round again. If something is off, reopen the issue, say what in a comment and send it again. The new session starts with the whole discussion, the last report included.

What to know about handing an issue over:

• The working directory. Send to Claude Code opens the session in the folder named in the project's sheet: Project…, the Directory field. The items are grey for a project without one, or whose folder is not on this machine.
• Which agents. The menu lists the agents exe has found on this machine, the same ones that have windows on the desktop. A second session takes tmux; without it the items are grey.
• The agent's own questions stay. It signs in, asks whether to trust a folder it has not worked in, and asks for permissions as it always does.
• Size. An issue and its discussion of more than 64 KiB are refused, with their size, not cut short.
• A blank start. Right-click a project and choose Open in Claude Code for a new session in its folder with no first message.

The line on an issue counts every session in the Claude Code and Codex windows whose latest instruction that names an issue names this one, whether the menu sent it or you typed it, as in fix EXE-12. A session started in a plain Terminal window does not show.

Let an agent read and write issues

An agent works in the tracker with the exe-projects command, from its own shell:

exe-projects help lists the rest. The command stays in the folder exe-projects was built in, so give an agent its full path.

An agent writes under a name of its own when EXE_PROJECTS_KEY names an ed25519 key of its own, a PEM file like the one a hub key is kept in. It says what to call it once, with exe-projects whoami -name "…". Without a key, what it writes is signed as this node, which is you.

An agent learns about the tracker from the project's instructions: CLAUDE.md for Claude Code, AGENTS.md for Codex. A few lines are enough:

Issues for this project are in Projects. The command is
~/exe-projects/exe-projects; `help` lists what it does.
Read an issue with `show EXE-12`.
Found something outside your task? File it with
`new . "Title" -m "What you saw"` and carry on.
Before you start an issue, comment your plan on it as a
checklist. When you finish, tick the checklist, report
what you did, and close the issue with the commit.

Without lines like these, an agent sent an issue still does the work, but reports only in its own conversation.