Your Local AI Sales Agent
Autonomous lead generation, outreach, and deal closing — running entirely on your desktop.
Quick Start · Features · Architecture · Technical Docs · User Manual
Aura is a desktop AI sales agent that automates the entire B2B lead generation pipeline — from finding prospects to closing deals. It runs locally on your machine with a fleet of 20 specialized AI agents that handle prospecting, research, outreach, follow-ups, invoicing, and even voice calls.
Unlike cloud SaaS tools, Aura keeps your data local (SQLite), your API keys encrypted (machine-bound AES), and gives you full control over autonomy levels — from observer mode to full autopilot.
Find leads → Enrich & qualify → Deep research → Draft personalized emails
→ Send sequences → Detect replies → Classify intent → Handle objections
→ Follow up → Close deal (or) → Voice call as last resort
Every step is automated. Every step is configurable. Every step requires your approval until you say otherwise.
# Install from source (recommended)
git clone https://github.com/Etriti00/aura-app.git
cd aura-app
pip install .
# Or install in editable/dev mode
pip install -e .
# Install the browser engine (needed for web scraping)
playwright install chromiumAfter installation, the aura command is available globally:
$ aura status
Aura v2.1.0 — System Status
───────────────────────────────
Campaigns 0
Leads 0
Agents 20
$ aura help
$ aura hunt "plumber" --city "Austin TX"
$ aura # starts interactive REPL# Option A: Download pre-built executable
# → https://github.com/Etriti00/aura-app/releases
# Windows: Aura.exe | macOS: Aura.app | Linux: ./Aura
# Option B: Install from source with GUI
git clone https://github.com/Etriti00/aura-app.git
cd aura-app
pip install ".[gui]"
playwright install chromium
aura-gui| Platform | CLI Install | GUI Install | Build |
|---|---|---|---|
| Windows | pip install . → aura |
pip install ".[gui]" → aura-gui |
pyinstaller aura.spec → dist\Aura\Aura.exe |
| macOS | pip install . → aura |
pip install ".[gui]" → aura-gui |
pyinstaller aura.spec → dist/Aura.app |
| Linux | pip install . → aura |
pip install ".[gui]" → aura-gui |
pyinstaller aura.spec → dist/Aura/Aura |
Prerequisites: Python 3.10+ and Git.
On first launch, configure at least one AI API key:
# CLI
aura config-api-keys
# GUI
# The Setup Wizard opens automatically on first run- AI Provider Key — Anthropic (Claude), OpenAI, or Google (Gemini)
- Sender Identity —
aura config-set sender_name "Your Name" - Email Delivery —
aura config-smtp
All API keys are encrypted with machine-bound AES-256. They never leave your device.
- Multi-source scraping — DuckDuckGo, Google Maps, Yelp
- API integrations — Apollo.io, Hunter.io, HubSpot CRM
- CSV imports — LinkedIn Sales Navigator exports, batch files
- Auto-enrichment — Email finder, phone lookup, website analysis
- AI qualification — Automatic lead scoring with LLM-powered assessment
- Multi-provider intelligence — Tavily, Firecrawl, Apify
- LLM synthesis — Generates company overview, pain points, tech stack, gaps & opportunities
- Auto-depth selection — Quick research for low-score leads, deep dive for high-potential
- Research-powered emails — Drafts reference actual company data, competitor gaps, and pain points
- Multi-step sequences — Automated follow-up cadences with customizable delays
- Reply detection — IMAP polling classifies intent (interested, objection, not interested, question, unsubscribe)
- Conversation engine — Multi-turn thread management with objection handling
- A/B testing — Compare subject lines and email variants
- 20 specialized agents — Prospector, Qualifier, Closer, Researcher, Accountant, Caller, and more
- Rank-based hierarchy — Commander (C-Level) → Specialists → Workers
- Task routing — 25+ task types automatically dispatched to the right specialist
- Ticket system — Kanban board with escalation, dependencies, and due dates
- Self-improvement — Agents learn from performance metrics and reflection scores
- Twilio integration — WebSocket media streams for real-time audio
- TTS cascade — ElevenLabs → OpenAI → Piper (local fallback)
- STT — Whisper (local or API)
- Auto-trigger — Detects stalled leads (3+ failed emails or 7+ days silent)
- Always requires approval — Even at full-trust autonomy level
- Per-install encryption salt — Unique random salt per installation (auto-migrates from legacy)
- Key migration — Automatic re-encryption of legacy ciphertext to new per-install salt
- LLM retry with backoff — Exponential backoff on transient errors (429, 503, timeouts)
- Thread-safe database — Serialized writes prevent SQLite locking errors
- Thread-safe delivery counter — Atomic daily send limit with
threading.Lock - Browser lifecycle management — Context-managed Playwright with batch mode and stealth for bulk operations
- IMAP connection pooling — Persistent connections with automatic stale detection and reconnect
- Resource cleanup on error — SMTP and IMAP connections always closed via
try/finally - HTML injection prevention — Email body escaped before HTML embedding
- Database indexes — 15 indexes on frequently queried columns for faster lookups
- Graceful shutdown —
closeEventstops all timers, fleet, gateways, and batch browser on exit - GPU-aware scheduling — Ollama calls serialized via semaphore for single-GPU machines
- Thread-safe safety guard — All mutable counters protected by locks
- 4 autonomy levels — Observer, Supervised, Autonomous, Full Trust
- Approval queue — Review and approve/deny any action before execution
- Budget controls — Daily spend limits with automatic tier downgrade
- Rate limiting — Per-provider API queues prevent throttling
- Telegram bot — Control Aura from Telegram with natural language commands
- Discord bot — Same capabilities via Discord server
- Command palette —
Ctrl+Kfuzzy search across all 14 pages - Cross-page navigation — Deep links between pages with context passing
- Dashboard — Real-time campaign stats, funnel visualization, conversion rates
- Trends — Google Trends integration for market intelligence
- Budget tracking — Per-model cost breakdown, daily/monthly projections
- Command history — Full audit trail with tree visualization
The CLI provides 81 commands across 17 groups with full feature parity to the GUI. Run aura to start the interactive REPL, or aura <command> for one-shot execution.
$ aura
Aura v2.1.0 — AI Sales Agent
Type /help for commands, or type naturally.
aura> /hunt plumber --city "Austin TX" --limit 20
aura> /qualify 1
aura> /draft 1
aura> /send 1
aura> find me SaaS leads in healthcare ← natural language works too
| Group | Commands | Description |
|---|---|---|
| Pipeline | /hunt, /qualify, /enrich, /draft, /send, /replies, /sequence |
Core lead-to-email pipeline |
| Campaigns | /campaigns, /campaign-create, /campaign-status, /campaign-pause, /campaign-resume, /export-csv, /export-pdf |
Campaign management and export |
| Leads | /leads, /lead-detail, /lead-lifecycle, /lead-search, /case |
Lead management and case files |
| Fleet | /fleet-status, /fleet-boot, /fleet-shutdown, /agents, /agent-assign, /goals, /goal-create, /reflections, /knowledge-graph, /conversations, /ask, /improvement |
AI agent fleet operations |
| Kanban | /tickets, /ticket-create, /ticket-update, /ticket-comment, /ticket-stats |
Ticket/task management |
| Skills | /skills, /skill-detail |
AI skill registry |
| Research | /research, /research-report, /research-queue |
Lead research intelligence |
| Voice | /call, /call-log, /call-transcript |
Voice call management |
| Budget | /budget, /budget-set, /token-usage |
Cost pacing and token tracking |
| Trends | /trends, /trends-opportunities, /trends-alerts |
Google Trends market intelligence |
| Autonomy | /autonomy-level, /autonomy-set, /approvals, /approve, /deny |
Agent autonomy controls |
| Suppression | /suppression-list, /suppress, /unsuppress |
Email suppression management |
| Integrations | /gateway-status, /gateway-connect, /gateway-disconnect, /crm-sync, /gateway-auth |
Telegram, Discord, CRM |
| History | /history, /history-detail, /history-tree |
Command audit trail |
| Config | /config, /config-set, /config-api-keys, /config-smtp |
Settings management |
| Knowledge | /knowledge-add, /knowledge-list, /knowledge-remove, /memory-rules, /memory-stats, /memory-clear |
Knowledge base & correction memory |
| System | /help, /status, /version, /clear, /exit |
System utilities |
# Hunt leads
aura hunt "SaaS companies" --city "San Francisco" --limit 100
# Check campaign stats
aura campaign-status 1
# Show system status
aura status
# Get help
aura help pipeline
# Verbose mode (show engine logs)
aura --verbose status┌─────────────────────────────────────────────────────────┐
│ Interface Layer (GUI or CLI) │
│ GUI: PySide6 (14 Pages, Chat Panel, Sidebar) │
│ CLI: REPL + 75 commands (no PySide6 required) │
├─────────────────────────────────────────────────────────┤
│ Controller Layer │
│ GUI: 19 QObject controllers with Signal/Slot wiring │
│ CLI: Direct engine calls (bypasses controllers) │
├─────────────────────────────────────────────────────────┤
│ Core Engine Layer │
│ 50+ specialized engines (business logic) │
├─────────────────────────────────────────────────────────┤
│ Database Layer │
│ SQLAlchemy ORM │ SQLite (WAL mode) │ 30+ tables│
├─────────────────────────────────────────────────────────┤
│ External Services │
│ LiteLLM │ Apollo │ Twilio │ Telegram │ Discord │ IMAP │
└─────────────────────────────────────────────────────────┘
aura-app/
├── main.py # GUI entry point
├── cli.py # CLI entry point (75 commands, REPL)
├── config.py # All constants, paths, design tokens
├── aura.spec # PyInstaller build configuration (cross-platform)
├── pyproject.toml # Python packaging (pip install -e .)
├── requirements.txt # Full dependencies (GUI + CLI)
├── requirements-cli.txt # CLI-only dependencies (no PySide6)
│
├── core/ # 50+ business logic engines
│ ├── ai_engine.py # LLM orchestration (generate, qualify, classify)
│ ├── agent_engine.py # Agent task execution with context building
│ ├── fleet_orchestrator.py # Multi-agent dispatch and coordination
│ ├── orchestrator_engine.py # Natural language command → action mapping
│ ├── scraper_engine.py # Multi-source web scraping
│ ├── delivery_engine.py # Email delivery (Resend + SMTP)
│ ├── research_engine.py # Multi-provider research orchestration
│ ├── voice_call_engine.py # Twilio WebSocket voice calling
│ ├── router_engine.py # 4-tier LLM routing (local→ollama→haiku→sonnet)
│ ├── rag_engine.py # TF-IDF + optional ChromaDB retrieval
│ ├── voice/ # TTS (ElevenLabs, OpenAI, Piper) + STT (Whisper)
│ ├── gateway_adapters/ # Telegram + Discord bot adapters
│ ├── enrichment_layers/ # DNS, Ollama, free APIs, deep crawl enrichment
│ └── ... # 40+ more engines
│
├── controllers/ # 19 signal-based UI controllers
│ ├── hunter_controller.py
│ ├── outreach_controller.py
│ ├── fleet_controller.py
│ ├── autonomy_controller.py
│ └── ...
│
├── ui/
│ ├── main_window.py # Application shell + engine wiring
│ ├── setup_wizard.py # First-run configuration
│ ├── pages/ # 14 full-page views
│ │ ├── dashboard.py # Campaign analytics
│ │ ├── hunter.py # Lead discovery
│ │ ├── forge.py # AI persona management
│ │ ├── outreach.py # Email campaigns
│ │ ├── fleet.py # Agent monitoring
│ │ ├── kanban.py # Task board
│ │ ├── research.py # Research reports
│ │ ├── calls.py # Voice call management
│ │ └── ... # 6 more pages
│ └── components/ # Reusable widgets
│ ├── sidebar.py
│ ├── chat_panel.py
│ ├── command_palette.py
│ └── ...
│
├── database/
│ ├── schema.py # 50+ SQLAlchemy models
│ ├── db_manager.py # Session factory, WAL mode, thread-safe writes
│ ├── migrations.py # ALTER TABLE migrations for backward compat
│ ├── seed_agents.py # 20 agent definitions + hierarchy setup
│ └── seed_skills.py # Built-in skill & settings seeding
│
├── assets/
│ ├── themes/ # QSS stylesheets (dark + light)
│ ├── icons/ # Application icon
│ └── templates/ # CSV import templates
│
├── scripts/ # Build scripts (cross-platform, macOS icon, Linux installer)
│ ├── build.py # Cross-platform build automation
│ ├── build_icns.sh # macOS icon generation
│ └── linux/ # Linux desktop entry + installer
│
└── tests/ # 1250+ tests across 50+ files
├── conftest.py # Fixtures (in-memory DB, QApp)
└── test_*.py # Comprehensive coverage
| Component | Technology |
|---|---|
| Desktop Framework | PySide6 (Qt 6) |
| Database | SQLAlchemy + SQLite (WAL mode) |
| LLM Routing | LiteLLM (Anthropic, OpenAI, Google, Ollama) |
| Email Delivery | Resend API + SMTP fallback |
| Web Scraping | Playwright + BeautifulSoup |
| Voice Calls | Twilio + WebSocket media streams |
| TTS | ElevenLabs, OpenAI, Piper (local) |
| STT | Whisper (local via faster-whisper, or API) |
| Encryption | AES-256 via cryptography (machine-bound, per-install salt) |
| CLI | 75 commands, REPL, natural language fallback |
| Packaging | PyInstaller (OneDir), cross-platform (Win/macOS/Linux) |
All configuration lives in config.py. Key settings you may want to adjust:
| Setting | Default | Description |
|---|---|---|
MAX_DAILY_EMAILS |
100 | Daily outbound email limit |
FOLLOWUP_CHECK_INTERVAL_MS |
1,800,000 | Follow-up sequence check interval (30 min) |
REPLY_CHECK_INTERVAL_MS |
7,200,000 | IMAP reply check interval (2 hours) |
ESCALATION_CHECK_INTERVAL_MS |
300,000 | Ticket escalation check (5 min) |
AGENT_CONTEXT_MAX_TOKENS |
8,000 | Max context tokens per agent task |
CALLER_FAILED_EMAIL_THRESHOLD |
3 | Failed emails before voice call eligibility |
CALLER_STALLED_DAYS |
7 | Days silent before stalled-lead detection |
Runtime settings (API keys, toggles, sender identity) are configured in the Settings page within the app.
venv\Scripts\activate
pyinstaller aura.spec --noconfirm
# Output: dist/Aura/Aura.exesource venv/bin/activate
# Generate .icns icon (optional, requires iconutil)
bash scripts/build_icns.sh
# Build
pyinstaller aura.spec --noconfirm
# Output: dist/Aura.appsource venv/bin/activate
pyinstaller aura.spec --noconfirm
# Output: dist/Aura/Aura
# Optional: System-wide install
sudo bash scripts/linux/install.shpython scripts/build.pyThe build bundles all assets, themes, fonts, and dependencies into a self-contained directory.
# Run full test suite
venv\Scripts\python.exe -m pytest tests/ -v --tb=long
# Run a specific test file
venv\Scripts\python.exe -m pytest tests/test_agent_engine.py -v
# Run tests matching a pattern
venv\Scripts\python.exe -m pytest tests/ -k "test_stalled" -vCurrent status: 1250+ tests across 50+ files — 100% passing.
| Document | Description |
|---|---|
| Technical Documentation | Architecture deep-dive, engine reference, database schema, security model |
| User Manual | Page-by-page walkthrough, feature toggles, keyboard shortcuts, troubleshooting |
Aura works with any combination of these LLM providers:
| Provider | Models | Use Case |
|---|---|---|
| Anthropic | Claude Haiku, Sonnet | Primary (recommended) |
| OpenAI | GPT-4o, GPT-4o-mini | Alternative |
| Gemini Pro, Flash | Alternative | |
| Ollama | Any local model | Privacy-first, free tier |
The 4-tier router automatically selects the optimal model based on task complexity and budget:
Tier 1 (Local) → Tier 2 (Haiku/Flash) → Tier 3 (Sonnet/GPT-4o) → Tier 4 (Opus)
Free ~$0.001/task ~$0.01/task ~$0.10/task
Budget pacing automatically downgrades tiers when daily spend approaches limits.
Contributions are welcome. To get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Make your changes
- Run the test suite (
pytest tests/ -v) - Commit (
git commit -m "Add your feature") - Push (
git push origin feature/your-feature) - Open a Pull Request
Please ensure all tests pass before submitting.
- Correction Memory Engine — Detects user corrections ("no, I meant X") and learns rules that persist across conversations. Agents automatically inject learned rules into their context
- Knowledge Base Engine — Store and retrieve business knowledge entries (products, competitors, pricing, processes). New Settings tab for managing entries with search
- Per-Agent Auto-Memory — Each agent automatically stores and retrieves learned behaviors in per-agent memory logs, injected into agent context during task execution
- Knowledge CLI commands —
/knowledge-add,/knowledge-list,/knowledge-remove,/memory-rules,/memory-stats,/memory-clear - Audit fixes — Fixed CLI
/enrichcrash (int→dict), gateway platform hardcoding, Telegram key mismatch, GMaps API key decryption, missing orchestrator intents, Whisper temp file leak - Missing PyInstaller imports — Added
skill_registry,hubspot_engine,linkedin_engine,icons,command_palettetoaura.spec - Version: 2.0.0 → 2.1.0 across
config.py,pyproject.toml,aura.spec - Tests: 1200 → 1250+ tests (50+ new tests across 2 new test files)
- Multi-platform response formatting — ResponseFormatter renders agent output for Telegram (HTML), Discord (Markdown), Chat (rich text), and CLI (plain text)
- 4-layer enrichment pipeline — DNS/WHOIS (Layer 0), Ollama local LLM (Layer 1), free APIs (Layer 2), deep web crawl (Layer 4) with weighted completeness scoring
- Excel export engine — Professional .xlsx exports with multiple sheets (summary, leads, agents, timeline), auto-column-width, styled headers, and charts
- Pricing + invoice system — Service CRUD, invoice generation (PDF via ReportLab or text fallback), approval flow with rank-based escalation, revenue summaries. New Accountant agent (20th agent)
- Discord server mode — Auto-create notification channels (#leads, #campaigns, #fleet, #alerts, #reports), event→channel routing with embeds, config persistence
- Telegram command system — 12 slash commands (/status, /hunt, /leads, /agents, /draft, /send, /campaigns, /budget, /approve, /deny, /help, /settings) with inline keyboards
- Business & Invoicing settings — New Settings tab with company info, banking details, and invoice configuration (16 fields for agent context and invoice generation)
- Tabbed Settings page — Restructured from single scroll into 6 sub-tabs: API Keys, AI Config, Email & Delivery, Features, Business & Invoicing, Appearance
- Schema expansion — 5 new models (Service, Invoice, InvoiceLineItem, FinanceNote, DiscordServerConfig), expanded Lead/EnrichmentData/Settings
- Tests: 959 → 1200 tests (241 new tests across 8 new test files)
- Advanced CLI: Complete rewrite of
cli.py— 75 commands across 16 groups with full GUI parity - Easy install:
pip install .→auracommand available globally (CLI-only, no PySide6 required) - GUI as optional:
pip install ".[gui]"→ includes PySide6 for desktop app - Clean output: Zero noise by default — no warnings, no INFO logs. Use
--verbosefor debug output - REPL mode: Interactive
aura>prompt with/helpsystem, fuzzy command matching, ANSI formatting - Natural language: Type plain English in the REPL — orchestrator parses intent and executes
- One-shot mode:
aura hunt "plumber" --city "Austin TX"runs a single command and exits - Full engine init: CLI initializes all 50+ engines (mirrors
main_window.pyexactly) - Cross-platform: Platform-aware
aura.spec(Windows .exe, macOS .app bundle, Linux executable) - macOS icon:
scripts/build_icns.shgenerates.icnsfrom PNG - Linux installer:
scripts/linux/install.sh+.desktopfile for system-wide install - Build script:
scripts/build.pycross-platform build automation - CI/CD: GitHub Actions matrix build for Windows, macOS, and Linux
- PySide6-optional:
navigation_service.pyandthread_worker.pywork without Qt
- Key migration:
KeyVault.migrate_ciphertext()re-encrypts legacy-salt keys with new per-install salt on startup - Batch browser wiring: Hunter controller now calls
start_batch()/end_batch()around enrichment loops - Stealth in batch path:
playwright_stealthapplied to batch browser pages (not just single-page mode) - Thread-safe delivery:
DeliveryEnginedaily counter usesthreading.Lockwith atomic_increment_daily() - SMTP leak fix: All SMTP connections wrapped in
try/finallywithserver.quit() - HTML escape: Email body HTML-escaped before embedding to prevent XSS injection
- IMAP leak fix: Triage engine IMAP connections wrapped in
try/finallywithmail.logout() - Database indexes: 15 indexes on frequently queried columns (leads, agent_tasks, tickets, command_log)
- Graceful shutdown:
MainWindow.closeEvent()stops timers, fleet, IMAP, gateways, batch browser, voice engine - Consolidated migrations: Removed dual migration system — all column migrations now in
database/migrations.py - Tests: 935 → 959 tests (24 new audit round 2 hardening tests)
- Security: Per-install random encryption salt replaces hardcoded salt; automatic key migration from v1.0
- LLM resilience: Exponential backoff retry (up to 3 attempts) on transient LLM errors (429, 503, timeouts)
- Thread safety: Database writes serialized via
threading.RLock; safety guard counters protected by locks - Browser management: Context-managed Playwright lifecycle with batch mode for bulk enrichment
- IMAP pooling: Persistent IMAP connections with keepalive checks and stale connection recovery
- GPU scheduling: Ollama calls serialized via semaphore to prevent GPU contention
- Codebase refactor: Extracted
db_manager.py(1400+ lines) intomigrations.py,seed_agents.py,seed_skills.py - Dev tooling: Added
requirements-dev.txtfor test/lint dependencies - Tests: 853 → 935 tests (added
test_hardening_fixes.pywith 82 new tests)
- Full B2B lead generation pipeline with 20 AI agents
- Multi-source lead discovery, deep research, outreach automation
- Voice calling, ticket system, 4-tier LLM routing, autonomy controls
Distributed under the MIT License. See LICENSE for more information.
- PySide6 — Desktop UI framework
- LiteLLM — Universal LLM API proxy
- SQLAlchemy — Python SQL toolkit
- Playwright — Browser automation
- Twilio — Voice calling infrastructure
Built with Python and a fleet of AI agents.
Aura v2.1.0