Skip to content

Desktop and Browser Interface Setup

Aesop Agentic provides a Tauri 2 desktop window and a shared React/Vite browser interface. The existing Python collector, native service owner, archive format, and terminal dashboard remain in use.

Launch Choices

Command Behavior
aesop open Open the configured default interface.
aesop desktop Open the installed Tauri window.
aesop browser Open the local web app in the default browser.
aesop serve Run the web server in the foreground and open a browser.
aesop serve --no-open --port 8765 Run the server at a chosen loopback port.
aesop dashboard Run the Textual dashboard in the current terminal.
aesop open --ui terminal Open the preferred macOS terminal.
aesop open --terminal Warp Open a new Warp window without changing preferences.
aesop preferences --ui browser Save Browser as the default interface.
aesop preferences --terminal iTerm2 Save iTerm2 as the preferred terminal.

Settings exposes the same two launch preferences. These top-level TOML settings must precede [sources] and destination tables:

ui_mode = "desktop"
terminal_app = "iTerm2"

The browser and desktop interfaces show current collection status, independent parse status, backup outcomes, source error details, and explicit Collect Now, Retry Backup, Parse Archive, and Verify Archive actions. Archive search matches titles and can filter by source. Documents load in bounded sections to handle large transcripts. Document Metadata exposes original source/model/ancestry fields when present. Remote content and active transcript HTML are not loaded.

Verify Archive checks local raw and rendered data. It deliberately does not read cloud backup destinations; use the CLI's full verification when the destination is available. Parsing retains incomplete/unsupported format indicators rather than treating an undecoded store as a successfully recovered conversation.

Building and Installing

Use Python 3.11+, Node.js/npm, Rust/Cargo, Apple's Command Line Tools, and just for the recipes below. The GitHub repository is private; maintainers can clone it. Other users can download and unpack the source distribution from PyPI, which includes the frontend, desktop source, lockfiles, and build scripts. Run the commands from that unpacked directory:

just install
just setup             # Only when no config exists yet.
just install-desktop   # Build web assets, build Rust, install the app/service.
just desktop

just build-web rebuilds packaged static assets. just build-desktop stages the platform-specific executable under the Python package's assets. aesop service install incorporates it into the managed macOS app. The build uses the checked-in npm and Cargo lockfiles. Reinstall after rebuilding the desktop binary; web assets in an editable installation are read from the current package.

A wheel built after the desktop build contains the native executable and has a platform-specific tag. A wheel built without that component contains the browser and terminal interfaces. Installed commands work outside the clone as long as the configured archive directory and installed Python environment remain present. The runtime is not frozen into the app. Moving/removing the Python environment requires reinstallation. Developer ID signing/notarization and other platforms' installers remain separate distribution work.

Installed Identity and Lifecycle

The existing collector keeps com.colinconwell.aesop-agentic, its native main executable, one LaunchAgent, and native notification ownership. The new GUI is packaged as Contents/Helpers/Aesop Agentic Desktop.app with the related stable identifier com.colinconwell.aesop-agentic.desktop. Both bundles use the approved Archive icon resources, appearance-aware asset catalog, Aesop Agentic display name, and Colin Conwell authorship metadata. The nested GUI bundle is necessary for macOS to attribute its window to a real application rather than an unrelated executable. Local builds are ad hoc signed, not notarized distribution builds.

The native collector parent stays alive around Python operations. The Tauri GUI is a separate native child window. It connects to the same per-configuration loopback server as the browser interface. The UI server is launched through the installed native app where available, so it does not create another scheduled collector. Closing a window leaves scheduled collection enabled. The server expires after 30 idle minutes, except while an explicit action is running. Opening the interface again reconnects or starts a fresh server.

UI action logs are stored in state_root/ui/actions/; the last action summary is state_root/ui/last-operation.json. The server log is in the Aesop Agentic system log directory. State files containing access URLs are private to the current user. A foreground serve prints its access URL for intentional local use.

