Ernie

A desktop app for working with Prime Agent, built with Zenbu.js.

Give your agents a name and a face, choose a working folder, and start a conversation. Ernie explores how an agent can help choose and adapt the interface around your work.

Ernie is alpha software. Expect bugs and changes as the app develops.

Explore Ernie · Read the introduction

Choose a name and character for the agent you work with.

See the agent’s runs and subagents alongside the conversation. Here, Theo is researching electricity trends with two subagents.

Ernie uses the Prime Agent daemon for agent execution. Adapting the interface through Zenbu plugins is an ongoing experiment; the website’s interactive demos show a few possible arrangements.

Read the guide that matches the change:

• Architecture: state ownership, component boundaries, and scenario integration
• Data structures: contract relationships, identifiers, synchronization, and state lifetime
• UI: visual direction, interaction requirements, and adverse states
• Workflow: browser iteration and isolated scenarios
• Verification: test boundaries and unresolved findings
• Code map: concepts linked to implementation

The guides distinguish current implementation from accepted product direction and verification requirements.

Install dependencies with Nub:

nub install

nub run dev

This starts one windowless Electron main process because Zenbu 0.6.0 requires Electron to host its service graph. It does not create an Electron renderer window. A stable loopback gateway opens the production Ernie renderer in the normal browser at http://127.0.0.1:4310.

The browser uses the real Zenbu RPC, events, database replica, service hot reload, and shared Prime Agent daemon. Renderer edits use Vite HMR without restarting the service host.

Development state is isolated under .zenbu/dev/browser/:

.zenbu/dev/browser/
├── db/
├── electron-user-data/
├── owner.json
└── runtime.json

Ernie connects to your existing Prime Agent daemon on startup. If it is absent, Ernie starts your installed Prime Agent executable. Installation and upgrades remain your responsibility. Quitting Ernie leaves the daemon running. See daemon ownership.

Use a separate profile and port for concurrent worktrees or agents:

ERNIE_DEV_PROFILE=review-42 ERNIE_DEV_PORT=4410 nub run dev

To read sessions from another Prime Agent supervisor, provide its absolute socket path explicitly:

ERNIE_PRIME_AGENT_SOCKET=/absolute/path/to/prime-agent.sock nub run dev

The socket remains externally owned, including when Ernie starts its daemon. Ernie checks compatibility before loading sessions and never replaces an incompatible daemon.

If a GUI launch cannot find your installation, select its executable explicitly:

ERNIE_PRIME_AGENT_EXECUTABLE=/absolute/path/to/prime-agent nub run dev

Ernie searches absolute PATH entries and common user/system bin directories, excluding project node_modules. It never runs a package installer. Not installed, Starting, Incompatible, and failure states appear in the sidebar and footer. Use Retry connection after fixing your installation or endpoint. Startup waits at most 30 seconds after launch; ordinary reconnects stop after three attempts.

Set ERNIE_PRIME_AGENT_START_DAEMON=0 for a connect-only endpoint. Disposable restart fixtures use this setting to prevent launching a user installation.

For disposable checks, set upstream PRIME_AGENT_CODING_AGENT_DIR to a fresh temporary directory and choose a socket inside that directory. Do not point fixtures at your normal agent directory.

A profile has one owner. A second owner fails instead of deleting or sharing live state. Runtime metadata is local, mode 0600, ignored by Git, and never prints the Zenbu authentication token.

# Real Zenbu and Prime Agent host without opening a browser
nub run dev:server

# Attach the stable browser gateway to an existing dev:server
nub run dev:web

# Real visible Electron application with isolated desktop development state
nub run dev:desktop

dev:web never starts a mock or silently creates a backend. It fails when the selected profile has no live dev:server.

Use the cheapest proof that crosses the boundary changed by the work:

# Type generation, typecheck, boundaries, integration tests, and staged source build
nub run check

# Daemon boundary integration tests
nub run test:integration

# Real browser, Zenbu RPC, Prime Agent session creation, and Vite HMR
nub run test:integration:browser

# Real Electron renderer startup without Cypress
nub run test:desktop-smoke

# Full isolated Electron user journey; reserve for integration milestones
nub run test:e2e

Open Cypress interactively only when debugging a browser or Electron journey:

nub run test:integration:browser:open
nub run test:e2e:open

The browser integration and desktop smoke commands use temporary database, agent, socket, and Electron profile directories, then remove them on exit.

Run nub run lint:unused to check unused files, exports, and dependencies with Knip. knip.json declares Zenbu service discovery, injected views, Nub scripts, and browser entrypoints. Cypress and cloud tools have separate package scopes.

Knip exceptions cover Zenbu's Electron builder, cloud CLI tools installed for shell scripts, and system binaries. Prime Agent companion packages resolve transitively through pinned overrides.

Validate the Konsistent configuration schema separately from auditing the codebase:

nub run konsistent validate
nub run konsistent

The audit reports structural outliers and may exit non-zero until those findings are reviewed. It is intentionally not part of nub run check.

Thin T3 Code and Effect snapshots live under the ignored repos/ directory. Refresh both pinned snapshots with:

nub run repos:sync

repos.lock.json pins each remote commit and sparse path set. The sync uses shallow, filtered checkouts and removes Git metadata from the result. To use an existing local checkout as a faster source, create the ignored repos.local.json file:

{
  "sources": {
    "t3code": "/absolute/path/to/t3code"
  }
}

The committed lock never contains machine-specific paths, so another machine can reproduce the snapshots from their pinned remotes.

Prepare an explicit candidate, review and commit it, then build or publish through the release workflow:

nub run release:prepare 0.2.1
nub run release:check
# After review, verification, release notes, and commit:
nub run release:build
nub run release:preview

Use release:prod for a production release. Both publication commands use ad-hoc signing without Developer ID or notarization. release:build:signed is available separately when official Apple credentials are configured. Both release types use the dedicated release source branch.

Ernie is licensed under the MIT License.