Skip to content

hyperpush-org/xero

BranchesTags

Repository files navigation

Xero (Tauri Desktop)

Xero is a Tauri desktop app for agentic development workflows, with a React/Vite frontend and a Rust backend command surface.

It combines:

  • Project/repository import + file editing/search operations
  • Runtime/session orchestration for AI providers
  • Autonomous run + operator approval loop support
  • In-app browser automation
  • iOS/Android emulator sidebars + automation hooks
  • Solana workbench tooling (clusters, personas, tx pipeline, deploy helpers)
  • Skill/plugin discovery and execution support
  • Session memory, transcript search, compaction, branch, and rewind workflows
  • MCP server registry management
  • Phoenix/Postgres sidecar services for web callbacks and shared backend features

Important: this is a desktop-first Tauri app. For end-to-end behavior, run via Tauri (tauri dev), not as a plain browser app.

Repository Layout

.
├─ client/                 # Main desktop app (React + Vite + Tauri + Rust)
│  ├─ src/                 # App entry + feature hooks
│  ├─ components/          # ShadCN UI + Xero shell/views
│  ├─ src-tauri/           # Rust backend, commands, state, tests
│  └─ package.json
├─ cloud/                  # TanStack Start web/PWA cloud session surface
├─ landing/                # Separate Next.js marketing site
├─ server/                 # Phoenix service + Postgres-backed features
├─ docs/                   # Provider, memory, skills/plugin docs
├─ STANDALONE_AGENTS_ASK_PLAN.md # Plan for Ask agent + future standalone agents
└─ package.json            # Root convenience scripts

Key top-level projects

  • client/: production desktop app (productName: Xero, identifier: dev.sn0w.xero)
  • cloud/: browser/PWA surface for remote sessions, deployed to cloud.xeroshell.com
  • landing/: separate website, run on port 3001 in root dev workflow
  • server/: Phoenix 1.8 service, local Postgres, GitHub auth callback/session support, Oban jobs

Tech Stack

Desktop app (client/)

  • Frontend: React 19, TypeScript, Vite, Vitest, ShadCN/Radix UI, Tailwind CSS
  • Desktop host: Tauri v2
  • Backend: Rust (command surface + orchestration + persistence)
  • Storage: SQLite and LanceDB-backed project stores under the OS app-data directory

Landing site (landing/)

  • Next.js 16, TypeScript, Tailwind CSS

Cloud app (cloud/)

  • TanStack Start, React 19, TypeScript, Tailwind CSS, PWA assets

Server (server/)

  • Phoenix 1.8, Elixir, LiveView, Ecto/PostgreSQL, Oban, Hammer rate limiting

Core App Surfaces

Main shell views:

  • Workflow — the agent-canvas surface, where you author and inspect agents.
  • Agent
  • Editor

Inside an agent canvas you can add Stages: gated phases that the agent moves through during a single run. Each stage decides which tools the agent may call, and the agent can only leave a stage once the gates you configure pass. Stages restrict one agent over time; the future "Workflow" pipeline (composing multiple agents end-to-end) is reserved but not yet implemented — don't conflate the two.

Sidebar tools:

  • In-app browser
  • iOS emulator sidebar (macOS only)
  • Android emulator sidebar
  • Solana workbench sidebar

Onboarding flow covers:

  • Provider profile setup
  • Project import

Prerequisites

1) Base (required)

  • Node.js (modern LTS recommended; Node 20+ is safest for current deps)
  • pnpm
  • Rust toolchain + Cargo
  • protoc on PATH. LanceDB-backed memory pulls lance-* crates whose build scripts compile vendored .proto files. On macOS: brew install protobuf.
  • Tauri OS prerequisites for your platform (WebView/runtime dependencies)
  • Docker Desktop, Docker Engine, or a compatible Docker daemon, for the local Postgres service
  • Docker Compose v2 (docker compose) or legacy docker-compose; root scripts use whichever is available
  • Elixir/Mix for the Phoenix server

2) Emulator features

Android

  • Android SDK tooling (adb, emulator) and at least one AVD
  • If missing, Xero can provision a managed SDK in app data via backend provisioning flow

iOS (macOS only)

  • Xcode + iOS Simulator tooling (xcrun, simctl)
  • Accessibility permission (required for some simulator input paths)

3) Solana workbench features

Detected/used CLIs include:

  • solana (minimum required for localnet workflows)
  • anchor
  • cargo-build-sbf
  • surfpool
  • trident
  • codama
  • solana-verify
  • plus node and pnpm

