Tota Agent

AI agent built for control: permissioned tools, safe execution, token budgets, and multi-channel access.

Remembers what matters. Asks before it acts. Runs 24/7 from CLI, Telegram, WhatsApp, REST API, or local web UI. 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…).

---

Quick Start

Install globally (recommended — makes tota available everywhere):

npm i -g tota-agent
tota

Or try it once without installing:

npx tota-agent

> Note: npx tota-agent runs tota in a temporary session only. > The tota command will not be available after that session ends. > Use npm i -g tota-agent for a permanent install.

> Upgrading from the old @manu14357/tota-agent package? > The package was renamed to tota-agent (unscoped). The old binary shim blocks the new install on Windows. > Uninstall the old package first, then reinstall: > ``bash > npm uninstall -g @manu14357/tota-agent > npm i -g tota-agent > ``

First run launches the setup wizard — enter your name, an API key, and optionally a Telegram bot token. Takes about 30 seconds.

To reconfigure at any time:

tota doctor

Or configure just one feature without running the full wizard:

tota setup websearch    # add a web search key
tota setup telegram     # change your Telegram bot
tota setup llm          # swap LLM provider
tota setup browser      # install Chromium, Firefox, WebKit browser binaries
tota setup computer     # enable computer-use & Android ADB tools
tota setup api          # enable the REST API channel
tota ui                 # open the local web UI (http://127.0.0.1:3001)

---

Why tota?

Every AI agent can read files and run commands. Most do it silently. tota asks first — and remembers what matters.

| Feature | What it means | |---------|--------------| | Permission-hardened | Shell blocklist, folder-level scoping, per-session approval modes. No surprises. | | Second Brain | Persistent SQLite memory with FTS5 search. 10 memory types. Learns your preferences automatically. | | Soul-driven | Personality from markdown files you own (~/.tota/soul/). No corporate wrapper. | | Token-aware | Daily budget with auto-concise at 70%. /budget command to check, reset, or override. | | Live streaming | Real-time token streaming on CLI with markdown re-render. Telegram streaming with editable messages. | | Always on | Daemon mode with crash recovery and system service (macOS, Linux, Windows). | | Web search | Built-in web search via Brave, Serper, or Tavily. Auto-detects from env keys. | | Vision | Analyze local images and URLs with your AI provider's vision capabilities. | | Code sandbox | Execute Python, JavaScript, Bash, TypeScript, Ruby, and Go in an isolated temp sandbox. | | Document readers | Read PDF, Excel (.xlsx/.csv), and Word (.docx) files — text, tables, metadata. | | Advanced file finder | Find files by glob, content keyword, type, date range, and size across deep directory trees. | | Browser automation | Full Playwright browser — Chromium, Firefox, or WebKit. Open pages, click, type, hover, drag, select, scroll, evaluate JS, manage cookies & storage, export PDF, set viewport. Switch engines mid-session. | | Computer-use | See your screen via vision AI, then click, type, scroll, drag, and press keys anywhere on the desktop. macOS, Linux, and Windows. | | Android control | ADB-powered Android device control — tap, swipe, type, key events, shell commands, file push/pull. No extra deps beyond adb. | | Telegram file receiving | Users can send documents, photos, audio, and video directly to tota via Telegram. | | Task delegation | Agent can spawn sub-tasks and delegate to itself for complex multi-step workflows. | | Multi-agent crew | Spawn specialized sub-agents (researcher, coder, reviewer) and coordinate their output. | | Secrets vault | Store and retrieve secrets using the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) with AES-256-GCM encrypted file fallback. | | Desktop notifications | Send native desktop notifications from macOS, Linux, or Windows — great for long-running tasks. | | Clipboard | Read from and write to the system clipboard. | | 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. | | Google Calendar | List, create, and delete events; check free/busy availability — full OAuth2 flow built in. | | MCP plugins | Connect any MCP-compatible tool server over HTTP — tools appear instantly in the agent. | | Web UI | Local dashboard at http://127.0.0.1:3001 — chat, memory browser, scheduler, skills, logs, and settings. tota ui to launch. | | REST API channel | Control tota programmatically over HTTP with optional bearer-token auth. | | WhatsApp channel | Use tota from WhatsApp — no Meta Business API needed. Scan a QR code, manage access per phone number. | | Extensible | Install community skills with one command. Schedule skills as recurring tasks. |

