Skip to content

Supported first path

Build the Pear Desktop baseline.

One linear walkthrough: install the public CLI, configure your assistant, run a local-first app, make a change, and verify persistence.

Preview boundary

This path verifies scaffolding and local persistence. Real local-inference requirements are still being measured, so this page does not pretend that downloading or loading a model is part of the baseline.

  1. 1

    Check the required tools

    The desktop generator needs Node.js 20 or newer and npm. The generated project installs Electron and pear-runtime locally. An AI coding assistant is optional; a Personal Node, wallet, and local model are not required for this baseline.

    bash
    $ node --version
npm --version
  2. 2

    Install the published CLI

    Install the exact public version used by this guide, then confirm which binary your shell resolves. The repository is preparing 0.4.0-beta.1; this guide stays on the published release until that candidate is verified on the registry.

    bash
    $ npm install -g @unstoppable-stack/cli@0.3.0
us --version
  3. 3

    Configure an assistant workspace

    The init flow creates a workspace and writes guidance for Claude Code, Cursor, OpenCode, Codex, or no assistant. Open the generated folder in your chosen tool after this step.

    bash
    $ us init coffee-workspace
cd coffee-workspace
  4. 4

    Create the desktop app

    This command creates coffee-notes as a child folder. Base P2P networking and local key-value storage are included, so obsolete p2p or kv-storage feature flags are not needed.

    bash
    $ us scaffold app -p pear-desktop -n coffee-notes
  5. 5

    Install and run

    Run these commands from the generated application folder. A Pear window should open. Dependency or runtime errors belong to this step; a model is not downloading in the baseline.

    bash
    $ cd coffee-notes
npm install
npm run dev
  6. 6

    Make one observable change

    Ask your coding assistant to make a small UI change, then reload the app and confirm it. This verifies that the generated project guidance is being used before you add another runtime capability.

    Prompt for your assistant

    In the generated Pear Desktop app, show saved entries newest first and add a visible “Newest first” label. Keep storage and peer networking in the worker. Run the existing checks when finished.

  7. 7

    Verify local persistence

    Create an entry, close the app normally, start it again, and confirm the entry remains. Disconnecting from the network must not prevent local reads or writes; it only pauses peer discovery and replication.

  8. 8

    Add local AI or another peer separately

    After the baseline works, consult the local AI and connection guides. Local AI requires a model download and compatible hardware. Personal Node pairing may require explicit approval and is never part of first-run success.

Recognize, diagnose, recover

Troubleshooting

us: command not found
Check
Run npm prefix -g and check that its bin directory is on PATH.
Recover
Open a new terminal after installation or add the reported bin directory to PATH.
Desktop dependencies are missing
Check
Run npm ls --depth=0 inside coffee-notes.
Recover
Run npm install in that generated folder and address the first meaningful npm error.
The package version is unavailable
Check
Run npm view @unstoppable-stack/cli versions --json.
Recover
Use the documented public version 0.3.0; do not substitute the repository candidate.
npm install fails
Check
Read the first error above the final npm summary.
Recover
Resolve that specific network, permission, or native dependency error, then rerun npm install in coffee-notes.
The app window does not open
Check
Run us doctor -p pear-desktop and confirm npm run dev is being run inside coffee-notes.
Recover
Fix the failed doctor check, then restart the dev command.
A local model does not download or load
Check
Confirm free disk space and read the first QVAC/model error.
Recover
Return to the base scaffold, or choose a smaller compatible model before retrying the optional local-ai path.
Personal Node is not found
Check
Confirm the Node is running and that the app is requesting supported capabilities.
Recover
Continue device-only, or review pairing approval and network reachability; the app should not fail locally.

Baseline working?

Read the architecture and support boundaries before enabling local AI, multi-writer data, or Personal Node sync.

Continue to docs