Skip to content
BranchesTags

Repository files navigation

ARIA

ARIA is a terminal-native, local-first relationship and inbox agent built in Python.

It connects to real Gmail and Google Calendar, syncs relationship context into a local store, drafts and sends email, tracks leads, reads local lead files, creates calendar events, and exposes the whole system through both a deterministic CLI and a Gemini-powered natural-language REPL.

The interactive model target is fixed to gemini-3.1-flash-lite-preview.

What ARIA Actually Does

ARIA combines these operating loops into one tool:

  1. inbox triage
  2. relationship memory
  3. lead pipeline tracking
  4. drafting, rewriting, sending, and scheduling email
  5. calendar awareness and calendar event creation
  6. daily and weekly operator briefings
  7. local file ingestion for lead discovery and import

The product is local-first:

  • Gmail is the live mail source of truth
  • Google Calendar is the live scheduling source of truth
  • Gemini is the reasoning layer for natural-language turns
  • ARIA's working state lives on your machine

Current v1 Capabilities

Gmail

  • real Gmail OAuth desktop auth
  • browser auth with manual fallback
  • real inbox sync
  • incremental sync with Gmail history IDs
  • full thread fetch
  • real send through Gmail
  • safe new-thread behavior for ad-hoc emails
  • live sync while the REPL is running

Google Calendar

  • calendar connection through the same Google auth flow
  • calendar overview for today, tomorrow, or the week
  • open-slot calculation
  • scheduling-aware draft suggestions
  • calendar event creation from natural time ranges

Examples:

  • tomorrow morning 5-9am ist
  • tomorrow 9am
  • in 2 hours

Inbox intelligence

  • thread classification: ACTION REQUIRED, LEAD, FOLLOW-UP NEEDED, WAITING ON REPLY, NOISE
  • latest-email handling by recency, not just priority
  • today-only inbox views
  • same-day prioritization
  • "why this matters" reasoning per thread

Current "why this matters" reasons include:

  • investor
  • partner
  • active lead
  • direct ask
  • replied today
  • deadline mention
  • meeting coordination
  • deal risk

Semantic relationship memory

ARIA maintains per-contact memory buckets such as:

  • facts
  • preferences
  • promises
  • topics
  • next steps

That memory is extracted from synced conversation history and then reused in:

  • contact views
  • draft generation
  • summaries
  • briefings

Leads and pipeline

  • add leads
  • move stages with confirmation
  • score leads
  • see pipeline summaries
  • auto-stage on reply
  • stage history for pipeline change reporting

Default stages:

  • PROSPECT
  • CONTACTED
  • REPLIED
  • QUALIFIED
  • PROPOSAL
  • CLOSED
  • LOST

Drafting and sending

  • follow-up drafts
  • cold outreach drafts
  • proposal drafts
  • breakup drafts
  • one-off custom drafts
  • draft editing
  • tone softening
  • bulk drafts by tag
  • send latest draft without specifying an ID
  • schedule sends using natural time input

Draft generation is also hardened so the model does not add duplicate closings like Best regards if you already have a saved signature.

Briefings and insights

  • daily brief
  • weekly brief
  • replied since last check
  • heating up leads
  • cooling relationships
  • pipeline changes
  • top actions for today
  • at-risk relationship view
  • wins view
  • usage stats

Local file ingestion

  • read a file or preview a folder
  • search inside files or folders
  • extract leads from CSV, TSV, JSON, JSONL, TXT, and MD
  • import those leads into contacts and pipeline

Diagnostics and reliability

  • aria doctor
  • aria doctor --json
  • local logs
  • schema-versioned state
  • automatic migration backups
  • atomic local writes
  • corrupt JSON recovery

What ARIA Does Not Do Yet

ARIA v1 is strong, but still intentionally narrow.

Not included yet:

  • non-Gmail mail providers
  • editing or deleting existing calendar events
  • background daemon for always-on scheduled email delivery
  • hosted multi-user SaaS deployment
  • web UI
  • encrypted local storage at rest

Quick Start

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install .
Copy-Item .env.example .env
aria

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install .
cp .env.example .env
aria

If you want the full non-technical walkthrough, use SETUP.md.

First-Run Setup

When you run aria without a completed setup, ARIA walks you through:

  1. Gemini API key
  2. Gmail / Google OAuth client setup
  3. browser sign-in
  4. manual OAuth fallback if browser callback does not complete
  5. name
  6. timezone
  7. signature

For users who want explicit auth commands:

aria auth status
aria auth gmail
aria auth gmail --link
aria auth gmail --manual

After Google scopes change, run aria auth gmail again to re-consent.

Requirements

  • Python 3.11+
  • GEMINI_API_KEY
  • Google Cloud project with Gmail API enabled
  • Google Calendar API enabled
  • Google OAuth desktop client

Runtime Location

By default ARIA stores state in:

  • Windows: C:\Users\<user>\.aria
  • macOS: /Users/<user>/.aria
  • Linux: /home/<user>/.aria

Override with:

  • ARIA_HOME

Typical files:

  • .env
  • aria.config.json
  • db.json
  • gmail-token.json
  • aria.log
  • optional gmail-client-secret.json

Environment Variables

Required

  • GEMINI_API_KEY

Google auth

Use either:

  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET

Or:

  • GMAIL_CLIENT_SECRETS_FILE

Optional:

  • GOOGLE_PROJECT_ID

Runtime tuning

  • ARIA_HOME
  • ARIA_ENV_FILE
  • GMAIL_OAUTH_HOST
  • GMAIL_OAUTH_PORT
  • GMAIL_OAUTH_TIMEOUT_SECONDS
  • GMAIL_INITIAL_SYNC_MAX_THREADS
  • GMAIL_SYNC_MAX_THREADS
  • GMAIL_LIVE_SYNC_INTERVAL_SECONDS

Command Surface

Run aria help for the current command summary.

Inbox

aria inbox
aria inbox --leads
aria inbox --cold --days 4
aria inbox --today
aria inbox --today --latest
aria inbox --today --summarize-latest
aria inbox --thread <thread-id>
aria inbox --summarize <thread-id>

Contacts

aria contacts
aria contacts --search Sarah
aria contact sarah@acme.ai
aria contact sarah@acme.ai --history
aria contact sarah@acme.ai --add-note "Met at SaaS meetup"
aria contact sarah@acme.ai --tag lead
aria contact sarah@acme.ai --delete

Leads

aria leads
aria leads --stage QUALIFIED
aria lead add someone@example.com
aria lead sarah@acme.ai --move PROPOSAL
aria lead sarah@acme.ai --score
aria pipeline --summary

Drafts

aria draft sarah@acme.ai --type follow-up
aria draft sarah@acme.ai --type cold-outreach
aria draft sarah@acme.ai --type proposal
aria draft sarah@acme.ai --type breakup
aria draft --to aaryan@example.com --name "Aaryan" --subject "Launch sync" --body "ARIA launches today. Can we connect ASAP to finalize launch strategy?"
aria draft --edit <draft-id> --body "Updated body"
aria draft --bulk investor
aria draft --soften <draft-id>
aria send [<draft-id>]
aria schedule [<draft-id>] --at "tomorrow 9am"
aria outreach --sequence sarah@acme.ai

Calendar

aria calendar
aria calendar --tomorrow
aria calendar --week
aria calendar --availability --days 3
aria calendar --create --title "Coding session" --time-range "tomorrow morning 5-9am ist"

Briefings and insights

aria brief
aria brief --weekly
aria brief --yesterday
aria insights
aria insights --at-risk
aria insights --wins
aria stats

Files and imports

aria file "leads.csv"
aria file "notes.md" --search "launch"
aria file "export-folder" --extract-leads
aria import leads "leads.csv" --stage QUALIFIED --tag investor,warm

Diagnostics

aria doctor
aria doctor --json
aria help

Using ARIA To Its Fullest

The best way to use ARIA is not as a single command launcher, but as a daily operator loop.

Best founder workflow

  1. start with the brief
aria brief
  1. inspect today's most important threads
aria inbox --today --latest
  1. open the most important thread and inspect why it matters
aria inbox --thread <thread-id>
  1. inspect the contact memory before you draft
aria contact <email>
  1. draft from context
aria draft <email> --type follow-up
  1. send or schedule with human-time phrasing
aria send
aria schedule --at "tomorrow 9am"
  1. check relationship health and pipeline drift
aria insights --at-risk
aria pipeline --summary

Best conversational workflow

Run:

aria

Then use short natural instructions:

  • summarize my latest important email from today
  • show me why it matters
  • draft a reply
  • rewrite it softer
  • send it
  • show me heating up leads
  • find open slots tomorrow
  • schedule a coding session for tomorrow morning 5-9am ist

Inside the REPL, literal CLI commands also work:

  • aria auth gmail
  • aria calendar --week
  • aria doctor

How The Interactive Agent Works

When you run aria with no subcommand:

  1. ARIA loads local state
  2. ARIA starts the Gemini REPL
  3. Gemini chooses local tools
  4. ARIA executes real handlers
  5. ARIA returns grounded results from your local DB, Gmail, Calendar, and files

The REPL is not freeform fake chat. It is a tool-calling layer over the real product.

Internal tool families include:

  • inbox triage
  • contact lookup and update
  • lead pipeline
  • draft creation and edit
  • send and schedule
  • outreach sequence generation
  • briefings and insights
  • auth control
  • calendar access
  • local files

Live Sync Behavior

While the REPL is open, ARIA starts a background sync loop.

That means:

  • new Gmail mail can appear during the session
  • due scheduled sends can be processed during the session
  • the local DB updates without restarting ARIA

This is live polling, not Gmail webhook push.

Safety Model

ARIA confirms risky actions before mutating important state:

  • send email
  • schedule email
  • delete contacts
  • move leads

In non-interactive contexts, those confirmations now fail closed instead of crashing.

Local Persistence

ARIA persists:

  • contacts
  • semantic memory
  • notes
  • tags
  • threads
  • drafts
  • scheduled drafts
  • lead stages
  • stage history
  • auth state
  • counters
  • config

ARIA does not vanish when you close it.

Reliability and Production Hardening

Recent hardening work includes:

  • schema-versioned config and DB
  • automatic migration backups
  • atomic writes for config, DB, and env
  • corrupt JSON recovery
  • local runtime logs
  • aria doctor diagnostics
  • safer non-interactive confirmations
  • timezone-correct schedule parsing and rendering
  • direct REPL passthrough for literal aria ... commands

Testing and Evals

Compile check:

python -m compileall src test eval

Smoke tests:

python test\smoke.py

Quick evals:

python eval\run_evals.py --scale quick

Standard benchmark:

python eval\run_evals.py --scale standard

Fullest currently implemented eval:

python eval\run_evals.py --scale full --with-live-model

Eval artifacts are written to eval/runs/.

Most useful output:

  • summary.svg

Eval coverage includes:

  • inbox recency
  • lead import
  • draft/send safety
  • transcript continuity
  • persistence
  • adversarial resilience
  • optional live-model turns

See eval/README.md for the benchmark details.

Project Structure

src/
  aria.py
  aria_core/
    app.py
    defaults.py
    gmail.py
    parser.py
    runtime.py
    storage.py
    time_utils.py
test/
  smoke.py
eval/
  run_evals.py
  scenarios.py
SETUP.md
README.md
how-it-works.md
pyproject.toml

Important Files

Troubleshooting

If something feels off, start with:

aria doctor

Common fixes:

  • rerun aria auth gmail after Google scope changes
  • rerun pip install . after code updates
  • check aria.log in ARIA_HOME
  • check aria doctor --json

Demo Flow

If you want the tightest product demo, use this structure:

  1. aria inbox --today --latest Show that ARIA surfaces what matters and explains why.

  2. aria contact <priority-contact> Show semantic memory, not just raw thread history.

  3. aria brief Show the operator view: replied since last check, heating up, cooling, pipeline changes, and today's actions.

  4. aria draft <priority-contact> --type follow-up Show relationship-aware drafting.

  5. aria calendar --availability --days 3 Show calendar context.

  6. aria calendar --create --title "Coding session" --time-range "tomorrow morning 5-9am ist" Show natural-time calendar creation.

  7. aria Ask one strong natural-language instruction such as: summarize my latest important email from today and draft the reply

I’ve also included a fresh, tighter demo plan in the response to your current request below.

About

crm claude code

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages