A menu bar agent: a transparent, floating chat panel built with Tauri 2, React 19, TypeScript, and the Nessa UI design system.
The window has no titlebar and no Dock icon. It lives behind the menu bar item — click it to summon the panel, click again to dismiss it, or press ⌘⇧A from anywhere. Summoning it hands the caret straight to the composer. The tab strip doubles as the titlebar — the gaps around the tabs drag the window; everything else lives in the tray menu.
It opens in the lower right of whichever screen it is summoned on, the way
Nessa's panel does — a 420pt column filling the work area's height by default,
both configurable (see Settings). A panel shorter than the screen
sits on the bottom edge rather than hanging from the top. The frame is reapplied
on every show, so moving between displays re-fits it rather than stranding it
(anchor_to_edge in src-tauri/src/panel.rs).
On Linux the same panel is a floating window. There is no menu bar extra to
hang from, so it opens on launch, stays on the taskbar, and still summons from
the system tray and Ctrl+Shift+A when those exist. Frost is CSS
backdrop-filter rather than an NSVisualEffectView. The webview is pinned
the same way as on macOS so a resize does not jitter the composer.
OS-specific window behaviour is not scattered through main. It lives in
src-tauri/src/platform/ — a Host trait with one
implementation per OS, injected by current() — and in
src/host/ on the shell.
- The iMessage-style chat surface —
ChatMessage/ChatBubble/ChatMessageReceipt/ChatTypingIndicatorfrom Nessa UI: sent bubbles right, received left, typing dots while the agent thinks, a streamed reveal as the reply arrives. - The Markdown pill composer —
PillComposer/PillComposerRowwithChatComposerMarkdownEditor: headings, lists, links, and code blocks with a language picker and syntax highlighting. Enter (or Mod+Enter) submits; Shift+Enter adds a block. The voice icon remains in place while typing. Three rendered lines (two newline breaks) reveal an expand control; Minimize or Escape returns to the compact composer. Large pastes (500+ characters) become pasted-text pills. Click a draft or sent pill to expand the Pasted text viewer; it shows the content with Markdown formatting while preserving the original text for sending. Ordered text/pasted parts stay with each conversation's draft and user turns; the backend receives their concatenated text, including the complete pasted payload. Drafts remain in-memory and do not survive an app restart. Voice and stop controls retain their existing runtime limitations. - The agent's face —
RandomAvatar, a deterministic generative avatar painted from the seed"nessa". The app icon is the same painting, rasterized (see Regenerating the icon). - Tabs —
ChatTabs, one per conversation. Each carries its ownRandomAvatar, painted from the tab's id, and a busy dot while it is mid-reply. A conversation is named after its opening line. Transcripts, phases and drafts belong to the conversation, not to the panel: a reply keeps arriving in a background tab, and switching tabs mid-sentence does not carry the sentence into someone else's thread. - Two surfaces — the tray menu's Transparent item switches between the
frosted surface, which blurs whatever the panel was summoned over, and the
clear one, which removes the panel entirely so only the bubbles and the pill
hang over the desktop. The frontend owns the choice and remembers it
(src/panel/adapters/surface.ts); the tray item only requests a
toggle, and its check mark is reflected back from
set_frosted. - Server-backed conversations — the conversation tabs in
src/conversation/retain local drafts while@nessa/clientcreates, reads, sends, steers, and controls server-owned conversations. On launch the panel opens astage=devsession against localnessa server(just server) and reads authorized gateway health.
pnpm install
just start # one terminal — server on ws://127.0.0.1:7421, then the panelDev and an installed Nessa run side by side. A packaged install keeps
127.0.0.1:7420 through a launchd background service that deliberately outlives
the app — quitting Nessa does not stop it, and killing its listener only makes
launchd start it again. So the dev stage listens on its own port, 7421. The one
stage → port table is
protocol/defaults/gateway-ports.json;
nessa-server, the desktop host, the frontend and the Vite proxy all read it,
and NESSA_PORT still overrides it for a single run. If something else is
holding the dev port, just start names the owner instead of killing it.
That is the whole setup from a clone. just start (and just server on its
own) runs nessa server --provision-local, which creates the dev namespace's
owner credential at $HOME/.nessa/owner.token, the panel's credential at
$HOME/.nessa/dev/auth/surfaces/nessa-panel.token, and the MCP credential at
$HOME/.nessa/dev/auth/surfaces/nessa-mcp.token when they are absent. It never
replaces credentials that already exist, so restarting the server does not
invalidate a token you are using. No signup, no account.
nessa call METHOD --params JSON sends one gateway method on that signed-in
session and prints the handler's JSON. nessa mcp serves the same methods as
MCP tools, using the nessa-mcp credential. That credential's default grants
are server.read, conversation.read, and conversation.write. Cedar on the
gateway still decides each call. The catalog and the methods it leaves out are
described in protocol/README.md.
Credentials are not enough to chat, so the same loop also names an agent.
A packaged install gets one from its bundle; a checkout has to say where its own
pieces are, and the server is deliberately not allowed to go looking for
crates/. So just server first runs
scripts/dev-agent-config.mjs, which writes an
agent block into $HOME/.nessa/dev/config.json pointing at this checkout's
Claude ACP harness, crates/nessa-sdk/data/models.json, the Node running the
dev loop, a workspace at $HOME/.nessa/dev/workspaces/default, and
target/debug/nessa-mcp when it has been built. An agent block that is
already there is never touched, merged, or repaired — the only thing a later run
does with someone's own configuration is say so when its executables have gone
missing.
The harness itself is not vendored. On a fresh clone the script says so and the gateway still starts; install it once with:
(cd crates/nessa-sdk/harnesses/claude-acp && npm ci --omit=dev)Nothing here ever blocks the dev loop: anything missing is printed with the
command that fixes it, and the gateway starts without an agent rather than not
at all. docs/guides/gateway-chat.md documents the same file for a server you
configure by hand.
Use two terminals instead if you prefer (just server, then just dev). A
server you run yourself — nessa server without --provision-local — provisions
nothing; use the offline nessa auth commands and choose your own token paths.
See local authentication for that, and
the ADR for scoped clients,
environment isolation, and owner recovery.
If the panel says no chat credential has been provisioned, the local server is
not the one that started it: run just server in that same namespace
(NESSA_DATA_DIR, NESSA_STAGE, NESSA_INSTANCE must match).
just is the entry (justfile). just
lists recipes. just server runs the WebSocket control plane. just dev is
tauri dev when a display is available, the browser UI (just web) when it
is not. just release is the shipping installer for prod; pass another
named stage as its first argument, such as just release alpha. pnpm app
resolves one dev stage for Vite and the host. The window controls no-op in the browser
(see src/host/window.ts).
Install just with the platform's package manager (apt install just,
brew install just, winget install --id Casey.Just --exact).
The server and auth library need Rust 1.89+ (embedded Cedar). Ubuntu's packaged
rustc is often 1.83; install via rustup. rust-toolchain.toml
pins stable, so just dev and cargo test pick it without an extra env var.
Linux containers running agent processes need a reaping init: use Docker
--init, or run the owner under tini -s --. See the opt-in
process-cleanup acceptance harness for the
non-reaping failure and supported environment comparison.
Build packages on Debian/Ubuntu:
bash scripts/desktop/install-linux-build-deps.shThen just dev. The Linux recipe refuses to start the desktop app if those
packages are missing, and it disables WebKit's DMA-BUF renderer on a VNC or
software X server that has no DRM device. To force that path on a machine
that does have /dev/dri:
WEBKIT_DISABLE_DMABUF_RENDERER=1 WEBKIT_DISABLE_COMPOSITING_MODE=1 just devA testing-shaped .deb is just release prod fast. A shipping .deb is just release.
just dev is tauri dev. just release prod fast writes a .app (no dmg). just release
writes a .dmg.
Windows recipes in the justfile have not been run on a Windows machine yet:
just release prod fast and just release ask Tauri for nsis. The justfile uses
cmd.exe so Git's sh is not required. Please verify just dev, just release prod fast,
and just release there.
| Command | What it does |
|---|---|
just |
List recipes |
just server |
Local nessa server (stage=dev defaults) |
just dev |
Desktop app in dev mode (falls back to the browser UI with no display) |
just web |
The UI in a browser, no Tauri |
just release prod fast |
Testing-shaped prod release — slow opts off (.app / .deb / NSIS) |
just release |
Shipping bundle — fat LTO, stripped (.dmg / .deb / NSIS) |
just release alpha |
Shipping-shaped bundle whose UI and host both use alpha |
pnpm app |
tauri dev with one validated dev stage supplied to the UI and host |
pnpm app:build |
Build and verify the prod shipping bundle: the macOS app and disk image, or the Linux .deb (--stage alpha selects another named stage) |
pnpm desktop:smoke |
On Linux, build and drive a real embedded WebKitGTK window against an isolated gateway/provider |
pnpm frontend:check |
Run the complete frontend/client formatting, lint, protocol, docs, type, test, and build contract |
pnpm sdk:check |
Run SDK formatting, Clippy, tests, and warnings-denied Rustdoc |
pnpm check |
Run the same frontend, Rust crate, SDK, MCP, and desktop checks composed in CI |
pnpm check:changed --git |
Discover branch, working-tree and untracked changes against the merge-base with origin/main (or main) even in coding-agent shells; run their local checks, or pnpm check for empty, unavailable or unowned input. Required CI still runs every job |
pnpm typecheck |
tsc --noEmit |
pnpm ui:check |
Confirm the vendored UI matches nessa-ui-revision (offline, runs before typecheck, dev, build, test) |
pnpm ui:types |
Reconcile the vendored UI with nessa-ui-revision |
pnpm ui:paths |
Write tsconfig.json's paths from scripts/nessa-ui-paths.mjs, which owns them whole |
pnpm check:changed without arguments discovers Git changes in a terminal; in
non-interactive shells it reads file paths from stdin. An empty pipe selects the
full check. Use pnpm check:changed --plan --git to inspect the discovered plan
without running checks, or pass paths explicitly. --git cannot be mixed with paths.
A direct Cargo build embeds dist/; it never silently falls back to the Vite
development server. Build the matching frontend first, then build and launch the
ordinary debug executable:
VITE_NESSA_STAGE=ci pnpm build
NESSA_STAGE=ci cargo build -p nessa-app
NESSA_STAGE=ci target/debug/nessa-apppnpm app remains the hot-reload path and points the webview at Vite.
To preview the native desktop with the browser's sample conversations and approvals,
run VITE_NESSA_SAMPLE_WORKSPACE=1 pnpm app. This uses an in-memory workspace;
the option is accepted only by development builds in the dev or ci stage.
For a
focused Rust host test, disable the embedded production feature so a test does
not require dist/ and pass test-harness flags after --:
cargo test -p nessa-app --no-default-features launch::tests -- --test-threads=1The native window smoke requires Linux, tauri-driver 2.0.6,
WebKitWebDriver, and Xvfb on a headless machine:
xvfb-run --auto-servernum pnpm desktop:smokeIt launches the real WebKitGTK window, isolated gateway, and deterministic ACP
provider; verifies a connected render, message reply, and attachment tile; and
checks that every process exits. Its synthetic browser File drop exercises
the real page attachment and upload path, but not a physical OS drag event,
which the native host consumes. The local-auth workflow is configured to run
this proof on Linux. WKWebView has no corresponding WebDriver coverage on
macOS.
There is no settings UI yet, so settings.json under the app config directory
is the interface. Paths are stage-scoped (ADR 0005):
Nessa creates a missing settings file with private permissions and replaces updates atomically. Invalid JSON, invalid UTF-8, and other read failures use in-memory defaults without overwriting the original file.
| Stage | Location (macOS example) |
|---|---|
prod |
~/Library/Application Support/so.nessa.app/settings.json |
| any other stage | ~/Library/Application Support/so.nessa.app/<stage>/settings.json |
stage + NESSA_INSTANCE |
…/<stage>-<instance>/settings.json |
NESSA_STAGE selects the stage (debug builds default to dev, release to
prod when unset). NESSA_INSTANCE isolates worktrees/sandboxes on the same
stage. Only prod uses the bare directory.
The file is written with its defaults on first launch so the keys are
discoverable, and serde(default) fills in anything a later build adds or a
person deletes. A malformed file is reported and ignored rather than
overwritten — throwing away what someone was mid-way through typing is worse
than falling back.
{
"panel": {
"width": 420,
"height": null,
"minWidth": 420
},
"stopAgentsOnQuit": false
}| Key | Meaning |
|---|---|
panel.width |
The width the panel opens at. After that the window's own width wins, so a drag on the resize edge is not thrown away |
panel.height |
The height it opens at. null fills whatever the work area leaves once the menu bar and the Dock have taken theirs, and keeps re-filling it across displays |
panel.minWidth |
How narrow the resize edge may drag it |
stopAgentsOnQuit |
Whether quitting the desktop asks the registered gateway to close active agents; the gateway itself remains available |
A configured width below minWidth is a contradiction, so the minimum wins —
it is what the resize edge enforces anyway. Height has its own floor
(MIN_PANEL_HEIGHT, 320): a panel shorter than that has no transcript left.
The file is rewritten with the merged result on every load, so keys a later build adds appear in it without resetting the values already there.
Shortcuts live in a sibling shortcuts.json under the same stage-scoped
root (ADR 0004). The server owns
defaults (protocol/defaults/shortcuts.v1.json); the host caches them so
summon works before connect. Default summon is CmdOrCtrl+Shift+D. Focused tab
navigation uses CmdOrCtrl+Shift+H (previous) and CmdOrCtrl+Shift+L (next), on
desktop only, wrapping from either end to the other. These are configurable panel.previousTab and
panel.nextTab bindings. Existing valid shortcuts.json files are preserved
rather than merged with new defaults. Append the following entries to their
bindings array and restart the app to enable them for an existing configuration:
[
{ "keys": "CmdOrCtrl+Shift+H", "action": "panel.previousTab", "scope": "focused", "surface": "desktop" },
{ "keys": "CmdOrCtrl+Shift+L", "action": "panel.nextTab", "scope": "focused", "surface": "desktop" }
]The relative-tab defaults are desktop-only because Safari reserves Cmd+Shift+H for its home page. Browser bindings may be configured explicitly with a chord supported by the browser.
A shortcut
that will not parse, or that another app already owns, is reported and skipped
rather than fatal: the tray icon still opens the panel
(src-tauri/src/shortcut.rs). Legacy
toggleShortcut in settings.json is ignored.
If you already have a flat settings.json from before stage scoping and you
run a prod build, that file is still used. Non-prod stages start fresh under
their namespace (copy manually if you want to keep values).
decorations: false means macOS gives the window no resize border, so
resizable: true on its own leaves nothing to grab — which is why dragging the
edge did nothing. The panel therefore carries its own handle: a strip down the
left edge that calls startResizeDragging("West"). West only, because the panel
is pinned to the right of the screen and spans the work area's height, so width
is the one dimension it owns.
anchor_to_edge re-fits the panel on every show, and it deliberately keeps the
window's current size rather than resetting it to the configured one —
otherwise a resize would be discarded the next time the panel was dismissed. The
configured geometry is applied once, at startup, by apply_configured_size.
Every agent starts here rather than running git worktree by hand:
just worktree create add-something # branch + worktree, ready to build
just worktree isolate # migrate an existing shared-target checkout
just worktree clean # rebuild this checkout's app/server crates
just worktree list
just worktree remove add-something # the branch is keptThese commands use scripts/worktree.sh on macOS and Linux. After entering the
new checkout, run just release prod fast to build a fast release.
just worktree create starts the new branch from the locally known remote
default branch and does not configure that remote branch as its upstream. The
saved checkout may remain on any feature branch without leaking those commits
into new work. Creation does not fetch, so it remains usable offline; run
git fetch origin main first when the newest remote commit is required.
Each worktree owns its workspace target/. Cargo, Tauri, and scripts that run
target/debug/* therefore read artifacts produced from the same checkout as
their source. scripts/worktree-target.test.mjs enforces that boundary with two
worktrees containing divergent versions of the same package: after A builds,
B builds, and B runs, A's already-built executable must still report A.
The separation costs a target directory per worktree. sccache still shares
compiled dependencies across those directories when RUSTC_WRAPPER=sccache is
set, and pnpm hardlinks from its global store. just worktree clean runs the
package-scoped clean from the invoking checkout and refuses a symbolic target,
so it cannot empty another checkout's output. Before cleaning, it asks Cargo for
the effective target and proceeds only when that is this checkout's own
target/.
An explicit CARGO_TARGET_DIR still overrides Cargo's default and therefore
opts that command into the directory it names. Build-and-run scripts ask
cargo metadata for the effective directory, so they execute the artifact from
that same override instead of a stale checkout-local binary. Use a path unique
to the checkout when setting it during parallel work. The override selects where
builds and runs happen; it does not authorize just worktree clean to delete an
external or another checkout's target. Clean such an intentional target directly
from the process that owns it.
Worktrees made by the former recipe still have target/ linked to the original
clone. From each such checkout, run just worktree isolate once. It unlinks only
that exact former link, creates an empty local directory, and leaves the original
artifacts untouched. A link to any other path is refused for manual inspection.
New worktrees are created as siblings of this checkout
(../nessa-agent-<name>) with a local target directory from the start.
Claude Code makes worktrees of its own, for background agents and for subagents
declaring isolation: worktree.
.claude/settings.json configures
WorktreeCreate and WorktreeRemove hooks
pointing at ./scripts/worktree.sh claude-hook and claude-hook-remove. The
create hook gives these worktrees the same isolated target ownership as the
manual recipe.
Replacing Claude Code's creation means owing it the behaviour it would have had.
The WorktreeCreate payload carries exactly one field, name, and it is a
worktree slug — not a branch and not a path — so everything else is the
hook's job to match:
| What the hook does, and why | |
|---|---|
| Location | .claude/worktrees/<name>, where Claude Code puts its own, already gitignored. Deliberately not the sibling directory create uses. Those are people's worktrees, and the two naming schemes are not the same function — a slug may contain dots, a create name may not — so keeping the namespaces apart is what stops an agent being handed somebody's checkout to commit to |
| Branch | worktree-<name>, which is what Claude Code's own default names it |
| Base | The repository's default branch, which is what worktree.baseRef: "fresh" means. git worktree add -b with no start-point instead branches from whatever the clone is sitting on, so a clone parked on a feature branch would have given every agent that branch's commits. --no-track, so the agent's git push and git pull don't act on main |
Note that the documented input schema for WorktreeCreate lists path and
worktree_path as well. Claude Code 2.1.278 sends neither; only WorktreeRemove
carries worktree_path. The hook reads what is actually sent.
The remove hook is not optional. Claude Code's periodic sweep only removes
worktrees carrying a marker it writes itself, and one a hook created has none,
so without it every worktree made this way would stay on disk for ever — the
accumulation this exists to stop. It unlinks a legacy target link before removing
the directory, leaving the link destination untouched, and deletes the branch
only when the base already contains every commit on it. That last test is
merge-base --is-ancestor rather than git branch -d, because -d means
"merged into whatever this clone has checked out" and would refuse to tidy up an
empty worktree branch whenever the clone sits on an unrelated branch.
One thing the hook gives up: .worktreeinclude is not processed when a
WorktreeCreate hook replaces creation. This repo has no such file, so nothing
is lost today; add the copying to the hook if one is ever introduced.
Nothing ships that the app does not reach, and the two build modes exist so testing does not cost a shipping build.
| Artifact | Compile | What it is | |
|---|---|---|---|
just release prod fast |
~9 MB .app / a .deb |
~45 s warm | opt-level=1, no LTO, no strip, no dmg |
just release |
6.5 MB .app inside a .dmg / a .deb |
~2 min | opt-level=3, fat LTO, one codegen unit, stripped |
just release prod fast / pnpm app:fast overrides the release profile with
CARGO_PROFILE_RELEASE_* env vars rather than defining a second profile, so
there is one definition and no chance of the two drifting. (The Tauri CLI has
no --profile flag, so a real second cargo profile could not be selected
anyway.) just release leaves that profile alone (opt-level=3, fat LTO,
strip) and asks for the shipping installer (dmg / nsis); on Linux the
build makes the release's .deb and takes no choice of bundle. The justfile
names the bundle per OS so the Windows CLI is not asked for macOS's app or
dmg. Both are release binaries — neither carries debug assertions — so
what you test behaves like what you ship.
sccache caches compilation across profiles and checkouts when
RUSTC_WRAPPER=sccache is set in the environment. It is optional: without it
cargo uses the ordinary compiler, which is what Linux and CI need. Rebuilding
from clean went 104s → 43s at an 85% hit rate on the machine that measured
it. brew install sccache or apt install sccache; it cannot cache
incrementally-compiled crates, so it skips this app's own crate in dev builds —
the win is the ~500 dependency crates, which is where the time goes.
Measured again on nessa-images, the crate whose dependencies carry the
opt-level = 2 override, building into a target directory wiped between the
two runs: 18.5 s → 4.3 s, 39 of 39 compilations served from the cache. That
gap is what a worktree with its own target/, or a stray cargo clean, costs
when sccache is absent. Set it once in your shell profile:
command -v sccache >/dev/null 2>&1 && export RUSTC_WRAPPER=sccacheThe guard is the point: the variable is only set where sccache exists, so the
same profile is safe on a machine without it. It is deliberately not in
.cargo/config.toml — a wrapper named there fails the build outright on any
machine that has not installed it, including CI.
Dev builds use debug = "line-tables-only": full debug info is the single
biggest cost in a Tauri rebuild, and line tables still give a readable backtrace.
For a full Rust workspace check, including the desktop production feature, build the frontend first:
pnpm build
cargo check --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-targets --all-features --lockedTauri's custom-protocol feature embeds dist/ at compile time. Direct Cargo
commands do not run Tauri's beforeBuildCommand, so a fresh checkout needs
pnpm build before enabling that feature. The ordinary development check,
cargo check --workspace --all-targets --locked, does not need the bundle.
Measured on this machine, with pnpm app running:
| Change | Cost | What happens |
|---|---|---|
Anything under src/ |
76 ms | Vite HMR. No Rust rebuild, no restart, React state kept |
Anything under src-tauri/src/ |
2.8 s | Incremental rebuild (~1.7 s) and the app relaunches |
| A dependency version | seconds | Cargo rebuilds that crate and its dependents, not the graph |
So keep iteration in the frontend where the work allows it: that path is sub-100ms and does not lose the conversation on screen.
There is no hot-patching of the Rust side, and it is not worth adding. Swapping
code into a running process means building the app as a reloadable dylib
(hot-lib-reloader, Dioxus's subsecond), which fights Tauri's runtime setup
and would cost more to maintain than the 2.8 s it saves. The relaunch is already
faster than the webview takes to paint.
The frontend is 576 KB, all of it reached — down from 7.5 MB.
The package's published bundle is a single dist/index.js, which hoists every
dependency to one module's top level, so mermaid and katex are static
imports of that one file. Rollup cannot drop them by tree-shaking the components
that use them: an app using six components shipped mermaid, cytoscape, and the
whole KaTeX font set. Two changes fix it:
- Bundle from the package's source, not its
dist(aliases in vite.config.ts) — every component is its own module again, so unused ones shake out. - Import the component modules directly, not the barrel. Vite emits a
module's CSS and font assets as soon as it transforms it, before Rollup can
shake it — so reaching
math-blockthrough the barrel shipped 1.2 MB of KaTeX fonts even though nothing rendered math.
When mermaid or math are actually needed, import them with React.lazy from
their own module rather than adding them to a static import. They then become
chunks fetched the first time a message contains a diagram, instead of weight
every launch pays for.
Types come from the package's source as well (tsconfig.json's paths). Its
source would pull in the copy of React's types under its own node_modules, and
two copies make identical types nominally incompatible, so those paths also
point react and react-dom, and their subpaths such as react/jsx-runtime,
at this app's @types — the same shared packages Vite and Vitest dedupe
(sharedPackages in scripts/nessa-ui-paths.mjs).
noUnusedLocals is off because consuming the design system as source puts its
files in this program, and its dead locals are not this app's to fix.
The frost is an NSVisualEffectView behind the webview
(src-tauri/src/platform/macos/vibrancy.rs), not a CSS
backdrop-filter. On a transparent, undecorated macOS window the CSS filter does
not sample the behind-window content 1:1 — it stretches it into a bleed running a
few hundred points down the panel — and it stops updating when the window loses
focus, so the surface visibly changed as you clicked away. The native view does
both correctly, and NSVisualEffectState::Active keeps it frosted whether or not
the panel is frontmost.
Two consequences for the CSS: the panel carries only a tint over the native
frost, and it fills the window edge to edge, because the effect is clipped to an
18pt rounded rect of the window — any padding would leave it poking out past the
panel. Since the effect is window-level, the clear surface has to turn it off
natively too, which is what the set_frosted command is for.
The panel stays open when you click away or open Spotlight, in both development and release builds. It appears across desktop Spaces, with macOS fullscreen auxiliary behavior enabled to allow it alongside fullscreen apps. Use the tray item or summon shortcut to toggle it closed.
The chat kit lives in nessalabs/nessa_ui
(packages/react). It is not on npm yet, so pnpm install links it from
.vendor/nessa_ui. That directory is filled by scripts/ensure-nessa-ui.mjs
before install: it clones the reviewed commit in nessa-ui-revision into this
checkout's own directory, where scoped dependency installation and package builds
run. An existing .vendor/nessa_ui symlink is replaced with a private clone;
the borrowed target's source, edits, and build artifacts stay untouched (covered
by scripts/ensure-nessa-ui.test.mjs). When the pin moves, the script advances
its clone as long as it carries no local edits. A linked .vendor parent is
refused before preparation; replace that link with a checkout-local directory.
If private cloning fails after removing a vendor link, its target stays intact
and the next preparation retries cloning. Update the revision file
deliberately when adopting UI changes.
pnpm skips preinstall when the lockfile is already satisfied, so a pull that only
moves the pin leaves pnpm install doing nothing. pnpm ui:types is the reliable
way to advance. To make a stale clone impossible to miss, typecheck, dev,
build, and test each start with pnpm ui:check, a single offline git rev-parse
against the pin. A stale or missing .vendor then fails with one message naming
pnpm ui:types instead of type errors in files nobody touched.
"@nessa-ui/react": "link:.vendor/nessa_ui/packages/react"
The app imports the package's source, not its build: a component by
@nessa-ui/react/<component>, and a registry library the package's entry does
not export, such as the shared size observer, by @nessa-ui/react/lib/<name>.
One table, scripts/nessa-ui-paths.mjs, maps each of these to the package's
source. vite.config.ts and vitest.config.ts build their aliases from it.
tsconfig.json cannot import it, so the table owns its paths whole — its
entries and the React type redirects above — and pnpm ui:paths writes them.
pnpm architecture fails when an entry is missing, points elsewhere or was
added by hand, or when baseUrl or extends would move them; a test holds
the file to exactly what pnpm ui:paths writes. To change a path, change the
table and run pnpm ui:paths.
The composer requires the shared Markdown AST extension and on-demand math/diagram renderers in the pinned UI revision. To reconcile a managed clone with that pin:
pnpm ui:typesWhen the package publishes, this becomes "@nessa-ui/react": "^x.y.z".
src/styles.css and src/desktop/styles.css
import @nessa-ui/react/app.css. The path table sends that name, and
styles.css and theme.css, to the package's source stylesheets, not to
dist/ and not to src/components/. The built CSS only carries the utilities
the library's own components happen to use, so a class the app writes —
size-14, say — silently resolves to nothing. Compiling from source gives the
app the full utility set and the same tokens. The same import names the
published stylesheet once the package ships to npm and the path table is gone.
React is deduped in vite.config.ts: the linked checkout carries its own React, and without that the app and the library would each load a copy and every hook in the library would throw.
pnpm dev serves /icon.html (src/icon-preview.tsx), a
dev-only page that renders candidate palettes at icon size and at menu-bar size
over a menu-bar blue — a palette that reads well at 96px can collapse into a blob
at 16px, which is how the first icon went wrong: the default hue wheel put a
near-white wash against a dark ground, and the menu bar showed a white patch. The
shipped wheel is AGENT_HUES in
src/conversation/model/identity.ts, shared with the in-app avatar so
the two cannot drift.
The menu bar gets its own icon, src-tauri/icons/tray-avatar.svg
→ tray-icon.png, compiled into the binary with include_bytes! so dev and
packaged builds load identical bytes with no resource-path lookup.
Same seed and hue wheel as the app icon, but tone="vivid" instead of
"pastel". Pastel washes sit around 0.87–0.97 lightness: delicate and correct in
the Dock at 128pt, but at the 16pt the menu bar actually draws they collapse into
a pale disc that reads as a white blob on any bar. Dropping the avatar's paper
ground does not fix that — the pigment itself is near-white at that tone, so
the weight has to change, not the backing.
Regenerate it from the preview's sorbet · vivid tile, at 44px (the 22pt menu
bar slot at 2×). Because it is compiled in, cargo does not notice the new
bytes on its own — touch the file that includes it:
node scripts/render-icon.mjs src-tauri/icons/tray-avatar.svg src-tauri/icons/tray-icon.png 44 && touch src-tauri/src/tray.rsThe icon itself is src-tauri/icons/nessa-avatar.svg,
lifted from the preview's sorbet · pastel · shipped tile — a rendered
RandomAvatar with AGENT_HUES, AGENT_ICON_TONE, and ground="paper" — with
its Tailwind blend-mode classes inlined so the file stands alone. Being pastel it
sits quietly on a dark or coloured menu bar and goes faint on a light one; a
heavier tone in AGENT_ICON_TONE trades the sorbet for contrast. To rebuild
the set:
node scripts/render-icon.mjs src-tauri/icons/nessa-avatar.svg src-tauri/icons/nessa-avatar.png 1024 && pnpm tauri icon src-tauri/icons/nessa-avatar.pngThe obvious macOS one-liner, qlmanage -t -s 1024 -o . icon.svg, is a QuickLook
thumbnailer: it composites the artwork onto white. The PNG it writes has an
alpha channel — sips -g hasAlpha cheerfully reports yes — but every pixel is
opaque, so the icon carries a white square into the menu bar and the Dock. That
check is not evidence of transparency; read a corner pixel instead.
scripts/render-icon.mjs uses resvg, which renders the
SVG itself and leaves everything outside the artwork transparent. It converts the
design system's oklch() colours to sRGB first: resvg does not implement CSS
Color 4, and without the conversion every fill resolves to black and the avatar
comes out a solid disc.
- Drive
phasefrom stream events once chat RPCs exist on a remoteConversationGateway. - Make the voice control real: the design system's story streams a transcription into the input word by word, with hold-to-record and a live meter.
- Persist the transcript across launches.
- The rest of the chat kit — attachments, tapbacks, reply threads, chat tabs —
is already in the design system; see its
pill-composerStorybook story.
Gateway access uses local credentials at /session. The panel automatically loads
its assigned surface credential. Credentials have no expiry by default; grants and
optional expiry are configurable per surface. Namespace config.json controls
registry limits and session deadlines without rebuilding. See the
local auth guide and coding standards.
Every change follows CODING_STANDARDS.md, including the organization gate. Inspect the owning feature before editing, and keep its source, tests, scripts, configuration, and documentation organized together. Update module maps and links when responsibilities move; verify the resulting layout and relevant checks. See codebase structure for the repository map.
Press +, then Files in the Add menu, to choose files, or drop files/folders anywhere on the panel. Nessa UI's Folder traversal is sequential and stops at 20 files or 1,000 entries, rejecting oversized trees before allocating attachments. Attachment tiles inside the composer open the shared FilePreview sheet; remove controls remove individual files. Unsupported preview formats retain their filename and download action. File previews load on demand. Clipboard images use the same attachment flow. Text and links dropped on the panel enter the composer. Website image drops fetch the explicitly dragged image when its host permits browser access; blocked images show an error so the user can save and drop the file instead. Drops never navigate the panel away from the app.
Attachments belong to the conversation draft and survive tab switches, but are session-only. This feature does not upload files or send them to the text-only backend. A draft with files cannot be submitted; remove the files to send its text. Limits are 20 files per draft, 20 MiB per file, and 50 MiB total per draft, with a 100 MiB retained-file budget across all conversations. Redux retains only metadata and object URLs, never base64 file contents. URLs are revoked when files are removed, conversations close, or an attachment command is rejected. Local files attach synchronously without a full-file read. Text, Markdown, JSON, and CSV over 32 KiB remain attached and downloadable, but do not mount the whole-file inline renderer.
The native window disables Tauri's consuming drag/drop handler so HTML file drops reach FileDropZone. The standard file input opens the operating-system picker; no filesystem or dialog plugin is required. Native behavior needs a rebuilt app.
flowchart LR
P["+ → Add menu → Files / panel drop zone"] --> R["Create bounded local object URLs"]
R --> A["Conversation attach-files command"]
A --> D["Draft file parts with count/size limits"]
D --> V["Attachment tile → lazy FilePreview"]
D --> X["Remove file"]
D --> B["File-bearing draft blocks text-only send"]