siddsachar/row-bot — Gitpedia

<img src="docs/row_bot_glyph_256.png" alt="Row-Bot" width="180"> <h1 align="center">Row-Bot</h1> (formerly Thoth) <a href="https://github.com/siddsachar/row-bot/releases"><img src="https://img.shields.io/github/v/release/siddsachar/row-bot?style=flat&label=release&color=4F78A4" alt="Release"></a> <a href="https://github.com/siddsachar/row-bot/actions/workflows/ci.yml"><img src="https://github.com/siddsachar/row-bot/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/siddsachar/row-bot?style=flat" alt="License"></a> <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-4F78A4?style=flat" alt="Platform">

Row-Bot is a local-first desktop AI assistant for doing real work with models,
memory, and tools. Its name is the operating model: Reason through messy
context, Orchestrate tools and model providers, and Work inside the
files, repos, workflows, and channels you choose.

It combines chat, durable memory, tool use, workflows, Developer Studio,
Designer Studio, Smart Skills, Skills Hub, Custom Tools, plugins, messaging
channels, realtime voice, and provider-aware model routing. Durable app data
stays local by default.

Choose the model path that fits the task: local models through
Ollama; provider keys for OpenAI, Anthropic, Google AI,
xAI, MiniMax, OpenRouter,
Atlas Cloud,
and Ollama Cloud; subscription sign-in for ChatGPT / Codex and Claude
Subscription; or custom OpenAI-compatible endpoints such as oMLX, LM Studio,
vLLM, llama.cpp, LocalAI, LiteLLM, and SGLang. Row-Bot keeps provider identity,
capability labels, context limits, and chat-only fallbacks explicit so local,
hosted, and self-hosted models can sit side by side.

Row-Bot itself has no account system, no Row-Bot-hosted inference server, and
no telemetry pipeline. Provider calls go to the provider or endpoint you choose,
and provider keys and subscription tokens are stored in the OS credential store
when available.

Download the latest installer from GitHub Releases. Windows and macOS use one-click installers. Linux has a one-line user installer.

<table align="center"> <tr> <td align="center"><a href="https://youtu.be/GA2Tnlt4jNk"><img src="https://img.youtube.com/vi/GA2Tnlt4jNk/maxresdefault.jpg" width="360" alt="Turn Research Into a Client-Ready Report with Row-Bot"></a> <a href="https://youtu.be/GA2Tnlt4jNk">Turn Research Into a Client-Ready Report with Row-Bot</a></td> <td align="center"><a href="https://youtu.be/wOUSGTyfEpk"><img src="https://img.youtube.com/vi/wOUSGTyfEpk/maxresdefault.jpg" width="360" alt="Turn Your Inbox Into an Action Plan with Row-Bot"></a> <a href="https://youtu.be/wOUSGTyfEpk">Turn Your Inbox Into an Action Plan with Row-Bot</a></td> </tr> <tr> <td align="center"><a href="https://youtu.be/Vuk2xz-vPcA"><img src="https://img.youtube.com/vi/Vuk2xz-vPcA/maxresdefault.jpg" width="360" alt="Create a Background AI Workflow with Row-Bot"></a> <a href="https://youtu.be/Vuk2xz-vPcA">Create a Background AI Workflow with Row-Bot</a></td> <td align="center"><a href="https://youtu.be/hRLuOEqbsds"><img src="https://img.youtube.com/vi/hRLuOEqbsds/maxresdefault.jpg" width="360" alt="Create Launch Campaign Designs with Row-Bot Designer Studio"></a> <a href="https://youtu.be/hRLuOEqbsds">Create Launch Campaign Designs with Row-Bot Designer Studio</a></td> </tr> </table>

What You Get