If tools are missing, workbench surfaces degraded/missing-toolchain states rather than crashing.

4) Server features

  • Postgres is provided by server/docker-compose.yml in local development.
  • Server env defaults are documented in server/.env.example; local secrets belong in server/.env.

Setup

This repo is a pnpm workspace, and the root dev preflight also installs each package in place. After cloning and completing the prerequisite toolchain/env setup above, the happy path is:

pnpm run dev

The root pnpm run dev command runs an idempotent preflight that:

  • installs root, client/, cloud/, and landing/ pnpm dependencies from their lockfiles
  • verifies required local commands (pnpm, git, mix, cargo, protoc)
  • installs Hex/Rebar if missing, fetches Mix deps, and installs Phoenix asset tools
  • starts Docker/Postgres where the OS allows it, creates the database, and applies migrations

Manual setup commands still work if you need to isolate a failing step:

pnpm install
pnpm --dir client install
pnpm --dir cloud install
pnpm --dir landing install
cd server && mix setup

Command Reference

Root commands

pnpm run dev          # Preflight, Postgres logs, Phoenix server, Tauri desktop, landing site, and cloud app
pnpm run stop:all     # Stop Xero dev servers and the local Postgres container
pnpm run dev:preflight
pnpm run db:up
pnpm run db:down
pnpm run db:reset
pnpm run server:setup
pnpm run dev:server   # Phoenix server on localhost:4000
pnpm run dev:tauri    # Desktop app only (Tauri dev)
pnpm run dev:tui      # Real Xero agent TUI terminal client + required relay/Cloud dev services
pnpm run dev:landing  # Landing site on port 3001
pnpm run dev:cloud    # Cloud app on port 3002

dev uses concurrently to start:

  • pnpm run dev:db:logs
  • pnpm run dev:server
  • pnpm run dev:tauri
  • pnpm run dev:landing
  • pnpm run dev:cloud

Desktop app (client/) commands

pnpm --dir client dev         # Vite dev server on :3000 (frontend only)
pnpm --dir client build       # Frontend production build
pnpm --dir client preview     # Preview built frontend on :3000
pnpm --dir client test        # Vitest run
pnpm --dir client test:watch  # Vitest watch mode
pnpm --dir client lint        # ESLint

Tauri desktop commands

pnpm --dir client run tauri:dev
pnpm --dir client run tauri:dev:ios-grpc
pnpm --dir client exec tauri build
pnpm --dir client exec tauri build --debug

# enable live emulator H.264 decode support
pnpm --dir client run tauri:dev -- --features emulator-live

Rust backend checks/tests

cargo check --manifest-path client/src-tauri/Cargo.toml
cargo test  --manifest-path client/src-tauri/Cargo.toml

Target a specific integration suite:

cargo test --manifest-path client/src-tauri/Cargo.toml --test runtime_supervisor
cargo test --manifest-path client/src-tauri/Cargo.toml --test solana_workbench

Prefer scoped Cargo checks/tests while iterating, and run only one Cargo command at a time so the target directory lock does not become the bottleneck.

Root helpers wrap the same policy:

pnpm run rust:test
pnpm run rust:target:prune:dry-run
pnpm run rust:target:prune

Phoenix server (server/) commands

cd server
mix setup
mix phx.server
mix test
mix precommit

Landing site (landing/) commands

pnpm --dir landing dev
pnpm --dir landing build
pnpm --dir landing start
pnpm --dir landing lint

Cloud app (cloud/) commands

pnpm --dir cloud dev
pnpm --dir cloud build
pnpm --dir cloud check
pnpm --dir cloud test

Runtime Provider Support (Desktop)

Xero supports provider profiles for:

  • openai_codex (OAuth flow)
  • openrouter
  • anthropic
  • deepseek
  • github_models
  • xai (xAI / Grok; OAuth, device code, or API key)
  • openai_api (OpenAI-compatible)
  • ollama (local OpenAI-compatible)
  • azure_openai
  • gemini_ai_studio
  • bedrock (ambient AWS creds)
  • vertex (ambient GCP creds)

