documentation

run Ernie, follow a task through the system, control the visible interface, and understand what the first macOS release contains.

v0.1.0 Apple silicon private alpha ad-hoc signed

start Ernie locally

development currently targets macOS. the repository uses Nub 0.7.5 for dependency installation, scripts, and Node.js execution.

before installation

use an Apple silicon Mac for the packaged release path.
install Nub 0.7.5.
make sure the local agentation path in package.json points to your Agentation package.

install and run

nub install
nub run dev

the development command builds the Electron main process and renderer, starts Vite at 127.0.0.1:5173, and opens Ernie. stop the process with Control+C.

check before changing code

run nub run check. it covers TypeScript, source lint, package boundaries, and the test suite.

understand the workspace model

Ernie organizes work around durable identities. the sidebar is a projection of repository, worktree, and Prime Agent session state.

repository

the stable project root. adding or removing it changes Ernie’s navigation, not the repository on disk.

worktree

a linked Git workspace nested below its repository. branch and worktree identity stay visible together.

Agent session

durable work owned by Prime Agent. Ernie renders its messages, tools, queued work, and recursively spawned Agents.

start a task

choose a repository or linked worktree.
open a new Agent draft.
select the model, reasoning effort, and RLM depth.
send the first non-empty task to create the durable session.
continue, queue follow-up work, or reopen the session later.

follow a request through Ernie

Prime Agent owns execution and durable session truth. Ernie owns the desktop shell, boundary parsing, navigation projection, and native lifecycle.

rendererReact presents repositories, sessions, and the composer.
renderer clienttyped requests and feed events are parsed at the boundary.
Electron IPCplain data crosses the sandboxed preload boundary.
Ernie daemonsession feeds, caches, and the Prime Agent adapter live here.
Prime Agentthe daemon socket owns execution and durable sessions.

renderer → Electron IPC → Ernie daemon → Prime Agent adapter → daemon socket

why the boundary matters

the renderer does not receive arbitrary daemon JSON and guess what it means. requests, results, and feed events are parsed before UI code consumes them. expected failures remain data; broken invariants remain defects.

control the visible interface

the local CLI changes visible Ernie state. it cannot read, create, stop, or modify Prime Agent sessions.

discover the current surface

nub run cli -- --help
nub run cli -- ui capabilities

ui capabilities returns a versioned JSON manifest with capability identifiers, availability, commands, and input limits.

window, theme, and sidebar

nub run cli -- ui focus
nub run cli -- ui theme dark
nub run cli -- ui theme light
nub run cli -- ui sidebar show
nub run cli -- ui sidebar hide
nub run cli -- ui sidebar width 320

sidebar width accepts values from 192 through 384 pixels. Ernie must be running for discovery and interface-changing commands.

status	meaning	stream
`0`	help or command success	stdout
`1`	runtime, availability, or protocol failure	stderr
`2`	invalid command or arguments	stderr

local security

the CLI uses ~/Library/Application Support/Ernie/ui-control.sock. Ernie creates it with owner-only permissions and accepts only its bounded, versioned UI protocol.

work with built-in plugins

Ernie’s versioned plugin host ships with Browser, React Grab, and Agentation. current plugins are trusted built-in code.

activation and cleanup

view plugins activate when their workbench view is requested.
application-wide tools activate at startup.
providers activate before consumers that require their services.
cleanup runs once in reverse acquisition order.
a failed activation rolls back staged services and contributions.

Browser boundary

Browser uses Electron WebContentsView with context isolation, sandboxing, no Node.js integration, and denied page permission requests. navigation accepts only HTTP and HTTPS.

plugins are not an extension marketplace

spatial composition controls lifecycle and service visibility. it does not make hostile JavaScript safe. external downloads and untrusted plugin execution remain out of scope.

build and release the mac app

Ernie packages an Apple silicon .app inside a ZIP. the archive contains the renderer, Electron main process, and installed Prime Agent runtime dependencies.

build locally

nub run check
nub run package:mac

the archive and its SHA-256 file appear in .build/release/. without a signing identity, the packager uses ad-hoc signing for development and private testing.

publish from GitHub Actions

gh workflow run release.yml \
  -f tag=v0.1.0 \
  -f prerelease=true

the tag must equal v plus the version in package.json. the workflow installs locked dependencies, runs the complete checks, packages the app, uploads build evidence, and creates the GitHub release.

identified distribution

a public download needs a Developer ID Application certificate and App Store Connect API credentials. the complete credential set enables hardened-runtime signing, notarization, ticket stapling, and final archive creation.

view v0.1.0 release details (repository access required) ↗

recover from common failures

the CLI says Ernie is unavailable

keep nub run dev running, then retry nub run cli -- ui capabilities. help commands work without the app; live commands do not.

dependency installation cannot find Agentation

inspect the agentation file: dependency in package.json. it must point to the local Agentation package before nub install.

macOS warns about the package

an ad-hoc build is not an identified-developer download. use it only for private testing, or configure the full signing and notarization path.

the release workflow rejects the tag

make the requested tag exactly match v plus the package.json version. partial Apple credentials also fail intentionally.

know what Ernie is not

Ernie is not a model runtime; Prime Agent owns execution.
the UI CLI is not a general session-control channel.
the plugin host is not a sandbox for untrusted extensions.
v0.1.0 is not a notarized public macOS download.
the task-shaped interface remains an experiment.

Ernie stays intentionally small. it is a learning lab for making agent-runtime and interface boundaries visible enough to observe, test, and explain.