70+ built-in tools · 9 AI providers · Web search · Vision · Browser · Computer-use · Android · MCP plugins

Soul-driven
AI agent

Permission-hardened tools, token budgets, and multi-channel access.Sees your screen. Controls your desktop. Runs 24/7 from CLI, Telegram, or REST API.

npx tota-agent

Or: npm i -g tota-agent

Get StartedView on GitHubSponsor
tota — zsh
$tota
✦ tota is listening...
you look at my screen and submit the form that is open
● computer_see what is on screen?
● computer_click x=640 y=420
● computer_type "hello@acme.com"
● computer_key tab
● computer_click x=640 y=520 (Submit)
Form submitted successfully.
⚡ Take a screenshot to confirm? [y/N]

tota always asks before it acts

Built different

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

Permission-Hardened

Shell blocklist blocks 24 dangerous patterns. Folder-level filesystem scoping. Per-session modes: Ask Me or Allow All. No silent execution — ever.

Second Brain

SQLite + FTS5 persistent memory. 10 memory types — identity, preferences, goals, habits, and more. Auto-extracts 0–3 facts per conversation. Fully local.

Soul-Driven

Personality defined by 4 markdown files you own in ~/.tota/soul/. Customize identity, persona, taste, and heartbeat. No corporate AI wrapper.

Token-Aware

Daily token budget with enforcement. Auto-concise mode kicks in at 70% usage. /budget command to check status, reset, override, or change the limit.

Live Streaming

Real-time markdown rendering on CLI with ANSI colors and step tracking. Telegram gets editable messages with live typing indicators.

Always On

Daemon mode with PID management and crash recovery. System service: macOS LaunchAgent, Linux systemd, Windows Task Scheduler. All without sudo.

Web Search

Built-in web_search tool with Brave, Serper, and Tavily support. Auto-detects provider from env keys. Search results formatted as numbered markdown.

Vision

Analyze local images or image URLs with analyze_image. Auto-detects MIME type from magic bytes. Works with any provider that has vision support.

Code Sandbox

Execute Python, JavaScript, Bash, TypeScript, Ruby, and Go in an isolated temporary sandbox via run_code. Output capped at 8,000 chars. Auto-cleanup.

Task Delegation

delegate_task spawns a focused sub-agent for complex sub-tasks and returns the result. Enables multi-step autonomous workflows without losing context.

MCP Plugins

Connect any Model Context Protocol server over HTTP. Tools appear instantly as mcp_<server>_<tool>. Any JSON-RPC MCP server is supported.

REST API Channel

Control tota programmatically via HTTP. POST /message, GET /status. Optional bearer-token auth. Runs alongside CLI and Telegram on a configurable port.

Extensible Skills

Install community skills with one command. Skills are markdown-based SKILL.md files with elevated permissions. Schedule them as recurring cron tasks.

Up in minutes

From zero to a 24/7 AI agent in under a minute.

01

Install

One command — no Docker, no config files, no cloud signup.

$npm i -g tota-agent
02

Configure

30-second wizard. Enter your name, choose a provider, optionally add a Telegram bot token.

$tota
03

Chat naturally

Ask it to check git, write code, browse a URL, schedule a reminder, or anything else. tota asks before it acts.

$you review my PR and suggest improvements
04

Run 24/7

One command installs the system service, starts the daemon, and confirms everything is running.

$tota up

9 providers. Automatic fallback.

Configure multiple LLM providers and tota tries them in order, remembering the last successful one. One provider goes down? Another picks up seamlessly.

DeepSeek
deepseek-chat

Default · Cost-effective

OpenAI
gpt-4o-mini

GPT-4o, o3, gpt-5

Anthropic
claude-sonnet-4

Claude Sonnet, Opus

Grok / xAI
grok-4

OpenAI-compatible

Ollama Cloud
gpt-oss:120b

Remote hosted

Ollama Local
qwen3.5:2b

No API key needed

MiMo
mimo-v2.5-pro

Xiaomi · China-optimized

OpenAI-compat
Custom

Any compatible endpoint

MiMo Token Plan
mimo-v2.5-pro

Token-based pricing

Fallback chain

DeepSeek→OpenAI→Anthropic→Grok→…

Configurable order · Tries last successful provider first · Set DEFAULT_PROVIDER to override

Second Brain

A persistent, structured memory that grows with every conversation. SQLite + FTS5 under the hood. Everything stays on your machine.

10 Memory Types

durableactive
IdentityPreferenceGoalProjectHabitDecisionConstraintRelationshipEpisodeReflection
SQLite + FTS5
Storage
~/.tota/memory/
Location
5 memories / req
Context

How it works

⬇
Extract0–3 facts per response
⚖
ScoreConfidence · Importance · Durability
🔍
RecallTop 5 relevant on every request
🧠
ConsolidateProfile summary every 60 min
Conflict resolution

Higher-confidence memory wins. Opposing facts auto-resolved. Memories reinforced 3× promoted to durable scope.

100% local

All memory data stays in ~/.tota/. Nothing leaves your machine.

Manage via /memory

OverviewRecentSearchPauseResumeClear

Integrations

Native GitHub tooling, Telegram bot, REST API, and MCP plugins — all first-class.

GitHub Companion

5 tools · activated when GITHUB_TOKEN is set

create_prCreate pull requests from conversation
review_prFetch diff and post review comments
list_issuesFilter issues by state, label, assignee
create_issueCreate issues with labels and assignees
github_apiRaw access to any GitHub API endpoint

Co-authored commits — Every commit tota makes appends Co-authored-by: tota <tota@github.com> automatically.

Telegram Bot

Private chats · Admin + member roles · Pairing-code access

📡
Text streaming

Live response editing with typing indicators

📎
File uploads

Photos, audio, video, documents auto-detected

⌨️
Inline keyboards

Approve shell commands and scope requests in-chat

👥
Multi-user access

Admin/member roles with pairing-code flow

🔒
Private chats only

Groups and channels always ignored

Access model

AdminFirst user · Can approve / reject / manage
MemberApproved user · Full chat access

REST API Channel

HTTP control · Bearer-token auth · Port 3001 (configurable)

GET/statusCheck if agent is running and ready
POST/messageSend a message, receive a response

POST /message

{ "content": "What time is it?" }
← { "response": "It's 3:14 PM UTC." }

Enable — set API_CHANNEL_ENABLED=true in ~/.tota/.env

MCP Plugins

Model Context Protocol · HTTP JSON-RPC · Auto-registered at startup

🔌
Any MCP server

JSON-RPC tools/list + tools/call over HTTP

🏷️
Auto-prefixed tools

mcp_<server>_<tool> — no naming conflicts

🔑
Bearer auth

Per-server apiKey forwarded automatically

⚡
Load at startup

Tools registered alongside built-ins

🛡️
Graceful errors

Unavailable servers logged and skipped

~/.tota/tota.yaml

mcp:
  servers:
    - name: my-tools
      url: http://localhost:8080/mcp
      enabled: true

Tool naming — tools from server my-tools appear as mcp_my-tools_<name>

Ready to start?

Node.js 20+ required. First run takes about 30 seconds.

zsh
# Install globally
$ npm i -g tota-agent
# Or try without installing
$ npx tota-agent
# First run — 30s setup wizard
$ tota
# Run as a 24/7 background daemon
$ tota up
Full setup guideBrowse docs