Credentials/config are managed via app state and provider profile stores (not via checked-in env files). For xAI / Grok OAuth, Xero uses xAI's shared public OAuth client for local Grok agents; ordinary X Developer Portal OAuth client ids are for X API auth and are not accepted by auth.x.ai. End users should only need to sign in, use device code, or paste an API key. OpenAI-compatible setup recipes cover LiteLLM, LM Studio, Mistral, Groq, Together AI, NVIDIA NIM, MiniMax, Azure AI Foundry, Atomic Chat local, and custom /v1 gateways. See docs/provider-setup-and-diagnostics.md for the setup and diagnostics workflow, including the current GitHub Models token-based onboarding decision and native xAI/Grok setup.

Session Memory And Context

Xero supports session transcript search, Markdown/JSON export, context visualization, manual compact, opt-in auto-compact, branch, rewind, selective code undo, and session rollback workflows. Reviewed memory and project records live in the shared OS app-data project_store/Lance backend; dev:tui renders the review queue through a desktop-backed adapter rather than a copied terminal store. See docs/session-memory-and-context.md for shipped behavior, privacy guarantees, and support triage guidance.

Agent Harness Benchmarking

Xero's owned-agent harness should be compared with fixed-model, sandboxed benchmark runs rather than informal leaderboard screenshots. See docs/agent-harness-benchmarking.md for the research summary, benchmark choices, and implementation plan.

Xero Agent TUI And Tool Harness

pnpm run dev:tui launches the real terminal-native Xero agent client (xero). It also ensures the local Phoenix relay and Cloud app are available for TUI cloud-session development, starting missing local services after preflight. It is for owned-agent development workflows: selecting an app-data project, selecting or creating sessions, sending prompts through the shared headless runtime, inspecting runtime events/tool calls, and reaching project/git/provider/context command surfaces without opening a Tauri window. The development command runs the desktop-backed xero binary so project records, memory review, and agent-definition authoring reuse existing desktop Rust services.

Terminal file actions are wrappers over the shared owned-agent Tool Registry V2 where available (xero file list|read|write|patch|delete|move|replace|tools), so policy, sandboxing, rollback metadata, and path protections stay aligned with real agent tool calls.

Inside dev:tui, the : command palette also exposes desktop-backed code-history recovery: code-history list|selective-undo|session-rollback and conversation rewind call the existing project_store rollback/session-lineage services. File-changing undo/rollback commands require explicit --apply.

Project process surfaces use the same app-data start_targets contract as the desktop project runner: xero process targets|add-target|remove-target|start|list|status|tail|stop. The dev:tui palette also exposes the shared desktop project-runner PTY registry with terminal open|list|read|write|resize|close, including a retained output buffer for terminal-native reads.

Provider and settings surfaces use the same app-data contracts as the desktop/backend paths: xero provider list|login|remove|doctor|preflight, xero mcp list|add|login|remove|status|serve, xero environment status|profile|user-tools|save-tool|remove-tool, xero skills list|enable|disable|remove|plugins, xero plugins list|enable|disable|remove, and xero settings agent-tooling|browser-control|soul. The dev:tui palette routes skill-sources list|upsert-local-root|remove-local-root|github|project|reload, plugin-sources list|upsert-root|remove-root|reload, and environment start|refresh|resolve-permissions|verify-tool|save-tool-verified|remove-tool-verified through the shared desktop settings/discovery/environment services.

Agent definitions are exposed through the shared app-data contract with xero agent-definition list|show|versions|diff|archive. Inside dev:tui, the : command palette also routes agent-definition draft|validate|preview|save|update|clone|attachable-skills --project-id ID --definition-file FILE through the shared autonomous definition service, including validation, effective runtime preview, write approval review, skill attachment catalog, and JSON-file Stage snapshots.

Terminal-compatible Solana workbench operations are exposed in dev:tui through the existing desktop Solana module: solana catalog|cluster-list|scenario-list|persona-roles|pda-scan|pda-derive|secrets-scan|doc-catalog|doc-snippets|wallet-scaffold-list|token-extension-matrix.

Maintenance usage totals are exposed with xero usage summary, reading the existing project agent_usage table.

Project-state maintenance is exposed with xero project-state list|backup|restore|repair and gated destructive cleanup through xero wipe project|all. These commands operate under OS app-data and require explicit confirmations for restore/wipe paths.

Fast development launch:

pnpm run dev:tui

Released TUI install:

curl -fsSL https://xeroshell.com/install.sh | sh

Windows PowerShell:

irm https://xeroshell.com/install.ps1 | iex