---

Daemon Mode

One command to make tota persistent:

tota up

This installs the system service, starts the background daemon, and confirms everything is running. If tota is already running, it just shows the PID.

tota restart      # Restart the background process
tota stop         # Stop the background process
tota start -d     # Start in background (no service install)
tota logs         # View recent daemon logs (last 100 lines)
tota logs -f      # Live-follow daemon logs (Ctrl+C to stop)
tota logs -n 50   # Show last 50 lines
tota logs --clear # Clear the log file
tota status       # Show if daemon is running

System Service (auto-start on boot)

tota up installs this automatically. Manage it directly:

tota service install
tota service status
tota service uninstall

| Platform | Method | Requires Admin | |----------|--------|---------------| | macOS | LaunchAgent (~/Library/LaunchAgents/) | No | | Linux | systemd user unit (~/.config/systemd/user/) | No | | Windows | Task Scheduler (schtasks) | No |

---

Web UI

tota ships a full browser-based dashboard that runs entirely on your machine — no cloud, no account, no data leaving localhost.

tota ui

Opens http://127.0.0.1:3001 in your default browser. The server starts in seconds and streams responses over WebSocket in real time.

Options

| Flag | Description | |------|-------------| | --port | Custom port (default: 3001) | | --no-open | Start server without opening a browser tab | | --attach | Proxy to an already-running tota daemon |

tota ui --port 4000          # custom port
tota ui --no-open            # server only
tota ui --attach             # connect to running daemon

Pages

| Page | Path | What you can do | |------|------|-----------------| | 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 | | Agents | /agents | Live multi-agent canvas. Launch a crew (/create-agent) and watch the orchestrator fan out into worker agents as nodes — each shows role, status (queued/running/done/error), elapsed time, and output. Streams over WebSocket in real time | | 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 | | 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 | | Scheduler | /scheduler | View all scheduled tasks with name, cron/interval, last run, next run, and status. Create, edit, toggle, or cancel any task | | Skills | /skills | See every installed skill — name, description, version, and whether it is currently active. Add, edit, or delete skills | | Settings | /settings | Inspect and update agent behaviour config, provider configuration, API key status per provider, and active channel config | | Logs | /logs | Live log viewer with severity filter (debug / info / warn / error). Auto-refreshes every 5 s and streams new entries via WebSocket | | 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 |

Enable via config (auto-start with daemon)

// ~/.tota/config.json
{
  "channels": {
    "ui": {
      "enabled": true,
      "port": 3001
    }
  }
}

Or configure interactively:

tota setup ui

Security

The 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:

ssh -L 3001:127.0.0.1:3001 user@your-server
# then open http://127.0.0.1:3001 locally

---

CLI Commands

| Command | Description | |---------|-------------| | tota ui | Launch the local web UI at http://127.0.0.1:3001 | | tota ui --port | Use a custom port for the web UI | | tota ui --no-open | Start the UI server without opening a browser | | tota ui --attach | Attach to an already-running tota instance via its API | | tota up | Install service + start daemon + confirm running | | tota | Start the agent | | tota start | Start in foreground | | tota start -d | Start in background | | tota restart | Restart background process | | tota stop | Stop background process | | tota logs | View daemon logs (last 100 lines) | | tota logs -f | Live-follow daemon logs | | tota logs -n | Show last N lines | | tota logs --clear | Clear the log file | | tota doctor | Reconfigure all settings (Enter keeps current) | | tota setup | Re-run full setup wizard | | tota setup | Configure one feature only (see below) | | tota status | Show config and daemon status | | tota help | Show full manual | | tota upgrade | Upgrade to latest version | | tota telegram list | List Telegram users | | tota telegram approve | Approve a pairing code | | tota telegram reject | Reject a pending request | | tota telegram remove | Remove an approved user | | tota telegram promote | Promote member to admin | | tota telegram demote | Demote admin to member | | tota telegram reset | Clear all Telegram access | | tota whatsapp status | Show WhatsApp status and access list | | tota whatsapp setup | Run WhatsApp setup wizard | | tota whatsapp link | Show QR code to link your WhatsApp device | | tota whatsapp allow | Add a phone to the allowed list | | tota whatsapp approve | Approve a pending access request | | tota whatsapp reject | Reject a pending access request | | tota whatsapp remove | Remove a number from access | | tota whatsapp pending | List pending WhatsApp requests | | tota whatsapp disallow | Remove a phone from the allowed list | | tota whatsapp revoke | Delete session auth and clear access lists (re-link required) | | tota service install | Install system service | | tota service uninstall | Uninstall system service | | tota service status | Show service status | | tota --verbose | Start with debug logging |