Area	Details
Agent and models	LangGraph ReAct agent, streaming responses, thinking bubbles, smart context trimming, provider-qualified model selection, readiness routing, chat-only fallback for non-tool models, chat/agent/vision capability labels, custom endpoint profiles and probes, live Atlas Cloud and MiniMax discovery, ChatGPT / Codex and Claude Subscription providers, OpenCode providers, local and hosted model catalogs, background model cache, and per-thread, per-workflow, and per-Developer model overrides.
Memory and knowledge	Personal knowledge graph, 10 entity types, 67 typed relations, bounded semantic/lexical/graph recall, audit and review states, recall traces, graph visualization, Obsidian-compatible wiki export, document extraction with source provenance, Dream Cycle refinement, duplicate merging, stale-confidence decay, relationship inference, self-knowledge, insights, and conversation search.
Tools	30+ core tool modules for web search, DuckDuckGo, Wikipedia, arXiv, YouTube transcripts, URL reading, documents, wiki vault, Gmail, Google Calendar, filesystem, shell, browser automation, workflows, tracker, channels, X, image generation/editing, video generation, MCP, Developer Studio, Designer Studio, Custom Tool Builder, status, calculator, Wolfram Alpha, weather, vision, memory, system info, and charts. File tools read PDF, CSV, Excel, JSON, JSONL, TSV, and image files, with schema, stats, previews, and PDF export where supported.
Developer Studio	Local Git workspace linking and cloning, code threads, repo inspector, file tree, diffs, todos, tests, branch, commit, push and PR prep, approval modes, and optional Docker Sandbox with a shadow workspace and explicit import back into the real repo.
Designer Studio	Decks, documents, landing pages, app mockups, and storyboards with a sandboxed interactive runtime, templates, brand controls, critique and repair, AI image and video generation, chart insertion, Mermaid and Plotly rendering, shareable HTML, and export to PDF, HTML, PNG, and PPTX.
Workflows	Scheduled runs, webhook triggers, task-completion triggers, step pipelines, conditions, approvals, subtasks, notification-only runs, concurrency groups, delivery defaults, per-workflow model/tool/skill overrides, safety modes, run status, run history, upcoming runs, and a Workflow Console.
Controlled self-evolution	Structured self-reflection, bounded change proposals, reviewable execution boundaries, persistence, Dream Cycle and memory integration, and Command Center/status visibility for improvement work that stays explicit and auditable.
Channels and voice	Telegram, WhatsApp, Discord, Slack, and SMS with streaming, reactions, media intake, voice transcription, document extraction, approval routing, health checks, auto-generated send/photo/document tools, and optional tunnel support. Realtime voice adds provider-backed voice sessions, action handling, speech/cue policy, and local faster-whisper STT plus Kokoro TTS options.
Platform and app	Native desktop app, setup wizard, tray integration on Windows and macOS, desktop notifications, local browser-first Linux launch, optional Linux native window/tray mode, faster transcript and Settings surfaces, Home status bar for models, OAuth, MCP, plugins, documents, workflows, Buddy, logging, disk, task DB recovery, and verified auto-updates.
Extensibility	Smart Skills, pinned skills, slash commands, Skills Hub browsing/import/search, sandboxed plugin marketplace, bundled skills and tool guides, external MCP clients over stdio, Streamable HTTP, and SSE, Custom Tools from repos or folders, hardened Custom Tool Builder setup, Claude Code Delegation through an approval-gated CLI worker, migration from selected Hermes/OpenClaw data, setup center, identity settings, and stability diagnostics.

See docs/ARCHITECTURE.md for the full subsystem reference.

Install

Windows

Download the latest Windows installer.
Run it. The installer bundles the embedded Python runtime, app source, and Python dependencies. Ollama is optional and only needed for local models.
Launch Row-Bot from the Start Menu or desktop shortcut.

User data lives in %USERPROFILE%\.row-bot. Repairing or upgrading replaces the bundled runtime and preserves your data. Startup logs are written to %USERPROFILE%\.row-bot\row_bot_app.log, including recovery hints for known optional audio package issues such as TorchCodec.

macOS

Download the latest macOS DMG.
Drag Row-Bot.app into Applications.
Launch Row-Bot from Applications or Launchpad.

The first run may ask you to confirm that the app was downloaded from the internet. The packaged app uses its bundled Python runtime and dependencies, and it starts Ollama if Ollama is already installed. Apple Silicon and Intel Macs are supported on macOS 12+.

If you only want provider models or a custom endpoint, you can skip model downloads during setup.

Linux

Run:

bash
curl -fsSL https://raw.githubusercontent.com/siddsachar/row-bot/main/installer/install-linux.sh | bash

