Zara

• Zara — hybrid symbolic AI assistant and native copilot
  • What Zara is trying to become
  • Current implementation
    • Core runtime and daemon
    • Desktop copilot
    • Android
    • Voice
    • Prolog and symbolic semantics
    • LLM agent and providers
    • Tools, plugins, and MCP
    • Zarathushtra desktop pets
  • Architecture at a glance
  • Commands
  • Quick start
  • Development and tests
  • Documentation map
  • Status language used in this repository
  • Rough edges

Zara — hybrid symbolic AI assistant and native copilot

Zara is an experimental assistant runtime built around Prolog, voice, tools, LLMs, durable conversations, and native clients.

The project began as a Linux voice-command experiment. It has grown into a client/server assistant platform with a long-lived Zara runtime, a native PySide6 desktop client, an Android client under active development, a versioned ZARA/1 protocol, symbolic intent handling, plugin/tool infrastructure, and local or remote model providers.

This is still a learning and research project. A lot of Zara was bootstrapped with LLM assistance, and part of the point is to replace vague generated machinery with systems I actually understand: Prolog rules, explicit protocols, typed runtime boundaries, deterministic tests, and better language processing.

Zara is not presented as a production-hardened assistant. It changes quickly, and some ambitious pieces are still behind explicit release gates.

What Zara is trying to become

The end goal is one assistant with many native surfaces rather than a pile of unrelated chat programs.

• One durable runtime owns conversations, turns, tools, plugins, memory, voice work, and provider execution.
• One versioned protocol lets desktop, CLI, Android, and future clients talk to that runtime without embedding their own assistant stack.
• Symbolic logic first where it makes sense: Prolog handles deterministic semantics and intent/capability decisions; LLMs handle open-ended conversation and reasoning where symbolic rules are not enough.
• Voice and text share conversations. A voice session should appear in the same durable history as typed chat rather than disappearing into a separate mode.
• Native clients stay native. The Linux UI is PySide6/Qt; Android is a real Android application rather than a web wrapper.
• Plugins extend Zara through bounded runtime APIs instead of reaching into UI objects or creating parallel runtimes.

Current implementation

Core runtime and daemon

Zara has a long-lived zara-server process and a reusable client boundary.

The server owns runtime lifecycle. Clients issue commands and consume provider-neutral events. The versioned ZARA/1 protocol uses ZeroMQ ROUTER/DEALER transport and supports the same canonical turn/conversation semantics used by the in-process runtime.

Implemented daemon-era work includes:

• RuntimeHost as the application-service boundary;
• RuntimeSupervisor / principal-owned runtime lifecycle;
• durable conversation and message state;
• ZARA/1 command/event framing;
• client/server handshake, correlation, cancellation, and bounded transport behavior;
• principal-scoped conversations/context/memory;
• authenticated transport and key handling work;
• cross-process voice transport and canonical turn cancellation;
• daemon-client desktop operation as the normal desktop direction.

The final adversarial daemon/voice replacement gate remains open. See issue #134 and docs/server.org. Do not interpret the existence of the protocol as a claim that every production/security/voice parity goal is finished.

Desktop copilot

The Linux desktop client is native PySide6/Qt.

Current desktop foundations include:

• system tray integration;
• persistent conversations and messages;
• runtime/provider status;
• streaming assistant updates;
• canonical turn cancellation;
• native Markdown/code rendering;
• settings and diagnostics surfaces;
• daemon-client runtime transport;
• keyboard-first summon behavior;
• desktop-pet integration as an optional event consumer.

The repository still contains the historical QuickCopilotWindow / FullChatWindow split. Current design research supersedes that model: Zara is moving toward one adaptive Copilot window that changes between compact and expanded presentation while preserving one conversation renderer and one composer.

That consolidation is design-ready work, not something this README pretends has already landed. See the unified Copilot research.

Android

The Android client lives in android/ and is a real Gradle/Android project.

Current Android foundations include:

• application id ai.zara.app;
• typed runtime state;
• a Trealla Prolog runtime through a thin NDK/JNI bridge;
• portable semantic fixtures shared with the Zara symbolic model;
• authenticated ZARA/1 transport work using JeroMQ/CURVE;
• enrollment state and pinned-server-key handling;
• Android-side credential protection;
• reproducible Nix development/build tooling and APK tests.

The Android application is still under active construction. Assistant-role integration, the complete native chat surface, Samsung-specific integration, voice UX, and device adapters are not all release-complete yet.

See wiki/android.org.

Voice

Zara supports speech-to-text, wake interaction, text-to-speech, and the newer daemon voice boundary.

The voice architecture is deliberately split by ownership:

• the client device owns microphone capture and speaker playback;
• the runtime/server owns VAD/STT routing, turn coordination, model/tool work, and TTS production;
• canonical turn_id / conversation_id values correlate voice and text;
• interruption/barge-in cancels stale work through the same turn lifecycle as typed interaction.

Standalone dictation remains available through zara-dictate.

See docs/STT.md and docs/server.org.

Prolog and symbolic semantics

Prolog is not decoration in Zara. It is one of the main architectural experiments.

Desktop/core Zara uses SWI-Prolog through the Python boundary. Android uses a portable Trealla runtime for the subset that must run on-device. Shared fixtures are used to keep portable semantics honest across runtimes.

