# Tota Agent

> Open-source AI agent: 11 LLM providers (OpenAI, Claude, Ollama, DeepSeek…), 60+ tools, web search, vision, browser & Android automation, MCP plugins, Second Brain memory — CLI · Telegram · WhatsApp · REST API

- **Type:** MCP server
- **Install:** `agentstack add mcp-manu14357-tota-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [manu14357](https://agentstack.voostack.com/s/manu14357)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [manu14357](https://github.com/manu14357)
- **Source:** https://github.com/manu14357/tota-agent
- **Website:** https://tota-agent.vercel.app/

## Install

```sh
agentstack add mcp-manu14357-tota-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
npm i -g tota-agent
tota
```

Or try it once without installing:

```bash
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:

```bash
tota doctor
```

Or configure just one feature without running the full wizard:

```bash
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:

```bash
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.

```bash
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:

```bash
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.

```bash
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 |

```bash
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)

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

Or configure interactively:

```bash
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:

```bash
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](https://github.com/manu14357)
- **Source:** [manu14357/tota-agent](https://github.com/manu14357/tota-agent)
- **License:** MIT
- **Homepage:** https://tota-agent.vercel.app/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-manu14357-tota-agent
- Seller: https://agentstack.voostack.com/s/manu14357
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.