To install a specific version:

bash
curl -fsSL https://raw.githubusercontent.com/siddsachar/row-bot/main/installer/install-linux.sh | bash -s -- 4.1.0

The installer downloads the release tarball, verifies its SHA256 from the GitHub release manifest, installs under ~/.local/share/row-bot, creates ~/.local/bin/row-bot, and stores user data in ~/.row-bot. The default Linux build opens in your system browser. Native window and tray support are available when the required GTK, Qt, and AppIndicator libraries are installed.

Manual tarball install:

bash
tar -xzf Row-Bot-X.Y.Z-Linux-x86_64.tar.gz
cd Row-Bot-X.Y.Z-Linux-x86_64
./install.sh
row-bot

If ~/.local/bin is not on PATH, run ~/.local/bin/row-bot or add it to your shell profile. On Linux, provider secrets use Secret Service or KWallet when available. WSL and headless systems can run without a keyring, but new secrets are session-only until secure storage is configured.

For browser automation, Chromium may need distro packages that the tarball cannot install. If Playwright reports missing dependencies, run the command it prints, or use python -m playwright install --with-deps chromium from a source checkout.

Upgrading from Thoth 3.x

Row-Bot v4 is the renamed successor to Thoth. On first launch, Row-Bot copies supported Thoth 3.x data into the new Row-Bot data locations and leaves the original Thoth data in place. Provider settings, channels, skills, MCP servers, plugins, Buddy assets, Designer workspaces, conversations, memories, tasks, media, and updater state are included in the migration path.

The major-version rebrand also changes app names, installer names, release artifact names, Linux commands, and data directories. Existing Thoth users should install Row-Bot v4 with the new installer rather than expecting the 3.x updater contract to replace itself in place.

Quick Start

On first launch, Row-Bot opens a setup wizard. Pick one of three paths:

Mode	Use it when	Setup
Local	You want inference and embeddings on your machine.	Choose a local runtime, download a recommended model such as `qwen3:14b` or a smaller model such as `qwen3:8b`, then start chatting. Ollama is the supported local runtime today.
Providers	You want hosted models, frontier reasoning, or no local model download.	Add an OpenAI, Anthropic, Google AI, xAI, MiniMax, OpenRouter, Atlas Cloud, or Ollama Cloud key, refresh live catalogs where available, pick a default model, and save Quick Choices. ChatGPT / Codex and Claude Subscription sign-in are available in Settings after launch.
Custom/Self-hosted	You run oMLX, LM Studio, vLLM, llama.cpp, LocalAI, LiteLLM, SGLang, or a private gateway.	Enter an OpenAI-compatible base URL such as `http://127.0.0.1:1234/v1`, choose the closest compatibility profile, add a key if your server requires one, fetch models, and choose a default.

Common first prompts:

Remember that my mom's birthday is March 15
Search for recent papers on transformer architectures
Read report.pdf in my workspace
Run git status on my project
Create a six-slide pitch deck for my startup
Show my headache trends this month
Remind me to call the dentist tomorrow at 9am
Review this repo and suggest the highest-risk issues
Turn this GitHub repo into a Custom Tool
What did I ask about taxes last week?

For local and self-hosted servers, use a context window large enough for Row-Bot's agent prompt and tool schemas. A 4096 context can fail before the first chat turn with misleading prompt-template errors. 32768 is a practical starting point for agent mode. Models that are useful for normal conversation but not reliable with tools can still run through chat-only mode.

Models, Keys, and Integrations

Most tools work without API keys. Add keys only for the providers and integrations you use.

Model catalog browsing, pinning, defaults, and Quick Choices live in
Settings → Models. Model choices stay provider-qualified, so the same model
ID from a local runtime, OpenRouter, Atlas Cloud, a custom endpoint, or a direct
provider remains distinct. Row-Bot also tracks whether a selected model is ready
for full agent/tool use, supports vision, should run chat-only, or needs a
larger context window or different endpoint profile. Live catalogs such as Atlas
Cloud and MiniMax refresh through the same provider path, and Atlas image/video
generation rows are filtered out of chat, agent, and vision model surfaces.

