{"id":50460756,"url":"https://github.com/manu14357/tota-agent","last_synced_at":"2026-06-01T04:30:26.047Z","repository":{"id":356362108,"uuid":"1231053314","full_name":"manu14357/tota-agent","owner":"manu14357","description":"Open-source AI agent: 11 LLM providers (OpenAI, Claude, Ollama, DeepSeek…), 60+ tools, web search, vision, browser \u0026 Android automation, MCP plugins, Second Brain memory — CLI · Telegram · WhatsApp · REST API","archived":false,"fork":false,"pushed_at":"2026-05-23T06:58:35.000Z","size":4186,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-23T08:28:41.153Z","etag":null,"topics":["ai-agent","anthropic","automation","cli","coding-agent","deepseek","developer-tools","llm","mcp","memory","nodejs","ollama","openai","personal-assistant","productivity","second-brain","sqlite","telegram-bot","typescript","whatsapp-bot"],"latest_commit_sha":null,"homepage":"https://tota-agent.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manu14357.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T15:22:22.000Z","updated_at":"2026-05-23T06:58:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/manu14357/tota-agent","commit_stats":null,"previous_names":["manu14357/tota-agent"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/manu14357/tota-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manu14357%2Ftota-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manu14357%2Ftota-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manu14357%2Ftota-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manu14357%2Ftota-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manu14357","download_url":"https://codeload.github.com/manu14357/tota-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manu14357%2Ftota-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33760645,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","automation","cli","coding-agent","deepseek","developer-tools","llm","mcp","memory","nodejs","ollama","openai","personal-assistant","productivity","second-brain","sqlite","telegram-bot","typescript","whatsapp-bot"],"created_at":"2026-06-01T04:30:25.305Z","updated_at":"2026-06-01T04:30:26.042Z","avatar_url":"https://github.com/manu14357.png","language":"TypeScript","funding_links":["https://github.com/sponsors/manu14357"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"tota-agent\" src=\"public/tota-agent-txt.png\" width=\"340\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAI agent built for control: permissioned tools, safe execution, token budgets, and multi-channel access.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Remembers what matters. Asks before it acts. Runs 24/7 from CLI, Telegram, WhatsApp, REST API, or **local web UI**.\u003cbr\u003e\n  60+ built-in tools · Web search · Vision · Code sandbox · Browser automation (36 tools) · Computer-use · Android control · Document readers · MCP plugins · Extensible skills · SQLite-backed Second Brain memory · 12 LLM providers (NVIDIA NIM, OpenRouter, DeepSeek, OpenAI, Anthropic, Grok, Groq, Ollama, MiMo…).\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003c!-- Version \u0026 downloads --\u003e\n  \u003ca href=\"https://www.npmjs.com/package/tota-agent\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/tota-agent?color=blue\u0026label=npm\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/tota-agent\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/tota-agent?color=blue\u0026label=total%20downloads\" alt=\"npm total downloads\"\u003e\u003c/a\u003e\n  \u003c!-- CI \u0026 Security --\u003e\n  \u003ca href=\"https://github.com/manu14357/tota-agent/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/manu14357/tota-agent/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/manu14357/tota-agent/actions/workflows/security.yml\"\u003e\u003cimg src=\"https://github.com/manu14357/tota-agent/actions/workflows/security.yml/badge.svg\" alt=\"Security\"\u003e\u003c/a\u003e\n  \u003c!-- Meta --\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/node/v/tota-agent\" alt=\"node\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/manu14357/tota-agent/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/manu14357/tota-agent\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/manu14357/tota-agent\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/manu14357/tota-agent?style=social\" alt=\"stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/manu14357\"\u003e\u003cimg src=\"https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=github-sponsors\" alt=\"sponsor\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\nInstall globally (recommended — makes `tota` available everywhere):\n\n```bash\nnpm i -g tota-agent\ntota\n```\n\nOr try it once without installing:\n\n```bash\nnpx tota-agent\n```\n\n\u003e **Note:** `npx tota-agent` runs tota in a temporary session only.  \n\u003e The `tota` command will **not** be available after that session ends.  \n\u003e Use `npm i -g tota-agent` for a permanent install.\n\n\u003e **Upgrading from the old `@manu14357/tota-agent` package?**\n\u003e The package was renamed to `tota-agent` (unscoped). The old binary shim blocks the new install on Windows.\n\u003e Uninstall the old package first, then reinstall:\n\u003e ```bash\n\u003e npm uninstall -g @manu14357/tota-agent\n\u003e npm i -g tota-agent\n\u003e ```\n\nFirst run launches the setup wizard — enter your name, an API key, and optionally a Telegram bot token. Takes about 30 seconds.\n\nTo reconfigure at any time:\n\n```bash\ntota doctor\n```\n\nOr configure just one feature without running the full wizard:\n\n```bash\ntota setup websearch    # add a web search key\ntota setup telegram     # change your Telegram bot\ntota setup llm          # swap LLM provider\ntota setup browser      # install Chromium, Firefox, WebKit browser binaries\ntota setup computer     # enable computer-use \u0026 Android ADB tools\ntota setup api          # enable the REST API channel\ntota ui                 # open the local web UI (http://127.0.0.1:3001)\n```\n\n---\n\n## Why tota?\n\nEvery AI agent can read files and run commands. Most do it silently. **tota asks first — and remembers what matters.**\n\n| Feature | What it means |\n|---------|--------------|\n| **Permission-hardened** | Shell blocklist, folder-level scoping, per-session approval modes. No surprises. |\n| **Second Brain** | Persistent SQLite memory with FTS5 search. 10 memory types. Learns your preferences automatically. |\n| **Soul-driven** | Personality from markdown files you own (`~/.tota/soul/`). No corporate wrapper. |\n| **Token-aware** | Daily budget with auto-concise at 70%. `/budget` command to check, reset, or override. |\n| **Live streaming** | Real-time token streaming on CLI with markdown re-render. Telegram streaming with editable messages. |\n| **Always on** | Daemon mode with crash recovery and system service (macOS, Linux, Windows). |\n| **Web search** | Built-in web search via Brave, Serper, or Tavily. Auto-detects from env keys. |\n| **Vision** | Analyze local images and URLs with your AI provider's vision capabilities. |\n| **Code sandbox** | Execute Python, JavaScript, Bash, TypeScript, Ruby, and Go in an isolated temp sandbox. |\n| **Document readers** | Read PDF, Excel (.xlsx/.csv), and Word (.docx) files — text, tables, metadata. |\n| **Advanced file finder** | Find files by glob, content keyword, type, date range, and size across deep directory trees. |\n| **Browser automation** | Full Playwright browser — Chromium, Firefox, or WebKit. Open pages, click, type, hover, drag, select, scroll, evaluate JS, manage cookies \u0026 storage, export PDF, set viewport. Switch engines mid-session. |\n| **Computer-use** | See your screen via vision AI, then click, type, scroll, drag, and press keys anywhere on the desktop. macOS, Linux, and Windows. |\n| **Android control** | ADB-powered Android device control — tap, swipe, type, key events, shell commands, file push/pull. No extra deps beyond `adb`. |\n| **Telegram file receiving** | Users can send documents, photos, audio, and video directly to tota via Telegram. |\n| **Task delegation** | Agent can spawn sub-tasks and delegate to itself for complex multi-step workflows. |\n| **Multi-agent crew** | Spawn specialized sub-agents (researcher, coder, reviewer) and coordinate their output. |\n| **Secrets vault** | Store and retrieve secrets using the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) with AES-256-GCM encrypted file fallback. |\n| **Desktop notifications** | Send native desktop notifications from macOS, Linux, or Windows — great for long-running tasks. |\n| **Clipboard** | Read from and write to the system clipboard. |\n| **Voice TTS/STT** | Multi-provider TTS: OpenAI TTS-1, ElevenLabs, Google Cloud TTS. Multi-provider STT: OpenAI Whisper, Groq Whisper. Telegram voice messages auto-transcribed. |\n| **Google Calendar** | List, create, and delete events; check free/busy availability — full OAuth2 flow built in. |\n| **MCP plugins** | Connect any MCP-compatible tool server over HTTP — tools appear instantly in the agent. |\n| **Web UI** | Local dashboard at `http://127.0.0.1:3001` — chat, memory browser, scheduler, skills, logs, and settings. `tota ui` to launch. |\n| **REST API channel** | Control tota programmatically over HTTP with optional bearer-token auth. |\n| **WhatsApp channel** | Use tota from WhatsApp — no Meta Business API needed. Scan a QR code, manage access per phone number. |\n| **Extensible** | Install community skills with one command. Schedule skills as recurring tasks. |\n\n---\n\n## Daemon Mode\n\nOne command to make tota persistent:\n\n```bash\ntota up\n```\n\nThis installs the system service, starts the background daemon, and confirms everything is running. If tota is already running, it just shows the PID.\n\n```bash\ntota restart      # Restart the background process\ntota stop         # Stop the background process\ntota start -d     # Start in background (no service install)\ntota logs         # View recent daemon logs (last 100 lines)\ntota logs -f      # Live-follow daemon logs (Ctrl+C to stop)\ntota logs -n 50   # Show last 50 lines\ntota logs --clear # Clear the log file\ntota status       # Show if daemon is running\n```\n\n### System Service (auto-start on boot)\n\n`tota up` installs this automatically. Manage it directly:\n\n```bash\ntota service install\ntota service status\ntota service uninstall\n```\n\n| Platform | Method | Requires Admin |\n|----------|--------|---------------|\n| **macOS** | LaunchAgent (`~/Library/LaunchAgents/`) | No |\n| **Linux** | systemd user unit (`~/.config/systemd/user/`) | No |\n| **Windows** | Task Scheduler (`schtasks`) | No |\n\n---\n\n## Web UI\n\ntota ships a full browser-based dashboard that runs entirely on your machine — no cloud, no account, no data leaving localhost.\n\n```bash\ntota ui\n```\n\nOpens `http://127.0.0.1:3001` in your default browser. The server starts in seconds and streams responses over WebSocket in real time.\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--port \u003cn\u003e` | Custom port (default: `3001`) |\n| `--no-open` | Start server without opening a browser tab |\n| `--attach` | Proxy to an already-running tota daemon |\n\n```bash\ntota ui --port 4000          # custom port\ntota ui --no-open            # server only\ntota ui --attach             # connect to running daemon\n```\n\n### Pages\n\n| Page | Path | What you can do |\n|------|------|-----------------|\n| **Chat** | `/chat` | Full conversation interface with real-time token streaming, slash-command autocomplete (`/help`, `/status`, `/memory`, `/permissions`, `/exit`), file upload up to 50 MB (drag or attach), voice input via browser mic with auto-transcription, inline media preview, and rendered code blocks with copy button |\n| **Dashboard** | `/dashboard` | Live agent overview — status badge, active model, provider, uptime, token budget (used / daily limit), and current permission mode. Auto-refreshes every 8 s |\n| **Memory** | `/memory` | Browse and manage Second Brain entries (short-term and long-term). Add entries with tags, edit existing ones, and delete stale facts — all changes sync to the SQLite database immediately |\n| **Scheduler** | `/scheduler` | View all scheduled tasks with name, cron/interval, last run, next run, and status. Create, edit, toggle, or cancel any task |\n| **Skills** | `/skills` | See every installed skill — name, description, version, and whether it is currently active. Add, edit, or delete skills |\n| **Settings** | `/settings` | Inspect and update agent behaviour config, provider configuration, API key status per provider, and active channel config |\n| **Logs** | `/logs` | Live log viewer with severity filter (debug / info / warn / error). Auto-refreshes every 5 s and streams new entries via WebSocket |\n| **Integrations** | `/integrations` | At-a-glance status of every channel (Telegram, WhatsApp, REST API, Web UI), configured GitHub and web-search settings, active providers, and tool category overview |\n\n### Enable via config (auto-start with daemon)\n\n```json\n// ~/.tota/config.json\n{\n  \"channels\": {\n    \"ui\": {\n      \"enabled\": true,\n      \"port\": 3001\n    }\n  }\n}\n```\n\nOr configure interactively:\n\n```bash\ntota setup ui\n```\n\n### Security\n\nThe server binds to `127.0.0.1` (loopback) only — it is never exposed to the network. To access it from another machine, use an SSH tunnel:\n\n```bash\nssh -L 3001:127.0.0.1:3001 user@your-server\n# then open http://127.0.0.1:3001 locally\n```\n\n---\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `tota ui` | Launch the local web UI at `http://127.0.0.1:3001` |\n| `tota ui --port \u003cn\u003e` | Use a custom port for the web UI |\n| `tota ui --no-open` | Start the UI server without opening a browser |\n| `tota ui --attach` | Attach to an already-running tota instance via its API |\n| `tota up` | Install service + start daemon + confirm running |\n| `tota` | Start the agent |\n| `tota start` | Start in foreground |\n| `tota start -d` | Start in background |\n| `tota restart` | Restart background process |\n| `tota stop` | Stop background process |\n| `tota logs` | View daemon logs (last 100 lines) |\n| `tota logs -f` | Live-follow daemon logs |\n| `tota logs -n \u003cn\u003e` | Show last N lines |\n| `tota logs --clear` | Clear the log file |\n| `tota doctor` | Reconfigure all settings (Enter keeps current) |\n| `tota setup` | Re-run full setup wizard |\n| `tota setup \u003cfeature\u003e` | Configure one feature only (see below) |\n| `tota status` | Show config and daemon status |\n| `tota help` | Show full manual |\n| `tota upgrade` | Upgrade to latest version |\n| `tota telegram list` | List Telegram users |\n| `tota telegram approve \u003ccode\u003e` | Approve a pairing code |\n| `tota telegram reject \u003cid\u003e` | Reject a pending request |\n| `tota telegram remove \u003cid\u003e` | Remove an approved user |\n| `tota telegram promote \u003cid\u003e` | Promote member to admin |\n| `tota telegram demote \u003cid\u003e` | Demote admin to member |\n| `tota telegram reset` | Clear all Telegram access |\n| `tota whatsapp status` | Show WhatsApp status and access list |\n| `tota whatsapp setup` | Run WhatsApp setup wizard |\n| `tota whatsapp link` | Show QR code to link your WhatsApp device |\n| `tota whatsapp allow \u003cphone\u003e` | Add a phone to the allowed list |\n| `tota whatsapp approve \u003cphone\u003e` | Approve a pending access request |\n| `tota whatsapp reject \u003cphone\u003e` | Reject a pending access request |\n| `tota whatsapp remove \u003cphone\u003e` | Remove a number from access |\n| `tota whatsapp pending` | List pending WhatsApp requests |\n| `tota whatsapp disallow \u003cphone\u003e` | Remove a phone from the allowed list |\n| `tota whatsapp revoke` | Delete session auth and clear access lists (re-link required) |\n| `tota service install` | Install system service |\n| `tota service uninstall` | Uninstall system service |\n| `tota service status` | Show service status |\n| `tota --verbose` | Start with debug logging |\n\n### `tota setup \u003cfeature\u003e`\n\nConfigure a single section without touching everything else. The agent keeps running — open a new terminal tab.\n\n| Feature | What it configures |\n|---------|-------------------|\n| `identity` | Your name and agent name |\n| `llm` | LLM providers and models |\n| `telegram` | Telegram bot token and pairing |\n| `whatsapp` | WhatsApp channel (QR link, allowed numbers, auth directory) |\n| `github` | GitHub username, PAT, default repo |\n| `websearch` | Web search provider key (Brave / Serper / Tavily) |\n| `browser` | Install Chromium, Firefox, WebKit binaries |\n| `computer` | Enable computer-use \u0026 Android ADB tools |\n| `calendar` | Google Calendar OAuth2 credentials — **add `http://localhost:8765/oauth2callback` to Authorized redirect URIs in Google Cloud Console first** |\n| `voice` | TTS/STT providers (OpenAI / ElevenLabs / Google / Groq) |\n| `vault` | Show secrets vault backend and usage info |\n| `api` | REST API channel (port, auth key) |\n| `ui` | Web UI channel (port) |\n| `budget` | Daily token budget |\n\n---\n\n## In-Chat Commands\n\nThese work on both CLI and Telegram and do not consume API tokens.\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show full manual |\n| `/status` | Show config, budget, usage |\n| `/tools` | List loaded tools |\n| `/skills` | List installed skills |\n| `/stream` | Toggle Telegram streaming |\n| `/budget` | Show token budget |\n| `/budget override` | Override budget for one request |\n| `/budget reset` | Reset usage to zero |\n| `/budget set \u003cn\u003e` | Change daily budget |\n| `/permissions` | Change permission mode |\n| `/tasks` | List scheduled tasks |\n| `/memory` | View and manage Second Brain |\n| `/unpair` | Reset all Telegram access |\n\n---\n\n## Built-in Tools\n\n| Category | Tools |\n|----------|-------|\n| **Filesystem** | `read_file`, `write_file`, `create_file`, `edit_file`, `list_dir`, `delete_file`, `send_file`, `approve_scope` |\n| **Document readers** | `read_pdf`, `read_excel`, `write_excel`, `read_docx` — PDF, Excel, Word document support |\n| **File finder** | `find_files` — advanced search by glob, content keyword, type, date range, and size |\n| **Browser** | `browser_open`, `browser_click`, `browser_type`, `browser_key`, `browser_wait`, `browser_screenshot`, `browser_extract`, `browser_scroll`, `browser_scroll_into_view`, `browser_hover`, `browser_select`, `browser_drag`, `browser_evaluate`, `browser_navigate`, `browser_get_url`, `browser_reload`, `browser_close`, `browser_engine`, `browser_cookies_get`, `browser_cookies_set`, `browser_cookies_clear`, `browser_storage_get`, `browser_storage_set`, `browser_storage_clear`, `browser_pdf`, `browser_set_viewport` |\n| **Computer-use** | `computer_screenshot`, `computer_see`, `computer_click`, `computer_move`, `computer_type`, `computer_key`, `computer_scroll`, `computer_drag`, `computer_screen_size` |\n| **Android (ADB)** | `adb_devices`, `adb_screenshot`, `adb_see`, `adb_tap`, `adb_swipe`, `adb_type`, `adb_key`, `adb_shell`, `adb_pull`, `adb_push` |\n| **Shell** | `run_command`, `cd`, `approve_command` |\n| **Code sandbox** | `run_code` — execute Python / JS / Bash / TS / Ruby / Go in an isolated sandbox |\n| **Messaging** | `send_message` |\n| **Git** | `git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push` |\n| **Web** | `fetch_url`, `web_search` — search via Brave, Serper, or Tavily |\n| **Vision** | `analyze_image` — analyze local images or image URLs |\n| **Delegation** | `delegate_task` — spawn a focused sub-agent for a sub-task |\n| **Multi-agent crew** | `spawn_agent` — spawn a specialized sub-agent (researcher, coder, reviewer) with scoped tools |\n| **Secrets vault** | `secret_store`, `secret_get`, `secret_list`, `secret_delete` — OS keychain + encrypted file fallback |\n| **Desktop notifications** | `notify` — send a native desktop notification (macOS, Linux, Windows) |\n| **Clipboard** | `clipboard_read`, `clipboard_write` — read from and write to the system clipboard |\n| **Voice** | `text_to_speech` (OpenAI TTS-1 / ElevenLabs / Google Cloud TTS), `transcribe_audio` (OpenAI Whisper / Groq Whisper) — Telegram voice messages auto-transcribed; `provider` param overrides default per call |\n| **Google Calendar** | `calendar_auth`, `list_events`, `create_event`, `check_availability`, `delete_event` — auto browser-based OAuth2 (tota opens the consent screen for you; one-time [redirect URI setup](#google-calendar-setup) required) |\n| **Skills** | `install_skill`, `list_skills`, `use_skill` |\n| **Scheduler** | `schedule_task`, `list_scheduled_tasks`, `cancel_scheduled_task` |\n| **System** | `budget_status` |\n| **MCP** | `mcp_\u003cserver\u003e_\u003ctool\u003e` — tools loaded dynamically from MCP servers |\n\n---\n\n## Web Search\n\ntota can search the web using three providers — set one API key and it works automatically.\n\n| Provider | Env Var | Sign up |\n|----------|---------|---------|\n| **Brave Search** | `BRAVE_API_KEY` | [brave.com/search/api](https://brave.com/search/api/) |\n| **Serper** | `SERPER_API_KEY` | [serper.dev](https://serper.dev) |\n| **Tavily** | `TAVILY_API_KEY` | [tavily.com](https://tavily.com) |\n\nAuto-detection: if `WEB_SEARCH_PROVIDER=auto` (default), tota picks whichever key it finds. Or pin a specific provider:\n\n```bash\n# ~/.tota/.env\nWEB_SEARCH_PROVIDER=brave\nBRAVE_API_KEY=your-key-here\n```\n\nDisable entirely: `WEB_SEARCH_ENABLED=false`\n\n---\n\n## Vision / Image Analysis\n\ntota can analyze images — local files or URLs — using your provider's vision model.\n\n```\nAnalyze this screenshot: /path/to/screenshot.png\nWhat's in this image? https://example.com/chart.jpg\n```\n\nThe `analyze_image` tool automatically detects MIME types from magic bytes, supports JPEG, PNG, GIF, and WebP, and works with any provider that supports vision.\n\n---\n\n## Computer-Use (Desktop Control)\n\ntota can see and control your desktop — click, type, scroll, drag, and press keys anywhere on screen, on macOS, Linux, and Windows.\n\n### Enable\n\n```bash\n# Option 1 — wizard (recommended)\ntota setup computer\n\n# Option 2 — env var\n# ~/.tota/.env\nCOMPUTER_USE_ENABLED=true\n```\n\nOr set `capabilities.computer.enabled: true` in `~/.tota/tota.yaml`.\n\n### Desktop tools\n\n| Tool | What it does |\n|------|--------------|\n| `computer_screenshot` | Capture the full screen or a region, save to temp file |\n| `computer_see` | Screenshot + vision AI analysis in one step |\n| `computer_click` | Left, right, or double-click at (x, y) |\n| `computer_move` | Move cursor to (x, y) |\n| `computer_type` | Type text at the current keyboard focus |\n| `computer_key` | Press a key or combo (`cmd+c`, `ctrl+z`, `enter`, etc.) |\n| `computer_scroll` | Scroll up/down/left/right at (x, y) |\n| `computer_drag` | Click and drag between two points |\n| `computer_screen_size` | Get display resolution |\n\nDesktop mouse/keyboard control uses [`@nut-tree-fork/nut-js`](https://github.com/nut-tree/nut.js) (cross-platform native module). On Linux, install `libxtst-dev` first:\n\n```bash\nsudo apt install libxtst-dev\n```\n\n### Android tools (ADB)\n\nAll Android tools work via `adb` in your PATH — no new Node.js deps needed.\n\n| Tool | What it does |\n|------|--------------|\n| `adb_devices` | List connected devices |\n| `adb_screenshot` | Capture Android screen |\n| `adb_see` | Android screenshot + vision AI analysis |\n| `adb_tap` | Tap at (x, y) |\n| `adb_swipe` | Swipe between two points |\n| `adb_type` | Type text into focused field |\n| `adb_key` | Send key event (HOME=3, BACK=4, ENTER=66…) |\n| `adb_shell` | Run any `adb shell` command |\n| `adb_pull` | Pull file from device |\n| `adb_push` | Push file to device |\n\n---\n\n## Code Sandbox\n\nThe `run_code` tool executes code in an isolated temporary directory — no access to your project files.\n\nSupported languages: **Python**, **JavaScript (Node.js)**, **Bash**, **TypeScript**, **Ruby**, **Go**\n\n```\nRun this Python script and show me the output:\n  import json; print(json.dumps({\"x\": 42}))\n```\n\n- Timeout: 30 s default, configurable up to 120 s\n- Output capped at 8,000 characters\n- Sandbox cleaned up after each run\n- Accepts optional stdin input\n\n---\n\n## REST API Channel\n\nControl tota programmatically over HTTP:\n\n```bash\n# Enable in ~/.tota/.env\nAPI_CHANNEL_ENABLED=true\nAPI_CHANNEL_PORT=3001\nAPI_CHANNEL_KEY=your-secret-key   # optional\n```\n\n**Endpoints:**\n\n```\nGET  /status          → { \"status\": \"ok\", \"ready\": true }\nPOST /message         → { \"content\": \"your message\", \"timeout\": 30 }\n                      ← { \"requestId\": \"...\", \"response\": \"...\" }\n```\n\n**Authentication** (if `API_CHANNEL_KEY` set):\n```\nAuthorization: Bearer your-secret-key\n# or\nX-Api-Key: your-secret-key\n```\n\n---\n\n## MCP Plugins\n\nConnect any [Model Context Protocol](https://modelcontextprotocol.io) server to tota. Tools load automatically at startup and appear with the prefix `mcp_\u003cserver\u003e_\u003ctool\u003e`.\n\n```yaml\n# ~/.tota/tota.yaml\nmcp:\n  servers:\n    - name: filesystem\n      url: http://localhost:8080/mcp\n      enabled: true\n    - name: my-db\n      url: http://localhost:9090/mcp\n      apiKey: secret-token\n      enabled: true\n```\n\nAny MCP server speaking the JSON-RPC `tools/list` + `tools/call` protocol over HTTP is supported.\n\n---\n\n## Google Calendar Setup\n\n\u003ca id=\"google-calendar-setup\"\u003e\u003c/a\u003e\n\ntota uses a local OAuth2 redirect (no code copy-paste, no \"browser not safe\" warning).\n\n**One-time setup in Google Cloud Console:**\n1. Go to [console.cloud.google.com](https://console.cloud.google.com) → APIs \u0026 Services → Credentials.\n2. Create (or open) your **Desktop app** OAuth 2.0 Client ID.\n3. Under **Authorized redirect URIs**, add:\n   ```\n   http://localhost:8765/oauth2callback\n   ```\n4. Run `tota setup calendar` and enter your Client ID and Secret.\n\n**After that — fully automatic:**  \nJust ask tota about your calendar. It opens your browser to Google's consent screen → you click **Allow** → done. Tokens saved to `~/.tota/calendar-token.json` and auto-refreshed forever.\n\n---\n\n## Second Brain\n\ntota builds structured persistent memory that grows with every conversation.\n\n- **10 memory types** — identity, preference, goal, project, habit, decision, constraint, relationship, episode, reflection\n- **Automatic extraction** — after each response, 0–3 facts extracted with confidence, importance, and durability scores\n- **Relevant recall** — top 5 matching memories (900-char budget) injected before each message\n- **Auto-consolidation** — every 60 min: profile summary, active-state summary, reflections from patterns\n- **Conflict resolution** — opposing memories resolved by confidence (higher wins) or recency\n- **Auto-pruning** — active memories stale after 21 days; inferred memories decay; low-confidence dismissed after 120 days\n- **User controls** — `/memory` for overview, search, pause, resume, clear\n- **Disable** — set `SECOND_BRAIN_ENABLED=false` or `memory.secondBrain.enabled: false` in config\n\nAll data stored locally at `~/.tota/memory/second-brain/second-brain.db`. No cloud.\n\n---\n\n## Configuration\n\nAll runtime data lives in `~/.tota/`.\n\n| Path | Purpose |\n|------|---------|\n| `~/.tota/tota.yaml` | Main config (providers, channels, budget) |\n| `~/.tota/.env` | API keys and tokens |\n| `~/.tota/soul/*.md` | Agent personality files |\n| `~/.tota/permissions.yaml` | Capabilities and approval rules |\n| `~/.tota/skills/` | Installed skills |\n| `~/.tota/schedules.yaml` | Scheduled tasks |\n| `~/.tota/token-usage.json` | Daily token usage |\n| `~/.tota/memory/` | All memory data |\n| `~/.tota/daemon.pid` | Background process PID |\n| `~/.tota/daemon.log` | Daemon logs |\n\n---\n\n## Providers\n\n| Provider | Default Model | API Key Env |\n|----------|--------------|-------------|\n| **DeepSeek** | deepseek-chat | `DEEPSEEK_API_KEY` |\n| **OpenAI** | gpt-4o-mini | `OPENAI_API_KEY` |\n| **Anthropic** | claude-sonnet-4 | `ANTHROPIC_API_KEY` |\n| **Grok (xAI)** | grok-4 | `GROK_API_KEY` |\n| **Groq** | llama-3.3-70b-versatile | `GROQ_API_KEY` |\n| **Ollama Cloud** | gpt-oss:120b | `OLLAMA_CLOUD_API_KEY` |\n| **Ollama Local** | gpt-oss:20b | — |\n| **OpenAI-compat** | custom | `OPENAI_COMPAT_BASE_URL` |\n| **NVIDIA NIM** | nemotron-3-super-120b | `NVIDIA_API_KEY` |\n| **OpenRouter** | openrouter/auto | `OPENROUTER_API_KEY` |\n\ntota tries providers in order and falls back automatically on failure.\n\n---\n\n## Telegram Access\n\ntota uses an organization access model with admins and members.\n\n1. Send `/start` to your bot → receive a pairing code\n2. Run `tota telegram approve \u003ccode\u003e` in CLI → you become the first admin\n3. Additional users send `/start` → admins approve from CLI\n4. Admins: approve/reject requests, promote/demote users, reset access\n5. Members: chat with tota\n\nPrivate chats only. Group messages are always ignored.\n\n---\n\n## WhatsApp\n\nUse tota from WhatsApp — no Meta Business API, no phone number purchase needed. Uses WhatsApp Web (Baileys).\n\n### Quick setup\n\n```bash\ntota setup whatsapp        # enable + configure auth dir and allowed numbers\ntota whatsapp link         # show QR code — scan from WhatsApp → Linked Devices\ntota start                 # go live\n```\n\n### Access control\n\nMessages from unlisted numbers automatically generate a pending access request.\n\n```bash\ntota whatsapp allow +15551234567    # pre-allow a number\ntota whatsapp pending               # view pending requests\ntota whatsapp approve +15551234567  # approve a request\ntota whatsapp reject +15551234567   # reject a request\ntota whatsapp remove +15551234567   # revoke access for a number\ntota whatsapp disallow +15551234567 # remove from allowed list\ntota whatsapp revoke                # nuke session auth + clear all lists (re-link required)\ntota whatsapp status                # show full access list\n```\n\n### Agent outbound messages\n\nThe agent can send messages back through WhatsApp:\n\n- **`send_message`** — sends back to whoever the agent is currently talking to (WhatsApp or Telegram automatically)\n- **`whatsapp_send`** — sends to a specific phone number (must be in your approved list)\n\n### Environment variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WHATSAPP_ENABLED` | `false` | Enable the WhatsApp channel |\n| `WHATSAPP_AUTH_DIR` | `~/.tota/whatsapp-auth` | Where to store session auth files |\n| `WHATSAPP_ALLOW_FROM` | _(empty)_ | Comma-separated allowed phone numbers (E.164) |\n| `WHATSAPP_ALLOW_GROUPS` | `false` | Enable group message support |\n\n---\n\n## Architecture\n\n- **TypeScript + Node.js 20+** — ESM, tsup build\n- **Vercel AI SDK v6** — `generateText` + `streamText`, 50-step (configurable) agentic loop, provider fallback\n- **grammY** — Telegram bot with typing indicators, editable streaming, file uploads\n- **REST API channel** — Node.js `http.createServer`, bearer-token auth, request/response pairing\n- **SQLite + FTS5** — Second Brain with full-text search and auto-consolidation\n- **JSONL** — Short-term, long-term, and episodic conversation memory\n- **Custom daemon manager** — Background spawn + PID file + watchdog crash recovery\n- **Platform services** — macOS LaunchAgent, Linux systemd, Windows Task Scheduler\n- **MCP loader** — JSON-RPC `tools/list` + `tools/call` over HTTP, dynamic tool registration\n- **Code sandbox** — Isolated `os.tmpdir()/tota-sandbox/\u003crunId\u003e/` with cleanup after each run\n- **Tool truncation** — All tool outputs capped at 12,000 chars with clear truncation notice\n\n---\n\n## Contributing\n\nContributions welcome. Please read the guidelines before submitting.\n\n- Fork the repo: \u003chttps://github.com/manu14357/tota-agent\u003e\n- Run `npm install` and `npm run build`\n- Test locally with `tota`\n- Open a PR with a clear description\n\n---\n\n## License\n\nMIT © [manu14357](https://github.com/manu14357)\n\n---\n\n\u003e **Disclaimer:** This is AI software. Use at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanu14357%2Ftota-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanu14357%2Ftota-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanu14357%2Ftota-agent/lists"}