The install scripts download from the Fly-hosted landing app at /downloads/tui/latest/, verify the archive checksum, and install xero locally. Set XERO_INSTALL_DIR to choose a different install directory. Once installed, xero update check reports whether a newer TUI is available and xero update install downloads, verifies, and applies it.

Headless launch verification:

pnpm run dev:tui -- --smoke
pnpm run dev:tui -- --smoke-run

Direct Cargo form:

cd client/src-tauri
cargo run --package xero-desktop --bin xero
cargo run --package xero-desktop --bin xero -- --smoke
cargo run --package xero-cli --bin xero-core -- tui --smoke # CLI-core smoke

The desktop developer tool harness remains available separately through the tool-harness binary. It is a developer/debug harness for cataloging and replaying individual backend tools; it is not the product TUI and does not own the dev:tui script.

Direct Cargo form:

cd client/src-tauri
cargo run --bin tool-harness -- fixture
cargo run --bin tool-harness -- catalog
cargo run --bin tool-harness -- dry-run read --input-json '{"path":"README.md"}'
cargo run --bin tool-harness -- run read --input-json '{"path":"README.md"}'
cargo run --bin tool-harness -- sequence list

Use --json on batch commands for scriptable output, and --app-data-dir PATH for isolated harness smoke tests. The terminal harness stores fixture and sequence state under OS app-data only; do not point it at repo-local .xero state.

The agent TUI parity matrix lives in docs/agent-tui-parity.md. Desktop-only browser viewport, emulator live panes, graphical canvas gestures, window chrome, and microphone dictation remain explicit exclusions; renderer-independent workflows are exposed through terminal-native panes or CLI commands.

Scoped verification for harness work:

cargo test --manifest-path client/src-tauri/Cargo.toml developer_tool_harness --lib --bins
pnpm --dir client vitest run components/xero/settings-dialog/development-section/tool-harness/index.test.tsx

Run one Cargo command at a time so the shared build lock does not stall parallel agents.

Agent System Release Gates

Agent-system rollout uses explicit gates for custom-agent fidelity, context, handoff, storage, security, diagnostics, documentation, and deferred UI. See docs/agent-system-release-checklist.md for the release checklist and reset/fail-closed policy for unsupported custom-agent definitions.

Skills And Plugins

Xero discovers static and dynamic project skills/plugins and stores trusted project artifacts in app data, not inside the imported repository. See docs/skills-and-plugins.md for authoring, trust, and runtime notes.

Tauri Command Surface (High-Level)

Backend commands are registered in client/src-tauri/src/lib.rs and grouped under modules in client/src-tauri/src/commands/.

Major groups:

  • Project/repo: import/list/remove projects, snapshot, git status/diff, file operations, search/replace
  • Runtime: auth/session, start/stop runtime runs, stream subscription, operator action resolution
  • MCP: list/upsert/remove/import MCP servers, refresh connection status
  • Browser: tabbed in-app browser automation (navigate/click/type/query/cookies/storage/screenshot/diagnostics/state), plus configurable native browser fallback for owned agents
  • Emulator: SDK status, device lifecycle/input, screenshots, UI tree/find/tap/swipe/type, app lifecycle helpers
  • Solana: cluster lifecycle, snapshots, personas, scenario runs, tx build/sim/send/explain, ALT/IDL/PDA/program deploy flows

Sidecars, Build-Time Behavior, and Feature Flags

Rust/Cargo features (client/src-tauri/Cargo.toml)

  • default = []
  • emulator-live (enables openh264 decoding for live emulator frame decode)
  • emulator-synthetic (synthetic frame generator/testing path)
  • ios-grpc (compiles vendored idb.proto gRPC client)

Default dev builds keep emulator/iOS gRPC dependencies out of the hot path. If emulator-live is not enabled, H.264 decode path reports decoder unavailable.

build.rs behavior (important)

On build, Xero can:

  1. Build and stage xero-cookie-importer helper binary
  2. Fetch and verify checksum for scrcpy-server-v2.7.jar
  3. On macOS, fetch and verify idb-companion universal bundle
  4. Compile proto/idb.proto when ios-grpc is enabled
  5. Compile the macOS dictation Swift shim when the host SDK supports it

Build-time env var

