Get started

Build and change your first desktop app

Create an app, save a note, prove it survives a restart, and change the saved data.

Content reviewed 21 October 2026

Follow this page from start to finish for a small desktop app with local Hyperbee storage. You will use the CLI directly; an assistant is optional. No model download is needed for this tutorial.

Before you start

Use a desktop with Node.js 22.17+ and npm. Installation needs internet access and downloads Electron, Pear runtime and native dependencies. Start in a parent directory where you can create a new folder named notes-workspace. The desktop scaffold is a developer preview; platform and packaged-release acceptance are separate checks.

Create and launch the app

Check tools and install the CLI

Check Node first, then install the exact CLI version used by these docs. Keep the version output if you need help.

bash

node --version
npm --version
npm install -g @unstoppable-stack/cli@0.4.0-beta.3
us --version
us doctor -p pear-desktop

Create the workspace and app

Run these in your chosen parent directory. init creates the workspace; scaffold creates the runnable notes-app child. For generated assistant guidance, replace none with claude, codex, cursor or opencode.

bash

us init notes-workspace --assistant none --no-install
cd notes-workspace
us scaffold app -p pear-desktop -n notes-app

Start from the app directory

The desktop window should show KV Storage with Key, Value, Save and Fetch controls. Keep this terminal open to see worker errors. If it only prints a workspace message, you are one directory too high.

bash

cd notes-app
npm install
npm run dev

Save and fetch a note

Write a value

In KV Storage, enter note:welcome in Key and Hello from my desktop in Value. Click Save. Expect Saved followed by the key.

Read it back

Leave Key as note:welcome and click Fetch. The result should contain Hello from my desktop. Fetch a different key such as note:missing to see the not found result.

Prove persistence

Close the app normally. From the same notes-app directory, run npm run dev again, enter note:welcome and click Fetch. The inputs start empty; the stored value should still exist.

Check offline use

With dependencies already installed, disconnect external networking and repeat Save and Fetch with note:offline. Close and reopen the same app and Fetch again. Local storage should work; peer discovery needs connectivity. Reconnect when finished.

Change the value you save

Close the app. Open app/index.js inside notes-app and find the kv-save click handler. Replace its existing sendToWorker call below. Keep the other handler lines, including the key/value input reads.

// Existing line inside the Save handler:
sendToWorker({ type: 'db-put', key, value })

// Replace that line with:
sendToWorker({
  type: 'db-put',
  key,
  value: { text: value, kind: 'note' }
})

The worker already accepts JSON values. This change makes newly saved records objects; existing string records remain strings until you save over their keys. Storage stays in worker.js and the UI continues to use the existing bridge.

Run the changed app

Launch again, save note:structured with Value Hello, then Fetch that key.

bash

npm run dev

Check the new shape

The fetched JSON should match the object below. Restart and Fetch again to confirm the object persists. Fetch your original note:welcome too; it should retain its original string unless you overwrote it.

json

{ "text": "Hello", "kind": "note" }

Choose your next change

Understand the Save path

Trace the UI, bridge and worker handlers before adding another command.

Connect two peers

Run an isolated notes demo for scoped RPC and replication, then choose the right sharing API.

Add local AI

Generate a separate AI starter and validate model loading, streaming and cancellation.

Something failed?

Find diagnostics for the command, window, storage, peers or model.

Need help? Report an issue with your CLI version, platform, command and first relevant error.