Using the Interface

  • Addresses. Every page has its own address (#/overview, #/archive, #/logs, #/settings). The Archive address records the search, source, sort, open conversation, and section, so reloading, bookmarking within the session, and the Back button all return to the same place.
  • Search. The Archive search box matches message text by default; select Titles Only to match titles. A message search requires every word and orders results by relevance, showing up to three matching excerpts per conversation. Selecting an excerpt opens the transcript at that section with the words highlighted. Tool inputs and outputs are not indexed.
  • Reading. Long transcripts are divided into sections of roughly 120 KB that never split a code block or tool event. Use the section menu or the arrows to move through them. Tool calls and results are collapsed; select Expand Tool Details to open them all.
  • Keyboard. Press / to search, j and k to move through the list, and Return to open a conversation. A skip link leads to the page content.
  • Actions. While a collection, parse, or backup runs, the banner shows the elapsed time and current step, such as the source being collected or files checked and copied during a backup. Cancel stops an action started from the window. Finished results stay until dismissed. Actions other than backups stop after four hours; backups use their own limits.
  • Status. A run is Complete, has Coverage Gaps (expected limits, such as sources awaiting sign-in or undecoded formats), or Needs Attention (source errors, parser failures, or backups that failed or copied only part of the archive). Only Needs Attention sends an alert with sound.
  • Backups. Each destination shows its type and location, the last successful backup (including backups run on their own), what the last run copied, and notes such as files stored only in iCloud or unmanaged folders.
  • Notifications. Settings shows whether macOS allows Aesop notifications and can request access or send a test notification.

The search index (parsed/.search.sqlite) is updated after each parse. It is derived from the rendered transcripts, stays on this Mac, and is not backed up.

Local Web Boundary

The server binds only to IPv4 loopback on a random available port by default. Every API read/write requires a random bearer token; the launcher places it in the URL fragment, and the frontend removes the fragment after storing it in the tab's session storage. Requests must match the expected Host and Origin. The server does not enable cross-origin access. It serves only packaged UI assets; archive reads require an indexed document identifier and remain inside parsed/.

The frontend renders Markdown without active HTML, remote images, or navigation from transcript links. Tauri navigation stays on the local origin. Its only native permission is the Open panel for choosing an export to import (desktop/capabilities/import-picker.json); it has no shell or general filesystem access. These boundaries prevent a transcript from becoming an executable frontend document. Remote multi-user hosting is not implemented; this server must not be exposed through a public proxy.

Warp Terminal Integration

The adapter writes only its own per-configuration file at ~/.warp/tab_configs/aesop_agentic_<config-hash>.toml, then opens warp://tab_config/<name>?new_window=true. The tab runs the private generated Aesop command with shell-quoted paths. Existing Warp defaults and unrelated tab configs are preserved. Missing apps and launch failures produce explicit errors. This uses the current Warp Tab Config API, not the legacy YAML launch format.

Complete Parsing Audit

aesop parse --rebuild --audit-revisions
aesop verify --local-only

The rebuild regenerates current conversation documents. The additional audit runs the registered decoders over retained historical revisions, records failures and coverage classes in data/parsed/revision-audit.json, and leaves current rendered documents unchanged. This distinguishes historical snapshot issues from current parser failures. Original content-addressed objects are never rewritten.

Desktop Window Behavior

Opening Aesop again while its window is open brings the existing window forward instead of starting another. The window remembers its size and position. When launched from a terminal, aesop desktop returns to the prompt while the window stays open; the installed app remains the responsible process while its window is open.

Version 0.4 Desktop Chrome and Recovery

The desktop window now uses a native AppKit unified compact toolbar, hidden window title, and Tauri's transparent title-bar style. macOS owns traffic lights, dragging, accessibility, and full-screen behavior. No custom web traffic lights, private AppKit APIs, or additional webview IPC privileges are introduced. The web interface keeps normal browser chrome. Both use the transparent Archive emblem; installed application and notification icons retain their existing light/dark resources and stable identifiers.

Every dashboard source links to Logs & Setup. Logs & Recovery includes source results, parser issues, local logs, login/import/recovery controls, and an error reference. See Source Recovery and Diagnostics for the exact coverage and limits, including ChatGPT account access.