Service	Key or setup	Used for
OpenAI	`OPENAI_API_KEY`	OpenAI models and image tools.
ChatGPT / Codex	In-app ChatGPT sign-in	Subscription-backed Codex models through ChatGPT's internal backend.
Claude Subscription	In-app Claude OAuth or explicit setup-token import	Subscription-backed Claude models through Row-Bot-owned OAuth. This is separate from Anthropic API.
Anthropic	`ANTHROPIC_API_KEY`	Claude models through the direct API.
Google AI	`GOOGLE_API_KEY`	Gemini models, Imagen, and Veo.
xAI	`XAI_API_KEY`	Grok models, Grok Imagine, and Grok Imagine Video.
MiniMax	`MINIMAX_API_KEY`	Current MiniMax models through the Anthropic-compatible API, discovered from the live provider catalog where available.
OpenRouter	`OPENROUTER_API_KEY`	Access to 100+ provider models.
Atlas Cloud	`ATLASCLOUD_API_KEY`	OpenAI-compatible access to Atlas-hosted chat, agent, and vision models, discovered from the live provider catalog. Image and video generation rows are not exposed as chat models.
Ollama Cloud	`OLLAMA_CLOUD_API_KEY` or local daemon sign-in	Direct Ollama Cloud models and cloud-tagged daemon models.
Custom OpenAI-compatible endpoint	Base URL and optional key	Self-hosted or proxy models through profiles for oMLX, LM Studio, vLLM, llama.cpp, LocalAI, LiteLLM, SGLang, and generic servers.
Tavily	`TAVILY_API_KEY`	Live web search.
Wolfram Alpha	`WOLFRAM_ALPHA_APPID`	Symbolic math, unit conversion, and scientific data.
Telegram	`TELEGRAM_BOT_TOKEN`	Telegram bot messaging.
Discord	`DISCORD_BOT_TOKEN`	Discord DM messaging.
Slack	`SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN`	Slack DM messaging through Socket Mode.
Twilio	`TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN`	SMS.
X	`X_CLIENT_ID` / `X_CLIENT_SECRET`	X API v2 OAuth 2.0 PKCE for search, timeline, mentions, posting, replies, quotes, likes, reposts, bookmarks, and deletes.
ngrok	`NGROK_AUTHTOKEN`	Tunnels for inbound webhooks.
Gmail and Google Calendar	Google Cloud OAuth `credentials.json`	Email search/read/draft/send and calendar view/create/update/move/delete.

Configure providers in Settings, Channels, and Accounts. Keys and in-app ChatGPT / Codex and Claude Subscription OAuth tokens are stored in Windows Credential Manager, macOS Keychain, or Linux Secret Service/KWallet when available. ~/.row-bot/api_keys.json and ~/.row-bot/providers.json keep metadata only, such as saved state, provider status, Quick Choices, compatibility profiles, probe results, and masked fingerprints.

Atlas Cloud uses an OpenAI-compatible API, but Row-Bot treats it as a
first-class provider with its own setup, auth, catalog refresh, provider
identity, capability labels, streaming behavior, and chat/agent/vision surface
filtering.

Embedding providers are configured separately from chat models. Local embeddings are available for private document and vector indexing. Optional cloud embeddings show a privacy warning because document text is sent to the selected embedding provider.