The current intent path is still evolving. Long term, Zara should rely more on explicit symbolic representations and better Prolog/DCG language handling instead of shallow generated intent glue.

Relevant docs:

• IntentFrame contract
• capability plans
• main.pl, kb/, and modules/
• android/app/src/main/assets/prolog/portable/

LLM agent and providers

Open-ended conversation and tool use are handled by Zara's agent/runtime layer.

Provider integrations include OpenAI, Anthropic, and Ollama. Local Ollama use keeps model execution local; remote providers require their own credentials and can receive conversation content according to their service behavior.

The LLM agent is not supposed to bypass the runtime boundary. Tools, cancellation, conversations, plugins, and UI state all converge on canonical Zara runtime commands/events.

Tools, plugins, and MCP

Zara supports ordinary tools plus a versioned service-plugin lifecycle.

User plugins are normally discovered beneath:

~/.zarathushtra/plugins/

Long-running plugins receive a restricted runtime facade for configuration, event subscriptions, managed workers, and runtime-command dispatch. They do not receive Qt widgets, raw backend objects, the microphone, or unrestricted runtime internals.

The companion zara-plugins repository is the home for installable Zara plugin work. Core lifecycle/API documentation lives in wiki/plugins.org. MCP integration is documented in wiki/mcp.org.

Zarathushtra desktop pets

The optional Pet subsystem reacts to provider-neutral Zara runtime events such as listening, thinking, tool activity, success, and errors.

Pets are consumers of runtime truth, not a second state authority. They can run in-process or through the compatibility ZeroMQ bridge.

See docs/pets.md and wiki/pets.org.

Architecture at a glance

                   native clients
        +-------------+-------------+
        |             |             |
     Desktop         CLI         Android
     PySide6                     Kotlin/NDK
        |             |             |
        +-------------+-------------+
                      |
                 ZaraClient API
                      |
              ZARA/1 / in-process
                      |
                 zara-server
                      |
               RuntimeSupervisor
                      |
                  RuntimeHost
                      |
       +--------------+---------------+
       |       |       |       |       |
     Prolog   Voice   Agent   Tools   Plugins
       |               |               |
       +---------------+---------------+
                       |
          conversations / context / memory

The main rule: clients project runtime state; they do not become alternate runtimes.

For the deeper version, read docs/architecture.org.

Commands

Command	Purpose
zara	Client-facing CLI.
zara-server	Long-lived runtime/service process.
zara-desktop	Native Linux desktop copilot.
zara-wake	Wake-word / voice interaction.
zara-dictate	Standalone speech-to-text dictation.
zara-console	Interactive console client.
zara-agent	Agent-oriented entry point.
zara-pets	Optional Zarathushtra pet UI.

Quick start

Nix is the authoritative development surface.

git clone https://github.com/lost-rob0t/zara.git
cd zara
nix develop

Run the server in one shell:

zara-server

Then launch a client, for example:

zara-desktop

The packaged desktop application can also be invoked with:

nix run .#zara-desktop

For standalone utilities:

zara-dictate
zara-console
zara-pets

Development and tests

Main repository gate:

nix develop -c bash scripts/test-all.sh

Android gate:

nix develop .#android -c bash scripts/test-android.sh

The project uses focused tests plus Nix/CI gates for Python, Prolog, daemon transport, lifecycle behavior, packaging, Android builds, and other integration surfaces. UI work is also moving toward deterministic screenshot artifacts so visual regressions can be reviewed rather than inferred from widget tests.

See docs/development.org.

Documentation map

Document	Scope
docs/README.org	Documentation index and implementation-status conventions.
docs/architecture.org	Runtime/client/server architecture and invariants.
docs/server.org	Daemon, ZARA/1, principals, auth, and voice boundary.
docs/development.org	Build/test/development workflow.
desktop-copilot-design.md	Earlier desktop architecture/design research.
unified Copilot research	Current desktop/voice continuity/visual-CI direction.
wiki/android.org	Android architecture, toolchain, status, and queue.
wiki/plugins.org	Plugin API and lifecycle.
wiki/install.org	Installation details.
wiki/customization.org	Configuration and customization.

Status language used in this repository

To keep rapidly changing docs from lying:

• Implemented means code exists on the current branch and has repository test evidence.
• Active / evolving means usable foundations exist but the surface is still being changed.
• Design-ready / researched means there is an accepted direction or research note, not necessarily merged implementation.
• Release-gated means the feature exists in pieces but Zara explicitly refuses to claim the larger goal until an adversarial gate passes.

Rough edges

• Zara is experimental and moves fast.
• Linux/Nix remains the best-supported desktop environment.
• Android is not yet a finished daily-driver release.
• Some providers require external credentials and services.
• The symbolic/NLP layer is intentionally still being rebuilt and learned.
• Security-sensitive daemon work has explicit regression gates; passing individual implementation slices is not the same thing as declaring the whole service production-ready.
• The desktop UI is in the middle of a substantial consolidation/redesign.

If you want a pristine reference architecture, this repo is the wrong thing to cargo-cult.

If hybrid symbolic AI, native clients, Prolog, voice, weird desktop software, and replacing hand-wavy LLM glue with explicit systems sounds fun: that is exactly why Zara exists.