XERO_SKIP_SIDECAR_FETCH=1
XERO_BUILD_COOKIE_IMPORTER=1
XERO_SKIP_COOKIE_IMPORTER=1
XERO_SKIP_DICTATION_SHIM=1
  • XERO_SKIP_SIDECAR_FETCH=1 skips scrcpy/idb download steps.
  • XERO_BUILD_COOKIE_IMPORTER=1 builds the cookie helper from its separate crate.
  • XERO_SKIP_COOKIE_IMPORTER=1 skips helper staging.
  • XERO_SKIP_DICTATION_SHIM=1 skips the macOS native dictation shim.

Optional runtime env vars

These are optional and only needed for specific runtime integrations:

# Custom web-search provider used by autonomous web tools
XERO_AUTONOMOUS_WEB_SEARCH_URL=https://...
XERO_AUTONOMOUS_WEB_SEARCH_BEARER_TOKEN=...

# Solana workbench resource overrides
XERO_SOLANA_RESOURCE_ROOT=/path/to/resources
XERO_SOLANA_TOOLCHAIN_ROOT=/path/to/toolchain

Persistence Model

SQLite state

Xero stores application and project state under the OS app-data directory:

  • xero.db for global state
  • projects/<project-id>/state.db for per-project state

New imports do not create <repo>/.xero/. That directory is legacy. Project skill artifacts also live in app data, under projects/<project-id>/skills and projects/<project-id>/dynamic-skills.

Agent memory also uses the OS app-data project store. The LanceDB-backed record/memory store is part of the Rust backend, which is why protoc is a build prerequisite.

App-level JSON state

Xero also stores UI/runtime-adjacent JSON files like:

  • window-state.json

Solana stores also use OS data dirs under xero/solana/... for personas/snapshots.

Server state

The Phoenix service uses the local Postgres database from server/docker-compose.yml (xero_dev by default). Current migrations cover Oban jobs and GitHub auth sessions.

Browser + Cookie Import Notes

The in-app browser supports tabbed automation, storage/cookie operations, screenshots, console/network diagnostics, accessibility snapshots, and state save/restore. Owned agents default to the in-app browser first and can fall back to native device-browser control when the browser-control preference allows it.

Cookie import helper supports detection/import from common browsers, including:

  • Chrome/Chromium/Brave/Edge
  • Opera/Opera GX/Vivaldi/Arc
  • Firefox/LibreWolf/Zen
  • Safari (macOS)

Troubleshooting

Tauri app fails to start in dev

  • Ensure pnpm --dir client install completed
  • Ensure protoc is installed and visible on PATH
  • Ensure Tauri OS prerequisites are installed
  • Ensure port 3000 is free (Vite dev server is strict on this port)

Root pnpm run dev fails before Tauri starts

  • Ensure Docker Desktop, Docker Engine, or a compatible Docker daemon is installed and running, or let the preflight start it where your OS allows
  • Ensure Elixir/Mix is installed for the Phoenix server
  • Inspect Postgres with docker logs xero-postgres
  • Run pnpm run dev:preflight to isolate setup failures

Emulator frames/status issues

  • For iOS, confirm Xcode/simctl are installed (macOS only)
  • For Android, confirm adb/emulator availability or run provisioning flow
  • If decoder unavailable errors appear, build/run with emulator-live feature

Sidecar download issues

  • Use XERO_SKIP_SIDECAR_FETCH=1 with pre-populated resources
  • Or allow network access during first build so build.rs can fetch pinned artifacts

Solana local cluster start failures

  • Verify solana (and surfpool for fork mode) are on PATH
  • Check toolchain status from Solana sidebar; missing tools are surfaced explicitly

Where to Start in Code

If you’re new to this repo, start here:

  1. client/src/App.tsx (top-level app orchestration)
  2. client/components/xero/shell.tsx (window shell + sidebar buttons)
  3. client/src/features/xero/use-xero-desktop-state.ts (state orchestration)
  4. client/src/lib/xero-desktop.ts (frontend adapter + invoke/event contract)
  5. client/src-tauri/src/lib.rs (backend command registration)
  6. client/src-tauri/src/commands/ (backend command namespaces)
  7. server/lib/xero_web/router.ex (Phoenix routes)
  8. server/lib/xero_web/controllers/ (server callback/API controllers)

Current Status Summary

This repository is actively structured around a Tauri desktop runtime with broad command surfaces for runtime orchestration, browser automation, mobile emulator control, Solana workflows, skills/plugins, and session memory. The server/ Phoenix app and local Postgres service support web callback/shared backend features. The landing/ app is a separate Next.js site used alongside (not instead of) the desktop host.

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 3

Xero 0.1.14 Latest
May 26, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages