Getting Aaka running

Two ways in: let Claude Code do it (recommended, ~5 minutes), or clone and run it by hand. Either way, everything lives on your machine — nothing is uploaded to us.

Before you start

• A Mac (fully supported) or a Linux box.
• Python 3.11+ and git.
• A Google account for calendar — authorized locally, optional at first.
• Claude Code if you want the guided install.
• Optional: a $5 VPS if you want it answering while your Mac sleeps.

Path A — install by talking to Claude

Open Claude Code in a folder where you keep projects, and paste:

Install Aaka from github.com/prasadgupte/aaka-life

Claude reads the repo's setup guide and walks you through it:

1. Fetch — clones the repo, checks Python and your Google account.
2. Name it — tell it what to call your assistant; that's how it shows up in your family chat.
3. Connect Google (locally) — you authorize once; the token is stored under ~/.aaka/tokens and never leaves your machine.
4. Choose skills — calendar, tasks, lists, notes, files. Turn on what you need.
5. Pick a channel — Telegram or WhatsApp (below).

Path B — install by hand

Nothing here requires Claude. The same deploy script sets everything up:

git clone https://github.com/prasadgupte/aaka-life ~/aaka-repo
cd ~/aaka-repo
export AAKA_CONFIG_DIR=~/.aaka
mkdir -p $AAKA_CONFIG_DIR/{config,tokens,data/{queue,calendar},logs}
# drop your Google credentials.json into $AAKA_CONFIG_DIR/tokens/
bash admin/aaka.sh deploy

Then run python3 aaka_config.py to verify your config.

Start small — the four tiers

You don't have to do it all at once. Each tier adds capability:

• Tier 0 — Telegram only. Lists, notes, tasks. A five-minute win.
• Tier 1 — add Google Calendar (local OAuth). Schedule reads and event writes.
• Tier 2 — add an LLM key (Claude or Gemini) for natural-language parsing.
• Tier 3 — add a VPS so it answers while your Mac is asleep.

Channels

Telegram — message @BotFather (opens in a new tab), tap New Bot, and paste the token it gives you when Claude (or the setup script) asks. Your family texts that bot.

WhatsApp — scan one QR to link a session. No token needed.

Always-on (optional VPS)

The stateless part (the message receiver) can run on a small VPS in Docker via docker-compose.prod.yml, while the part that holds your tokens stays on your Mac. So even the internet-facing half holds no secrets. See the repo's docs/ for the VPS walkthrough.

Where your data lives

Everything sits under ~/.aaka/ on your machine — config, calendar snapshots, the SQLite queue, and tokens. No cloud account. You can read any of it with cat.

Full source and the deepest docs: github.com/prasadgupte/aaka-life (opens in a new tab). Stuck? Get in touch.