APPLICATION

AbstractAssistant

A macOS-first tray app and CLI that hosts a local, durable agent. Gateway-first thin client with voice-enabled chat, tool approval workflows, multi-session support, and full voice mode — all driven from the system tray.

Get Started PyPI GitHub

pip install abstractassistant

# Launch the tray app
assistant

# Or run a single CLI turn
assistant run --prompt "What is in this repo?"

Overview

Gateway-First Thin Client

AbstractAssistant connects to AbstractGateway, discovers available providers and models there, and keeps only local UI and session state. The heavy lifting — agent loops, tool execution, and LLM calls — happens on the gateway.

Tray UI

A macOS menu bar app with chat bubble, sessions, file attachments, tool approval dialogs, and voice controls. Runs as a lightweight system tray icon with click-to-chat interaction.

CLI Mode

Run a single agentic turn in the terminal without the UI. Supports tool approval prompts, file attachments, and provider/model selection via CLI flags.

Durable Tool Boundary

Tool calls are surfaced as resumable durable waits. Safe read-only tools can auto-approve; writes, shell execution, and unknown tools require explicit user approval.

Voice Integration

Built-in TTS and STT via AbstractVoice. Full voice mode with mic-reactive listening, speaking animation, frequency-band meters, and tray-first voice controls.

Features

Your AI, Always at Hand

A comprehensive personal AI assistant that lives in your menu bar, with full voice, vision, and tool control capabilities.

Chat Bubble

A lightweight chat interface that appears from the tray icon. Send messages, view responses with markdown rendering, and attach files with drag-and-drop.

Tool Approval UI

Structured tool approval dialogs with tool name, key parameters, and approve/deny actions. Approve All mode auto-approves future tools for the session.

Multi-Session Support

Create and switch between multiple sessions. Each session persists its transcript, last run ID, and context under the data directory.

File Attachments

Attach images, audio, video, PDFs, and documents. Audio files are pre-transcribed via AbstractVoice. Images go through the multimodal media pipeline.

Full Voice Mode

Hands-free interaction driven from tray states: listening, thinking, speaking. Mic-reactive pulse animation scales with voice volume and shifts color for visual feedback.

Media Settings

Configure voice, TTS model, STT model, and image generation from gateway-discovered catalogs. Select voices, providers, and models from the settings dialog.

Workflow Picker

Select from gateway-discovered workflow entrypoints. Persisted per session so your preferred workflow is ready when you open the tray.

macOS App Bundle

Ship a helper that creates a native macOS app bundle under /Applications with proper icons and Launch Services integration.

Getting Started

Install and Launch

AbstractAssistant requires Python 3.10+ and an AbstractGateway instance for tray mode. CLI mode can run standalone.

Install

pip install abstractassistant

# Verify installation
assistant --help

Launch with Gateway

# Start the gateway first
export ABSTRACTGATEWAY_FLOWS_DIR="$PWD/abstractgateway/flows/bundles"
export ABSTRACTGATEWAY_AUTH_TOKEN="your-shared-token"
abstractgateway serve --host 127.0.0.1 --port 8080

# Launch the assistant (connects to gateway)
assistant

# Or with explicit gateway override
assistant --gateway-url http://127.0.0.1:8080 --gateway-token "$ABSTRACTGATEWAY_AUTH_TOKEN"

CLI Mode (No UI)

# Run a single agentic turn in the terminal
assistant run --prompt "What is in this repo and where do I start?"

# With provider override
assistant --provider ollama run --prompt "Explain this error"

macOS App Bundle

# Create a native macOS app bundle
create-app-bundle

API Reference

CLI & Architecture

AbstractAssistant exposes CLI commands, environment variables, and a durable agent host for tool-call boundary management.

CLI Commands

# Tray app (default command)
assistant

# Single-turn CLI
assistant run --prompt "..."

# Global flags (before subcommand)
assistant --provider ollama --data-dir ~/.myassistant run --prompt "..."

Environment Variables

ABSTRACTGATEWAY_URL               # Gateway base URL (default: http://127.0.0.1:8080)
ABSTRACTGATEWAY_AUTH_TOKEN         # Gateway auth token (required)
ABSTRACTGATEWAY_MAX_ATTACHMENT_BYTES # Max attachment size (default: 25 MiB)

Core Modules

`agent_host.py`

Durable agent backend with tool waits, approval flows, attachment handling, and run resume. The core execution boundary between UI and runtime.

`tool_policy.py`

Safe auto-approve vs require-approval tool policy. Read-only and search tools auto-approve; file writes, shell commands, and unknowns require user consent.

`session_index.py`

Multi-session registry stored at sessions.json. Tracks active session ID, creation timestamps, and session metadata.

`session_store.py`

Lightweight session.json snapshot store for transcript persistence. Saves last run ID for fast UX state restoration.

Data Directory

~/.abstractassistant/
  session.json       # Transcript snapshot + last run ID
  sessions.json      # Session registry + active session
  runtime/           # AbstractRuntime stores (ledger, artifacts)
  sessions/          # Per-session data directories