External Codex CLI and Claude Code login files are metadata/reference only. Row-Bot can detect that a CLI login exists, but direct Codex runtime requires the in-app ChatGPT sign-in and direct Claude Subscription runtime requires Row-Bot-owned Claude OAuth or an explicit user import. Row-Bot does not copy runnable tokens from ~/.codex/auth.json or ~/.claude/*, and Claude Subscription never falls back to ANTHROPIC_API_KEY.

Claude Subscription supports two Row-Bot-owned auth paths in Settings -> Providers: in-app Claude OAuth, or explicit import of a token printed by claude setup-token. The setup-token path is a user paste/import action; Row-Bot still does not silently read Claude Code environment variables or credential files.

After connecting Claude Subscription, Settings -> Providers can run a Claude Subscription runtime test that checks native OAuth chat, a forced Row-Bot tool call, and tool-result replay. A failed runtime test is stored as provider metadata and prevents Row-Bot from advertising Claude Subscription as tool-ready until it is fixed or reconnected; claude -p remains a separate Claude Code delegation path, not the provider runtime.

Tools and Safety

Row-Bot's tools can be enabled or disabled from Settings. Many tools expose multiple operations, Developer Studio adds code-specific tools, Skills Hub can add manual skills, Custom Tools can be promoted after review, and running channels add send/photo/document tools automatically.

Group	Included tools
Search and knowledge	Tavily web search, DuckDuckGo, Wikipedia, arXiv, YouTube transcripts, URL reader, document search, wiki vault, memory graph, and conversation search.
Productivity	Gmail, Google Calendar, filesystem, shell, visible Chromium browser automation, workflows, tracker, channel tools, and X.
Media and design	Designer Studio, image generation/editing through OpenAI, Google, and xAI, video generation through Google Veo and xAI Grok Imagine Video, chart insertion, Mermaid, Plotly, and media persistence.
Developer and extensibility	Developer Studio, Custom Tool Builder, promoted Custom Tools, external MCP tools, plugin tools, Claude Code Delegation, and Row-Bot Status.
Analysis	Calculator, Wolfram Alpha, weather, vision for camera/screen/workspace images, system info, and Plotly charts with PNG export.

Safety controls are built into the tool layer:

Destructive operations require confirmation, including file delete/move, moderate-risk shell commands, Gmail send, calendar move/delete, memory delete, tracker delete, and task delete.
Filesystem access is sandboxed to the configured workspace folder, which defaults to ~/Documents/Row-Bot.
Shell commands are classified as safe, moderate, or blocked. High-risk commands such as shutdown, reboot, and mkfs are blocked.
Background workflows can have per-task command prefix and email-recipient allowlists.
Browser tabs are isolated per thread and cleaned up when tasks or threads finish.
Developer Studio has its own approval modes for edits, commands, Git operations, commits, pushes, and PR prep.
Docker Sandbox is opt-in and runs commands in a shadow workspace until you explicitly import changes.
Controlled self-evolution produces bounded, reviewable proposals and does not
silently modify repos or app code.
Smart Skills, slash commands, and Skills Hub imports stay user-controlled; installed skills can be enabled, disabled, reviewed, and removed.
Custom Tools are reviewed, smoke-tested, enabled, promoted, disabled, and removed without deleting their source repos.
Gmail and Calendar permissions are tiered for read, compose/write, and destructive actions.
MCP servers stay disabled until tested. External tools are namespaced, destructive MCP tools require approval, and broken servers degrade to diagnostics instead of blocking startup.
Prompt-injection defense scans tool outputs and user inputs for instruction override attempts, role impersonation, data exfiltration, encoding evasion, and social engineering patterns.

Architecture

Row-Bot is organized around reasoning, orchestration, and work: context assembly, memory, workflows, channels, Designer Studio, Developer Studio, plugin/MCP boundaries, and safety controls.

Explore the visual architecture gallery: docs/architecture.html

Read the full architecture reference: docs/ARCHITECTURE.md

<table> <tr> <td align="center"><a href="docs/Core_Agent_Arch.png"><img src="docs/Core_Agent_Arch.png" width="360" alt="Row-Bot core agent architecture"></a> Core Agent</td> <td align="center"><a href="docs/Context_Arch.png"><img src="docs/Context_Arch.png" width="360" alt="Row-Bot context architecture"></a> Context Assembly</td> </tr> <tr> <td align="center"><a href="docs/Knowledge_Graph_Arch.png"><img src="docs/Knowledge_Graph_Arch.png" width="360" alt="Row-Bot knowledge graph architecture"></a> Knowledge Graph</td> <td align="center"><a href="docs/Workflows_Arch.png"><img src="docs/Workflows_Arch.png" width="360" alt="Row-Bot background workflow architecture"></a> Background Workflows</td> </tr> <tr> <td align="center"><a href="docs/Multi_Channel_Arch.png"><img src="docs/Multi_Channel_Arch.png" width="360" alt="Row-Bot multi-channel architecture"></a> Multi-Channel Runtime</td> <td align="center"><a href="docs/Designer_Studio_Arch.png"><img src="docs/Designer_Studio_Arch.png" width="360" alt="Row-Bot Designer Studio architecture"></a> Designer Studio</td> </tr> <tr> <td align="center"><a href="docs/Developer_Studio_Arch.png"><img src="docs/Developer_Studio_Arch.png" width="360" alt="Row-Bot Developer Studio architecture"></a> Developer Studio</td> <td align="center"><a href="docs/Skills_System_Arch.png"><img src="docs/Skills_System_Arch.png" width="360" alt="Row-Bot skills system architecture"></a> Skills System</td> </tr> <tr> <td align="center"><a href="docs/Safety_Privacy_Arch.png"><img src="docs/Safety_Privacy_Arch.png" width="360" alt="Row-Bot safety privacy and control architecture"></a> Safety, Privacy & Control</td> <td align="center"><a href="docs/Self_Evolution_Arch.png"><img src="docs/Self_Evolution_Arch.png" width="360" alt="Row-Bot self-evolution architecture"></a> Self-Evolution</td> </tr> </table>

System Requirements

Setup	Minimum	Recommended
Local model runtime	Windows 10/11 64-bit, macOS 12+, or glibc Linux x86_64; Python 3.11+; 8 GB RAM for 8B models; about 5 GB disk for the app and one small model; internet for install and model download.	16 to 32 GB RAM for 14B to 30B models; NVIDIA GPU with 8+ GB VRAM or Apple Silicon for much faster inference; 20+ GB disk for multiple or larger models.
Provider/custom models only	Windows 10/11 64-bit, macOS 12+, or glibc Linux x86_64; Python 3.11+; 4 GB RAM; about 1 GB disk; internet for provider inference.	No GPU required. Use this path if you do not want local model downloads.
Developer Sandbox	Docker Desktop or a compatible Docker/Podman runtime.	Optional. Developer Studio also works with local execution in the selected repo.

Your default Brain model is set by the setup wizard. If you choose the local path, Row-Bot uses one of the models already exposed by your local runtime; 14B-class models are recommended for stronger agent/tool behavior, while smaller 8B-class models are better for 8 GB machines. Hosted and custom endpoint setups can skip local model downloads entirely.

From Source

Install Ollama first if you want Row-Bot's supported local model runtime. Provider-only and custom-endpoint setups can skip local model downloads.

bash
git clone https://github.com/siddsachar/row-bot.git
cd row-bot
python -m venv .venv

Activate the environment:

bash
# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Install dependencies and launch:

bash
pip install -r requirements.txt
python launcher.py

On Windows and macOS, launcher.py starts the tray icon and opens the app on the first available local port, normally http://localhost:8080. On Linux it opens in the browser without a tray by default. If port 8080 is busy, Row-Bot picks the next free port.

Headless Linux/server mode:

bash
python launcher.py --server --no-open --port 8080

Direct app launch:

bash
python app.py

Direct launches default to http://localhost:8080. Set ROW_BOT_PORT to choose a different port.

Recovery helpers:

bash
python launcher.py --reset-tasks-db
python launcher.py --reset-db
python launcher.py --restore-data

These commands back up local SQLite files before recreating or restoring known task, memory, and thread databases.

Privacy

Local model runs stay on your machine. Documents, memories, conversations, knowledge graph data, workflows, logs, and user settings are stored locally under ~/.row-bot or the platform-specific Row-Bot app data paths used by the installer. Migrated Thoth 3.x data is copied into Row-Bot locations; the original Thoth data is left in place.

Provider and custom models are opt-in. When selected, the current conversation, model-visible tool context, and tool results are sent to that endpoint. Memories, documents, files, graph data, and other conversations stay local unless you explicitly include them in the current conversation or expose them through a tool result. Memory recall happens locally before any selected memory is inserted into the active turn.

Developer Studio only touches repos you link or clone. Local execution runs in that repo. Docker Sandbox runs in a shadow copy and requires explicit import before changing the real repo. Skills Hub imports and Custom Tools are opt-in, testable or reviewable, removable, and only affect normal chat after you enable or promote them.

Row-Bot does not require a Row-Bot account, and there is no Row-Bot-hosted middleman for provider calls.