tota setup

Configure a single section without touching everything else. The agent keeps running — open a new terminal tab.

| Feature | What it configures | |---------|-------------------| | identity | Your name and agent name | | llm | LLM providers and models | | telegram | Telegram bot token and pairing | | whatsapp | WhatsApp channel (QR link, allowed numbers, auth directory) | | github | GitHub username, PAT, default repo | | websearch | Web search provider key (Brave / Serper / Tavily) | | browser | Install Chromium, Firefox, WebKit binaries | | computer | Enable computer-use & Android ADB tools | | calendar | Google Calendar OAuth2 credentials — add http://localhost:8765/oauth2callback to Authorized redirect URIs in Google Cloud Console first | | voice | TTS/STT providers (OpenAI / ElevenLabs / Google / Groq) | | vault | Show secrets vault backend and usage info | | api | REST API channel (port, auth key) | | ui | Web UI channel (port) | | budget | Daily token budget |

---

In-Chat Commands

These work on both CLI and Telegram and do not consume API tokens.

| Command | Description | |---------|-------------| | /help | Show full manual | | /status | Show config, budget, usage | | /create-agent | Spawn 1+ parallel agents on a goal (e.g. 3 research vector DBs) | | /agents | List recent multi-agent runs (watch live on the web UI canvas) | | /tools | List loaded tools | | /skills | List installed skills | | /stream | Toggle Telegram streaming | | /budget | Show token budget | | /budget override | Override budget for one request | | /budget reset | Reset usage to zero | | /budget set | Change daily budget | | /permissions | Change permission mode | | /tasks | List scheduled tasks | | /memory | View and manage Second Brain | | /unpair | Reset all Telegram access |

---

Built-in Tools

| Category | Tools | |----------|-------| | Filesystem | read_file, write_file, create_file, edit_file, list_dir, delete_file, send_file, approve_scope | | Document readers | read_pdf, read_excel, write_excel, read_docx — PDF, Excel, Word document support | | File finder | find_files — advanced search by glob, content keyword, type, date range, and size | | 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 | | Computer-use | computer_screenshot, computer_see, computer_click, computer_move, computer_type, computer_key, computer_scroll, computer_drag, computer_screen_size | | Android (ADB) | adb_devices, adb_screenshot, adb_see, adb_tap, adb_swipe, adb_type, adb_key, adb_shell, adb_pull, adb_push | | Shell | run_command, cd, approve_command | | Code sandbox | run_code — execute Python / JS / Bash / TS / Ruby / Go in an isolated sandbox | | Messaging | send_message | | Git | git_status, git_diff, git_log, git_add, git_commit, git_push | | Web | fetch_url, web_search — search via Brave, Serper, or Tavily | | Vision | analyze_image — analyze local images or image URLs | | Delegation | delegate_task — spawn a focused sub-agent for a sub-task | | Multi-agent crew | spawn_agent — spawn a specialized sub-agent (researcher, coder, reviewer) with scoped tools | | Secrets vault | secret_store, secret_get, secret_list, secret_delete — OS keychain + encrypted file fallback | | Desktop notifications | notify — send a native desktop notification (macOS, Linux, Windows) | | Clipboard | clipboard_read, `cli

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: manu14357
• Source: manu14357/tota-agent
• License: MIT
• Homepage: https://tota-agent.vercel.app/

Install and usage instructions live in the source repository linked above.